mbtiles

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

Installation

npm install @mapbox/mbtiles

var MBTiles = 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.

new MBTiles('./path/to/file.mbtiles', function(err, mbtiles) {
  console.log(mbtiles) // mbtiles object with methods listed below
});

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).

var zlib = 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.

var exampleInfo = {
  "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.

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

Test

npm test