{"id":13426311,"url":"https://github.com/mapbox/node-mbtiles","last_synced_at":"2025-03-15T21:31:05.762Z","repository":{"id":1478730,"uuid":"1722835","full_name":"mapbox/node-mbtiles","owner":"mapbox","description":"mbtiles utility, renderer, and storage backend for tilelive","archived":false,"fork":false,"pushed_at":"2024-06-28T10:39:25.000Z","size":4420,"stargazers_count":287,"open_issues_count":12,"forks_count":84,"subscribers_count":125,"default_branch":"master","last_synced_at":"2024-10-30T00:33:15.427Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mapbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-05-09T14:21:27.000Z","updated_at":"2024-10-25T21:51:25.000Z","dependencies_parsed_at":"2024-11-09T11:32:49.145Z","dependency_job_id":"71ad0a5c-efdc-41e9-8e2f-7c56936acf03","html_url":"https://github.com/mapbox/node-mbtiles","commit_stats":{"total_commits":318,"total_committers":26,"mean_commits":12.23076923076923,"dds":0.7389937106918238,"last_synced_commit":"03220bc2fade2ba197ea2bab9cc44033f3a0b37e"},"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fnode-mbtiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fnode-mbtiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fnode-mbtiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fnode-mbtiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mapbox","download_url":"https://codeload.github.com/mapbox/node-mbtiles/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243624091,"owners_count":20321028,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T00:01:31.573Z","updated_at":"2025-03-15T21:31:03.766Z","avatar_url":"https://github.com/mapbox.png","language":"JavaScript","readme":"# mbtiles\n\nNode.js utilities and [tilelive](https://github.com/mapbox/tilelive.js) integration for the [MBTiles](https://github.com/mapbox/mbtiles-spec) format.\n\n[![Build Status](https://travis-ci.com/mapbox/node-mbtiles.svg?branch=master)](https://travis-ci.com/mapbox/node-mbtiles)\n[![Build status](https://ci.appveyor.com/api/projects/status/04wbok5rs3eroffe)](https://ci.appveyor.com/project/Mapbox/node-mbtiles)\n\n# Installation\n\n```\nnpm install @mapbox/mbtiles\n```\n\n```javascript\nvar MBTiles = require('@mapbox/mbtiles');\n```\n\n# API\n\n### Constructor\n\nAll MBTiles instances need to be constructed before any of the methods become available. *NOTE: All methods described below assume you've taken this step.*\n\n```javascript\nnew MBTiles('./path/to/file.mbtiles?mode={ro, rw, rwc}', function(err, mbtiles) {\n  console.log(mbtiles) // mbtiles object with methods listed below\n});\n```\n\nThe `mode` query parameter is a opening flag of mbtiles. It is optional, default as `rwc`. Available flags are:\n\n- `ro`: readonly mode, will throw error if the mbtiles does not exist.\n- `rw`: read and write mode, will throw error if the mbtiles does not exist.\n- `rwc`: read, write and create mode, will create a new mbtiles if the mbtiles does not exist.\n\n### Reading\n\n**`getTile(z, x, y, callback)`**\n\nGet 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.\n\n```javascript\nmbtiles.getTile(z, x, y, function(err, data, headers) {\n  // `data` is your gzipped buffer - use zlib to gunzip or inflate\n});\n```\n\n**`getInfo(callback)`**\n\nGet 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.\n\n```javascript\nmbtiles.getInfo(function(err, info) {\n  console.log(info); // info\n});\n```\n\n**`getGrid(z, x, y, callback)`**\n\nGet a [UTFGrid](https://github.com/mapbox/utfgrid-spec) tile from the MBTiles table.\n\n```javascript\nmbtiles.getGrid(z, x, y, function(err, data) {\n  // continue onwards\n});\n```\n\n### Writing\n\n**`startWriting`** AND **`stopWriting`**\n\nIn order to write a new (or currently existing) MBTiles file you need to \"start\" and \"stop\" writing. First, [construct](#constructor) the MBTiles object.\n\n```javascript\nmbtiles.startWriting(function(err) {\n  // start writing with mbtiles methods (putTile, putInfo, etc)\n  mbtiles.stopWriting(function(err) {\n    // stop writing to your mbtiles object\n  });\n});\n```\n\n**`putTile(z, x, y, buffer, callback)`**\n\nAdd 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).\n\n```javascript\nvar zlib = require('zlib');\n\nzlib.gzip(fs.readFileSync('./path/to/file.mvt'), function(err, buffer) {\n  mbtiles.putTile(0, 0, 0, buffer, function(err) {\n    // continue onward\n  });\n});\n```\n\n**`putInfo(data, callback)`**\n\nPut 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.\n\n```javascript\nvar exampleInfo = {\n  \"name\": \"hello-world\",\n  \"description\":\"the world in vector tiles\",\n  \"format\":\"pbf\",\n  \"version\": 2,\n  \"minzoom\": 0,\n  \"maxzoom\": 4,\n  \"center\": \"0,0,1\",\n  \"bounds\": \"-180.000000,-85.051129,180.000000,85.051129\",\n  \"type\": \"overlay\",\n  \"json\": `{\"vector_layers\": [ { \"id\": \"${layername}\", \"description\": \"\", \"minzoom\": 0, \"maxzoom\": 4, \"fields\": {} } ] }`\n};\n\nmbtiles.putInfo(exampleInfo, function(err) {\n  // continue onward\n});\n```\n\n**`putGrid(z, x, y, grid, callback)`**\n\nInserts a [UTFGrid](https://github.com/mapbox/utfgrid-spec) tile into the MBTiles store. Grids are in JSON format.\n\n```javascript\nvar fs = require('fs');\nvar grid = JSON.parse(fs.readFileSync('./path/to/grid.json', 'utf8'));\nmbtiles.putGrid(0, 0, 0, grid, function(err) {\n  // continue onward\n});\n```\n\n## Hook up to tilelive\n\nWhen working at scale, node-mbtiles is meant to be used within a [Tilelive](https://github.com/mapbox/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:\n\n```javascript\nvar tilelive = require('@mapbox/tilelive');\nvar MBTiles = require('@mapbox/mbtiles');\nvar s3 = require('@mapbox/tilelive-s3');\n\ns3.registerProtocols(tilelive);\nMBTiles.registerProtocols(tilelive);\n\nvar sourceUri = 'mbtiles:///User/hello/path/to/file.mbtiles';\nvar sinkUri = 's3://my-bucket/tiles/{z}/{x}/{y}';\n\n// load the mbtiles source\ntilelive.load(sourceUri, function(err, src) {\n  // load the s3 sink\n  tilelive.load(sinkUri, function(err, dest) {\n\n    var options = {}; // prepare options for tilelive copy\n    options.listScheme = src.createZXYStream(); // create ZXY stream from mbtiles\n\n    // now copy all tiles to the destination\n    tilelive.copy(src, dst, options, function(err) {\n      console.log('tiles are now on s3!');\n    });\n  });\n});\n```\n\n# Test\n\n```\nnpm test\n```\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fnode-mbtiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmapbox%2Fnode-mbtiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fnode-mbtiles/lists"}