Bikeshare stations – incremental updates
Incremental updates are in public beta. The feature is subject to changes.
Source data can often have updates. In this example, the bikeshare stations dataset changes in real time. Incremental updates enable updating and re-processing a specific part of an existing tileset instead of updating and re-processing the entire tileset.
In this example, our full dataset has 2,754 bikeshare stations, but we will use incremental updates to update only three stations. Without incremental updates, MTS would re-process and re-tile all 2,754 stations in the tileset, even the stations that did not change.
The tileset on the left shows the initial version of the bikeshare stations. The incrementally updated tileset on the right shows two stations with changed available_bikes and a single station removed.
Components of an incremental update tileset
Recipe
The simplest recipe you can write for a tileset that uses incremental updates includes three top-level fields:
versionof the recipe specificationlayersobjectincrementalflag set totrue
{
"version": 1,
"incremental": true,
"layers": {
"stations": {
"minzoom": 8,
"maxzoom": 16,
"source": "mapbox://tileset-source/{username}/bikeshare-stations"
}
}
}
Tileset source
Incremental update tilesets need a tileset source with stable unique feature IDs. This is because when making an incremental update, MTS relies on feature IDs to make changes.
Changeset GeoJSON
A changeset is one or more line-delimited GeoJSON files uploaded to a Mapbox account that updates a layer in an existing tileset. Changesets allow you to create, change, and delete individual GeoJSON features without re-processing your entire tileset.
The changeset below has three points representing bike stations. The first two GeoJSON features update the number of available bikes in their bikeshare station. The last GeoJSON feature is a bikeshare station that will be deleted ("delete": true). The id field ("id": "8786317244026698") is the stable feature ID that MTS uses for incremental updates to properly work.
{"id":"7857471448093814","type":"Feature","geometry":{"type":"Point","coordinates":[4.334831,50.897522]},"properties":{"number":280,"name":"280 - HEYSEL / HEISEL","address":"HEYSEL / HEISEL - AVENUE DE L'IMPERATRICE CHARLOTTE / KEIZERIN CHARLOTTELAAN","banking":"False","bonus":"False","status":"OPEN","contract_name":"Bruxelles-Capitale","bike_stands":25,"available_bike_stands":16,"available_bikes":27,"last_update":"2025-04-23T17:09:26+03:00"}}
{"id":"7074671582743743","type":"Feature","geometry":{"type":"Point","coordinates":[4.331902,50.894005]},"properties":{"number":278,"name":"278 - STADE / STADIUM","address":"STADE / STADIUM - AVENUE HOUBA DE STROOPER / HOUBA DE STROOPERLAAN","banking":"False","bonus":"False","status":"OPEN","contract_name":"Bruxelles-Capitale","bike_stands":25,"available_bike_stands":13,"available_bikes":32,"last_update":"2025-04-23T17:12:07+03:00"}}
{"delete":true,"id":"8786317244026698"}
Creating an incremental bikeshare stations tileset
This section describes how to use the Tilesets CLI to generate a tileset enabled for incremental updates and then incrementally update it.
- Download the JCDecaux bike stations data you’ll use to create the incremental tileset:
- Create a tileset source named
bikeshare-stationswith the data you downloaded.
$tilesets upload-source username bikeshare-stations ~/your/local/path/jcdecaux-bike-stations-data-rt.geojson
- Create your recipe as a local JSON file (for example,
bikeshare-stations-recipe.json) with"incremental": trueand yourbikeshare-stationstileset source. Also use the ID expression and hash operation to generate a unique feature ID for each GeoJSON feature because the bikeshare stations dataset does not have feature IDs.
{
"version": 1,
"incremental": true,
"layers": {
"stations": {
"minzoom": 8,
"maxzoom": 16,
"source": "mapbox://tileset-source/{username}/bikeshare-stations",
"features": {
"id": ["hash", ["concat", ["get", "number"], ["get", "name"]]]
}
}
}
}
- Create an initial tileset with the tileset ID
username.bikeshare-stationsusing your recipe and name it“Bikeshare stations”.
$tilesets create username.bikeshare-stations --recipe ~/your/local/path/bikeshare-stations-recipe.json --name "Bikeshare stations"
- Now you’re ready to publish your tileset and start processing your data.
$tilesets publish username.bikeshare-stations
Preview your initial tileset
- You can now see your tileset using the Tilesets Explorer.
Incrementally update the tileset
- Create a file named
bikeshare-stations-changeset.ldgeojsonusing the changeset below to change theavailable_bikesin two stations and to delete one station.
{"id":"7857471448093814","type":"Feature","geometry":{"type":"Point","coordinates":[4.334831,50.897522]},"properties":{"number":280,"name":"280 - HEYSEL / HEISEL","address":"HEYSEL / HEISEL - AVENUE DE L'IMPERATRICE CHARLOTTE / KEIZERIN CHARLOTTELAAN","banking":"False","bonus":"False","status":"OPEN","contract_name":"Bruxelles-Capitale","bike_stands":25,"available_bike_stands":16,"available_bikes":27,"last_update":"2025-04-23T17:09:26+03:00"}}
{"id":"7074671582743743","type":"Feature","geometry":{"type":"Point","coordinates":[4.331902,50.894005]},"properties":{"number":278,"name":"278 - STADE / STADIUM","address":"STADE / STADIUM - AVENUE HOUBA DE STROOPER / HOUBA DE STROOPERLAAN","banking":"False","bonus":"False","status":"OPEN","contract_name":"Bruxelles-Capitale","bike_stands":25,"available_bike_stands":13,"available_bikes":32,"last_update":"2025-04-23T17:12:07+03:00"}}
{"delete":true,"id":"8786317244026698"}
- Create a changeset named
bikeshare-stations-changesetusing the line-delimited GeoJSON file.
$tilesets upload-changeset username bikeshare-stations-changeset ~/your/local/path/bikeshare-stations-changeset.ldgeojson
- Publish the changeset to incrementally update the tileset
Create a bikeshare-stations-changesets.json configuration file containing the layers and changesets for the incremental update.
{
"layers": {
"stations": {
"changeset": "mapbox://tileset-changeset/{username}/bikeshare-stations-changeset"
},
}
}
Use the bikeshare-stations-changesets.json file in your local path to publish the changeset.
$tilesets publish-changesets username.bikeshare-stations /your/local/path/bikeshare-stations-changesets.json
Preview your incrementally updated tileset
- You can see your tileset using the Tilesets Explorer.
Note that tileset changes on cached tiles won't be visible for at least 12 hours due to the CDN cache default. For more information, see the Maps API caching guide.