MBTiles generator

[Version: 0.3.0]

A project designed to provide a simple API for generating MBTiles for a bounding box, fetching data from a remote tile-server.

Warning: this tool can generate heavy load on tile-servers. Use it responsibly.

Features

REST API or command line tool
Lightweight, easily configurable
Multiple map providers supported (osm and bing)
Additional providers can easily be declared

Howto

Install nodejs
in the repository root, type npm install
To launch the server mode, execute ./start.sh or ./start-debug.sh
To use the cli, execute ./run.sh --left=2.31760654 --bottom=48.8243829 --right=2.358607 --top=48.8513625

Configuration

To configure your application, edit the conf/Conf.js file.
The file may look like this

module.exports = {
  "tileServer": {"type": "...", "endpoint": "..."}, // Tile server specs
  "minZoom": 5, // Minimum zoom level to compute for an mbtile.
  "maxZoom": 17, // Maximum zoom level to compute for an mbtile
  "timeout": 300000, // Http Timeout in milliseconds (Server-mode only)
  "maxArea": 16, // Maximum MBTiles covering area in square kilometers. Will reject all oversized requests. 0 to disable.
};

Two tile providers are currently supported :
OpenStreetMap: In this case, provide the following tileServer (replace your endpoint):

"tileServer": {"type": "osm", "endpoint": "http://your-tileserver/{z}/{x}/{y}.png"}

Layers are also supported, using them as:

"tileServer": {"type": "osm", "endpoint": "http://your-tileserver/{layer}/{z}/{x}/{y}.png"}

Bing: In this case, provide the following tileServer (replace your style and ApiKey):

"tileServer": {
"type": "bing", 
"endpoint": "http://dev.virtualearth.net/REST/V1/Imagery/Metadata/Aerial?mapVersion=v1&output=json&key=myApiKey",
"culture": "fr"
}

Server API

The server runs on port 2999 and listens to the following endpoints:

Synchronous endpoints

[GET]/mbtiles:
Requires 4 parameters: left, bottom, right, top.
Optional parameter: layer.
Returns: the mbtiles file Example: http://localhost:2999/mbtiles?left=2.31760654&bottom=48.8243829&right=2.358607&top=48.8513625 Will synchronously prepare your mbtiles file and return it in the http response when done. This process can take up to a few minutes.

Asynchronous endpoints

[GET]/mbtiles/async:
Requires 4 parameters: left, bottom, right, top.
Optional parameter: layer.
Returns: a json {"token": "your-token"}
Example: http://localhost:2999/mbtiles/async?left=2.31760654&bottom=48.8243829&right=2.358607&top=48.8513625
Will asynchronously launch your mbtiles computation and return a unique token.

[GET]/mbtiles/status/:token:
Requires one path variable: token (your token provided in the previous endpoint)
Returns: {"status": "generating|done|downloaded", "progress":11} the status and the progress percentage.
Example: http://localhost:2999/mbtiles/status/969396ca-9747-469b-b0a0-32da12dc4ab6
Retrieve the status of your current mbtiles computation

[GET]/mbtiles/download/:token:
Requires one path variable: token (your token provided in the previous endpoint)
Returns: the mbtiles file
Example: http://localhost:2999/mbtiles/download/969396ca-9747-469b-b0a0-32da12dc4ab6
Retrieve the computed mbtiles file

CLI

The CLI needs 4 parameters to be provided to work: --left, --bottom, --right, --top.
It supports one optional parameter: --layer.
Use ./run.sh --help for more information.

Docker runtime

To run the MBTiles generator in an even simpler environment, simply execute:

docker run -d -p 2999:2999 -e "APP_MODE=server" -e "TILESERVER_TYPE=osm" -e "TILESERVER_ENDPOINT=http://mytileserver.org/{z}/{x}/{y}.png" -e "APP_TIMEOUT=300" -e "APP_MINZOOM=3" -e "APP_MAXZOOM=17" -e "APP_MAXAREA=16" mapsquare/mbtiles-generator-server

ENV variables:

APP_MODE: the execution mode. Valid values: server, command. server will launch a server on port 2999, command creates the requested MBTiles and outputs in the container /opt/app/data folder.
TILESERVER_TYPE: the tile provider. Valid values: osm, bing.
TILESERVER_ENDPOINT: depends on the provider. see app/mapper files and examples.
APP_TIMEOUT: timeout in seconds for server mode.
APP_MAXAREA: max supported area in square kilometers for an MBTiles file.
APP_MINZOOM: minzoom to compute the MBTiles.
APP_MAXZOOM: maxzoom to compute the MBTiles.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

jawg / mbtiles-generator

readme