Awesome
serialtiles-spec
serialtiles is a specification for streaming tile uploads. This format makes it possible to transfer large tilesets from MBTiles or other sources in a streaming manner: this allows both the sender and receiver to process the upload without holding the entire thing in memory or waiting for completion.
Unlike MBTiles, serialtiles is a text format, not a binary format: it is a transmission of line-delimited JSON. Binary contents of tiles, like raster images and protocol buffer-encoded vectors, are base64 encoded in order to be safe for this transport.
Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Definitions
JavaScript Object Notation (JSON), and the terms object, name, value, array, number, true, false, and null are to be interpreted as defined in [RFC7159].
Specification
serialtiles is a stream and thus is documented in order that it appears. Any other order is invalid. serialtiles is a subset of line-delimited JSON: each item is separated by a linebreak.
Header
The stream MUST begin with the literal text
JSONBREAKFASTTIME
This header declares that the stream contains serialtiles data.
TileJSON
The second item in the stream MUST be a valid TileJSON
object, stringified and wrapped in a JSON object under the member tilejson
.
{"tilejson":"STRINGIFIED TILEJSON CONTENT"}
Tiles
Each tile is a JSON object that contains z
, x
, y
, and buffer
members.
The z
x
and y
members represent a Z/X/Y tile in the slippy map tilenames
scheme, in the Web Mercator map projection.
The buffer
member contains tile data. The encoding of map data is as such:
- Raster data, including PNG, JPEG, GIF, WebP is base64 encoded
- Protocol buffer data, including Mapbox Vector Tiles, is gzip compressed and then base64 encoded.
{"z":10,"x":1,"y":2,"buffer":""}
Examples
Vector Tiles (vector tile data)
Serialtiles is often used to transfer Mapbox Vector Tiles, which are protocol buffer-encoded. These tiles are additionally required to be gzipped & base64-encoded for transmission through serialtiles because serialtiles is not a binary format.
JSONBREAKFASTTIME
{"tilejson":"info object"}
{"z":0,"x":0,"y":0,"buffer":"base64-encoded, gzipped tile data"}
{"z":1,"x":0,"y":0,"buffer":"base64-encoded, gzipped tile data"}
{"z":1,"x":1,"y":0,"buffer":"base64-encoded, gzipped tile data"}
{"z":1,"x":0,"y":1,"buffer":"base64-encoded, gzipped tile data"}
{"z":1,"x":1,"y":1,"buffer":"base64-encoded, gzipped tile data"}
Raster Images (png, webp, gif, jpg)
Unlike vector tiles, raster images are not gzipped: they are only base64 encoded.
JSONBREAKFASTTIME
{"tilejson":"info object"}
{"z":0,"x":0,"y":0,"buffer":"base64-encoded data"}
{"z":1,"x":0,"y":0,"buffer":"base64-encoded data"}
{"z":1,"x":1,"y":0,"buffer":"base64-encoded data"}
{"z":1,"x":0,"y":1,"buffer":"base64-encoded data"}
{"z":1,"x":1,"y":1,"buffer":"base64-encoded data"}
Examples
- make_cereal: example of generating serialtiles from node.js
Implementations
An unofficial list of implementations is maintained in the wiki of the serialtiles-spec GitHub project