Frequently Asked Questions
Answers to commonly asked questions for users of the Mapbox Tiling Service (MTS).
What is the difference between errors and warnings on an MTS tileset job?
Both errors and warnings are arrays in the response data from the GET /jobs/:job_id and GET /jobs endpoints. A tileset job will only have an errors array if it has failed, describing why it failed. A successful job will have a warnings array if one or more features were dropped from the resulting tileset.
There are gaps of missing data in my tiles
If you notice that your MTS tileset is missing points, lines, or polygons, it’s likely that MTS dropped some features because the layer size was approaching the maximum allowed size of 1250 KB. If you use the GET /jobs/:job_id endpoint for this tileset job, you will see warnings about how many tiles dropped features and a list of example tiles so you can diagnose the problem.
To avoid hitting the 1250 KB limit, you should reduce the number and size of features in each layer. You can do this by:
- Specifying
"tiles": { "id": null }to remove feature IDs from the output tiles. - Setting
"features": { "attributes": { "allowed_output": [ … ] } }to remove all but the needed attributes. - Using
"features": { "attributes": { "set": { … } } }to set the value of unneeded attributes tonull. - Using integer values for attributes instead of floating point or string values.
- Using the same attribute values between features instead of unique values.
- Using
"features": { "filter": … }with a[ "zoom" ]expression to reduce the number of features at low zoom levels. - Using
"tiles": { "union": [ … ] }to merge features with the same attributes into a single feature. - Setting
"tiles": { "extent": …, "buffer_size": … }to reduce the geometry resolution within tiles and the number of features mirrored from adjacent tiles. - Setting
"features": { "simplification": … }to reduce the geometric complexity of features.
If none of these options are practical for your data, or are not enough, you can specify a higher layer_size of up to 2500 in your recipe. You can find the necessary layer_size for your data and recipe by consulting the capped_list in the information about your tiling job.
My minzoom is different than expected
MTS tries to generate tiles for every requested zoom level. If the zoom levels in a tileset do not match the zoom levels in the corresponding recipe, this is due to features being filtered out based on the rules you have provided, which led to empty tiles at these zooms.
For example, if you specify a minzoom level of 6 but your filtering syntax only starts accepting features at zoom 8, once processing is complete MTS will dynamically set the tileset's minzoom to 8 since there are no tiles to be requested at zoom 6 or 7.
There are "notches" in my LineStrings at high zooms
Notches in LineStrings happen when high zoom tiles do not have buffers that are large enough. To avoid possible buffer-edge artifacts, set your buffer_size to something larger than the default of 0.5. The recommended value is 6.
The features in my vector tiles have different IDs than the features in my source data
Vector tiles only support integer-based identifiers. If you provide an ID in the tileset source in any format other than integers, MTS will generate an integer hash of this value to use as the feature ID.
If you need to keep the original source IDs, you can do either of the following:
- Use integer IDs in the source data.
- Save the original ID of the feature as an attribute in the vector tiles using the
setoption in your recipe.
A feature I expected to be in my new tileset isn't there
If a feature that you expected to see is not in the new tileset, it might have been dropped for one of the following reasons:
- The tileset source data was not valid GeoJSON. You can diagnose the problem by using the Tilesets CLI's
validate-sourcecommand to validate your source data. - The feature was filtered out by your recipe. For more information on how and why a recipe might filter out a feature, see the Mapbox Tiling Service recipe reference.
- The feature has been simplified away at certain zoom levels. For more information on feature simplification, see the Mapbox Tiling Service recipe reference.
I'm not able to use GeometryCollection features in my tileset source
Tileset sources do not support GeoJSON GeometryCollection features. If you have GeometryCollection features in your source data, you should split each of its sub-features into a unique, individual feature.
There are no features in my tileset when I click "zoom to data" in Mapbox Studio
Depending on how your data is distributed or the zoom range you choose, knowing where your data is can be a challenge. Mapbox Studio tries to help you visualize your data at the right location, but due to how it makes this calculation, you may not see any features if there are not any at the mathematical center of the tileset source used to create the tileset. If this occurs, you will need to manually click and drag the map to your feature locations, rather than being able to click "zoom to data".
Objects and arrays in feature properties are being dropped
According to the Mapbox vector tile spec, object and array values are not supported in feature.properties. Any non-primitive types included in feature.properties will be dropped when you publish your tileset source to MTS. To get around this issue, you can convert objects like below:
{
"foo": {
"bar": "hoge"
}
}
to
{
"foo.bar": "hoge"
}
For arrays, depending on how you are using this on the client side, you can transform them like below:
{
"foo": [
"bar",
"hoge"
]
}
to
{
"foo_0": "bar",
"foo_1": "hoge",
"foo_count" 2
}
Answers to commonly asked questions for users of the Raster MTS.
What is Raster MTS?
Raster MTS (or RMTS) is a service that creates custom raster tilesets from customer-provided raster data. The tilesets are hosted on Mapbox infrastructure and served via Mapbox APIs and SDKs to your Mapbox account. Tilesets are available at once across the globe and automatically backed by our regionally redundant, auto-scaling caching network, making it seamless to support any scale, in any geography, with low latency and high throughput.
How is Raster MTS different from MTS?
While MTS can process raster data that has been converted to a vector format (GeoJSON) and output a vector tileset, RMTS processes raster data in its native format, such as GeoTIFF, GRIB, or NetCDF, and outputs a raster tileset. The resulting raster tileset maintains the source’s pixel values, enabling multiple data values to be represented for the same geographic location.
What is raster data?
Raster data is a pixel-based data format in which data is stored in a grid structure. Each pixel, or unit of information, has the same size and shape, but varies in value. All digital photographs are stored in this format, including satellite images like those used in the Mapbox Satellite tileset. Raster tilesets are used in Mapbox tools to display maps as a grid of images that can be loaded on the map.
How do I use Raster MTS?
Follow the steps in the Raster MTS recipe tutorial to get started.
What is an RMTS recipe?
Recipes are JSON documents that set rules for the data to be tiled, using expressions based on the properties in the data. Example rules in a recipe could include: Tile the tornado data uploaded from zooms 5 through 16 Only tile imagery with a resolution of 3 cm at zoom levels >18 Only tile the top 5 flood-affected regions by area from the dataset until zoom 10, at zoom levels >10, only show flooded regions with an area greater than 8 pixels
What data formats can I upload?
The Raster MTS tool supports
- 3 different file types: GeoTIFF, GRIB, and NetCDF for
"type":"rasterarray"recipe. - GeoTIFF for
"type":"raster"recipe.
Contact us if there are formats you work with so we can assess alternative transformations.
Does Raster MTS support time series data?
Yes, Raster MTS supports processing time series data. Updates to GL JS and our Map SDKs allows to you to create and manage animations at runtime.
Can Raster MTS convert my data from another format?
No. If your data’s native format is not supported directly in RMTS, there are some open source tools to convert raster data formats. Depending on your needs, we’ve found both GDAL and Rasterio to be good at converting raster data.
Is my data compressed?
To distribute data efficiently, RMTS reduces data precision and then losslessly compresses it. The degree of precision simplification is configurable across zoom levels.
Can I view the progress of a tileset while it’s processing?
The status of a tiling job can be accessed via the tilesets status endpoint.
Can I download raw data I’ve uploaded to Mapbox?
We do not allow access to raw data. We recommend storing a local copy of source data for future reference.
Can I preview a finished raster tileset?
Previews are not available at present. We recommend starting with a small area and assessing the resulting tiles before running larger areas.
What are the limits associated with Raster MTS?
- Each individual source file must not exceed 20 GB.
- The maximum combined total size of all files that compose a tileset source is 50 GB.
- A single tileset-source can consist of up to 10 files. You can add as many sources as you want for a single recipe.
- GeoTIFF for "raster" recipe jobs must be 8-bit, and encoded for RGB photometric interpretation rather than YCbCr.