MBTiles Specification
MBTiles is a specification for storing tiled map data in SQLite databases for immediate usage and for transfer. MBTiles files, known as tilesets, must implement the specification below to ensure compatibility with devices.
UTFGrid
The MBTiles specification previously contained the UTFGrid specification. It was removed in version 1.2 and moved into its own specification with synced version numbers - so MBTiles 1.2 is compatible with UTFGrid 1.2. The specs integrate but do not require each other for compliance.
Versions
Changelog
Roadmap
- The format will switch tile ordering to the XYZ schema popularized by OpenStreetMap and away from the Tile Map Service specification.
1.1
name='format'row required inmetadatatable.name='bounds'row suggested inmetadatatable.- optional UTFGrid-based interaction spec.
Concept
MBTiles is a compact, restrictive specification. It supports only tiled data, including image tiles and interactivity grid tiles. Only the Spherical Mercator projection is supported for presentation - tile display - and only latitude-longitude coordinates are supported for metadata such as bounds and centers.
It is a minimum specification - only specifying the ways in which data must be retrievable. Thus MBTiles files can internally compress and optimize data, and construct views that adhere to the MBTiles specification.
Unlike Spatialite, GeoJSON, and Rasterlite, MBTiles is not raw data storage - it is storage for presentational data, like rendered map tiles.
One MBTiles file represents a single tileset, optionally including grids of interactivity data. Multiple tilesets - layers, or maps in other terms, can be represented by multiple MBTiles files.
Implementations.
License
The text of this specification is licensed under a Creative Commons Attribution 3.0 United States License. However, the use of this spec in products and code is entirely free: there are no royalties, restrictions, or requirements.
Authors
- Tom MacWright (tmcw)
- Will White (willwhite)
- Konstantin Kaefer (kkaefer)
- Justin Miller (incanus)
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
MBTiles 1.2
Sub-sections:
- Interaction: HTTP endpoints needed for implementing interactivity
- UTFGrid: This specification relies on UTFGrid 1.2 for interactivity.
Abstract
MBTiles is a specification for storing tiled map data in SQLite databases for immediate usage and for transfer. MBTiles files, known as tilesets, must implement the specification below to ensure compatibility with devices.
Database Specifications
Tilesets are expected to be valid SQLite databases of version 3.0.0 or higher. Only core SQLite features are permitted; tilesetscannot require extensions.
MBTiles databases can optionally use the officially assigned magic number to be easily identified as MBTiles.
Database
Note: the schemas outlined are meant to be followed as interfaces. SQLite views that produce compatible results are equally valid. For convenience, this specification refers to tables and virtual tables (views) as tables.
Metadata
Schema
The database is required to contain a table or view named metadata.
This table must yield exactly two columns named name and value. A typical create statement for the metadata table:
CREATE TABLE metadata (name text, value text);
Content
The metadata table is used as a key/value store for settings. Five keys are required:
name: The plain-english name of the tileset.type:overlayorbaselayerversion: The version of the tileset, as a plain number.description: A description of the layer as plain text.format: The image file format of the tile data:pngorjpg
One row in metadata is suggested and, if provided, may enhance performance.
bounds: The maximum extent of the rendered map area. Bounds must define an area covered by all zoom levels. The bounds are represented inWGS:84- latitude and longitude values, in the OpenLayers Bounds format - left, bottom, right, top. Example of the full earth:-180.0,-85,180,85.attribution: An attribution string, which explains in English (and HTML) the sources of data and/or style for the map.
Several additional keys are supported for tilesets that implement UTFGrid-based interaction.
Tiles
Schema
The database is required to contain a table named tiles.
The table must yield four columns named zoom_level, tile_column, tile_row, and tile_data. A typical create statement for the tiles table:
CREATE TABLE tiles (zoom_level integer, tile_column integer, tile_row integer, tile_data blob);
Content
The tiles table contains tiles and the values used to locate them. The zoom_level, tile_column, and tile_row columns follow the Tile Map Service Specification in their construction, but in a restricted form:
The global-mercator (aka Spherical Mercator) profile is assumed
The tile_data blob column contains raw image data in binary.
A subset of image file formats are permitted:
pngjpg
Grids
See the UTFGrid specification for implementation details of grids and interaction metadata itself: the MBTiles specification is only concerned with storage.
Schema
The database can have optional tables named grids, grid_data.
The grids table must yield four columns named zoom_level, tile_column, tile_row, and grid. A typical create statement for the grids table:
CREATE TABLE grids (zoom_level integer, tile_column integer, tile_row integer, grid blob);
The grid_data table must yield five columns named zoom_level, tile_column, tile_row, key_name, and key_json. A typical create statement for the grid_data table:
CREATE TABLE grid_data (zoom_level integer, tile_column integer, tile_row integer, key_name text, key_json text);
Content
The grids table contains UTFGrid data, gzip compressed.
The grid_data table contains grid key to value mappings, with values encoded as JSON objects.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Implementations
Brendan Ward edited this page on Sep 8 · 65 revisions
Pages 1 * **[Implementations](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmapbox%2Fmbtiles-spec%2Fwiki%2FImplementations)** Clone this wiki locally [Clone in Desktop](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fwindows.github.com%2F) #### 1.1 Compliant * [Mapbox](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fmapbox.com%2F) * [TileStream](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fgithub.com%2Fmapbox%2Ftilestream) * [Mapbox iOS SDK](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmapbox%2Fmapbox-ios-sdk) ([example](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmapbox%2Fmapbox-ios-example)) * [GDAL](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fwww.gdal.org%2Ffrmt_mbtiles.html) * node.js: [mbtiles-generator](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmapsquare%2Fmbtiles-generator) * python: [rio-mbtiles](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmapbox%2Frio-mbtiles) (write) * python: [mbutil](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmapbox%2Fmbutil) (read/write) * python: [landez](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmakinacorpus%2Flandez) (read/write) (uses mbutil) * python: [TileStache](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Ftilestache.org%2F) ([code](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmigurski%2FTileStache%2Fblob%2Fmaster%2FTileStache%2FMBTiles.py)) (read/write) - a full, high-quality tile server * python: [python-mbtiles](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fperrygeo%2Fpython-mbtiles) * python: [TileCloud](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Ftwpayne%2Ftilecloud) * python: [servembtiles](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmonkut%2Fservembtiles) a pure python3 wsgi application for serving MBTiles. * python: [gdal2mbtiles](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fecometrica%2Fgdal2mbtiles) - convert GDAL-readable datasets into an MBTiles file (write) * python: [tpkutils](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fconsbio%2Ftpkutils) (write) - convert ArcGIS tile packages into MBtiles 1.1. * proprietary: [Arc2Earth](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fwww.arc2earth.com%2F) (write) * python: [mapproxy](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fmapproxy.org%2F) ([announcement](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fmapproxy.org%2Fblog%2Fnew-mapproxy-1.2.0-release%2F)) (read/write) * proprietary: [maperitive](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fmaperitive.net%2F) (write) * PHP: [mbtiles-generator](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2FHTML24%2Fmbtiles-generator) (read/write) * python [mbtiles2s3](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2FMinnPost%2Fmbtiles2s3) * objc: [osm2mbtiles](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Frpcarver%2Fosm2mbtiles) * C++: [tilemaker](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fsystemed%2Ftilemaker) (write vector tiles) #### Others * ruby: [silent\_cartographer](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fjwhitehorn%2Fsilent_cartographer) * python/Django: [django-mbtiles](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmakinacorpus%2Fdjango-mbtiles%2F) * objc: [MapDBImporter](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmapbox%2FMapDBImporter) (write) * java/android: [MBTilesDroidSpitter](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fdjcoin%2FMBTilesDroidSpitter) ([example](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fdjcoin%2FMBTilesDroidSpitterExampleSimple)) (read) * objc/iPhone: [Maptual](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fmaptual.com%2F) (read) * java/Android: [Locus](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Flocus.asamm.cz%2F) (read) * java/Android: [MapIt](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fmapit-gis.com%2F) (read) * Windows compatible viewer: [MBTilesViewer](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fviswaug.wordpress.com%2F2011%2F06%2F28%2Fmbtilesviewer%2F) (read) * java/Android: [Nutiteq SDK](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fwww.nutiteq.com%2Fandroid-mapping-api-sdk) * Python: [MBTiles-Extractor](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fpbarry%2FMBTiles-extractor) * Java/Processing: [Unfolding](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Funfoldingmaps.org%2F) (read) ([example](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Ftillnagel%2Funfolding%2Fblob%2Fmaster%2Fexamples%2Fde%2Ffhpotsdam%2Funfolding%2Fexamples%2FMBTilesMapApp.java)) * PHP: [tileserver-php](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fklokantech%2Ftileserver-php) * PHP: [MBTiles-PHP](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Finfostreams%2Fmbtiles-php) * PHP: [PHP-MBTiles-Server](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fbmcbride%2FPHP-MBTiles-Server) * PHP: [TilePhlox](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2FJohn5%2FTilePhlox) * ASP.NET: [tilecannon](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fsainsb%2Ftilecannon) * Python: [MBTiles-extractor](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fpbarry%2FMBTiles-extractor) * C++: [Example C++ mbtiler](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmapbox%2Fmbtiler) ### Applications * js: [TileMill](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fdevelopmentseed.github.com%2FTileMill%2F) (write) * [TileMill OS X](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fmapbox%2Ftilemill%2Fdownloads) QuickLook & Spotlight plugins (read) * [Portable Basemap Server](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgeopbs.codeplex.com%2F) An easy to use WPF application and has implemented map tile part of Esri’s “GeoServices REST Specification” and OGC WMTS specification (read/write) * C++: [osgEarth](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fosgearth.org%2F) (read) * iOS/Android/Web: [Fulcrum- mobile field data collection](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fwww.fulcrumapp.com%2F) (read) * C: [Viking](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fsourceforge.net%2Fprojects%2Fviking%2F) GPS Desktop application. Linux + Windows (read) * python: [QTiles](https://www.oschina.net/action/GoToLink?url=https%3A%2F%2Fgithub.com%2Fnextgis%2FQTiles) QGIS plugin (write) * Windows: [TilingTools](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fgeomixer.ru%2Findex.php%2Fru%2Fdocs%2Fmanual%2Ftilingtools) - raster to tiles (read/write) ### Websites * [MapTiler](https://www.oschina.net/action/GoToLink?url=http%3A%2F%2Fwww.maptiler.com%2F)
