mbtiles

Node.js utilities and tilelive integration for the MBTiles format.

Installation

npm install @mapbox/mbtiles

varMBTiles=require('@mapbox/mbtiles');

API

Constructor

All MBTiles instances need to be constructed before any of the methods become available. NOTE: All methods described below assume you've taken this step.

newMBTiles('./path/to/file.mbtiles?mode={ro, rw, rwc}',function(err,mbtiles){console.log(mbtiles)// mbtiles object with methods listed below});

The mode query parameter is a opening flag of mbtiles. It is optional, default as rwc. Available flags are:

• ro: readonly mode, will throw error if the mbtiles does not exist.
• rw: read and write mode, will throw error if the mbtiles does not exist.
• rwc: read, write and create mode, will create a new mbtiles if the mbtiles does not exist.

Reading

getTile(z, x, y, callback)

Get an individual tile from the MBTiles table. This can be a raster or gzipped vector tile. Also returns headers that are important for serving over HTTP.

mbtiles.getTile(z,x,y,function(err,data,headers){// `data` is your gzipped buffer - use zlib to gunzip or inflate});

getInfo(callback)

Get info of an MBTiles file, which is stored in the metadata table. Includes information like zoom levels, bounds, vector_layers, that were created during generation. This performs fallback queries if certain keys like bounds, minzoom, or maxzoom have not been provided.

mbtiles.getInfo(function(err,info){console.log(info);// info});

getGrid(z, x, y, callback)

Get a UTFGrid tile from the MBTiles table.

mbtiles.getGrid(z,x,y,function(err,data){// continue onwards});

Writing

startWriting AND stopWriting

In order to write a new (or currently existing) MBTiles file you need to "start" and "stop" writing. First, construct the MBTiles object.

mbtiles.startWriting(function(err){// start writing with mbtiles methods (putTile, putInfo, etc)mbtiles.stopWriting(function(err){// stop writing to your mbtiles object});});

putTile(z, x, y, buffer, callback)

Add a new tile buffer to a specific ZXY. This can be a raster tile or a gzipped vector tile (we suggest using require('zlib') to gzip your tiles).

varzlib=require('zlib');zlib.gzip(fs.readFileSync('./path/to/file.mvt'),function(err,buffer){mbtiles.putTile(0,0,0,buffer,function(err){// continue onward});});

putInfo(data, callback)

Put an information object into the metadata table. Any nested JSON will be stringified and stored in the "json" row of the metadata table. This will replace any matching key/value fields in the table.

varexampleInfo={"name": "hello-world","description":"the world in vector tiles","format":"pbf","version": 2,"minzoom": 0,"maxzoom": 4,"center": "0,0,1","bounds": "-180.000000,-85.051129,180.000000,85.051129","type": "overlay","json": `{"vector_layers": [ { "id": "${layername}", "description": "", "minzoom": 0, "maxzoom": 4, "fields": {} } ] }`};mbtiles.putInfo(exampleInfo,function(err){// continue onward});

putGrid(z, x, y, grid, callback)

Inserts a UTFGrid tile into the MBTiles store. Grids are in JSON format.

varfs=require('fs');vargrid=JSON.parse(fs.readFileSync('./path/to/grid.json','utf8'));mbtiles.putGrid(0,0,0,grid,function(err){// continue onward});

Hook up to tilelive

When working at scale, node-mbtiles is meant to be used within a Tilelive ecosystem. For example, you could set up an MBTiles file as a "source" and an S3 destination as a "sink" (using tilelive-s3). Assuming you have a system set up with an mbtiles:// protocol that points to a specific file and authorized to write to the s3 bucket:

vartilelive=require('@mapbox/tilelive');varMBTiles=require('@mapbox/mbtiles');vars3=require('@mapbox/tilelive-s3');s3.registerProtocols(tilelive);MBTiles.registerProtocols(tilelive);varsourceUri='mbtiles:///User/hello/path/to/file.mbtiles';varsinkUri='s3://my-bucket/tiles/{z}/{x}/{y}';// load the mbtiles sourcetilelive.load(sourceUri,function(err,src){// load the s3 sinktilelive.load(sinkUri,function(err,dest){varoptions={};// prepare options for tilelive copyoptions.listScheme=src.createZXYStream();// create ZXY stream from mbtiles// now copy all tiles to the destinationtilelive.copy(src,dst,options,function(err){console.log('tiles are now on s3!');});});});

Test

npm test