Manage your tileset processing and tileset hosting costs
This troubleshooting guide shows you different ways to optimize your usage of Mapbox Tiling Service (MTS) and the Mapbox Uploads API to manage your costs for these services. These Mapbox services are used to tile your data and visualize it on a map. This guide also discusses how you can use Tippecanoe to tile your data optimally before uploading it with the Uploads API.
For more information on how MTS and the Uploads API are priced, see the relevant product documentation:
How do I lower my tileset processing costs?
Tileset processing is a one-time cost incurred when you publish an MTS job or create an upload with the Uploads API. This means it’s not possible to lower processing costs associated with any tilesets you’ve already published with MTS or uploaded with the Uploads API.
To reduce the processing costs for future tilesets, there are three factors that have the biggest impact on the cost of tileset processing:
- The precision of your tileset (in other words, its
maxzoom) - The update frequency
- The area of your tiled data
Reduce the maxzoom value
The most effective way to lower your tileset processing costs is by reducing the maxzoom value used by the tileset. Note that tilesets with a maxzoom of less than 6 are included in the free tier of MTS and the Uploads API.
Reduce maxzoom using MTS
Reducing the maxzoom in your tileset recipe will have the biggest impact on your tileset-related costs. Tilesets with a maxzoom of less than 6 are included in the free tier of MTS. So if your use case and data are such that you only need 300 meters of precision, then using a maxzoom of less than 6 will reduce your tileset processing costs to zero.
If you need more precision than 300 meters, then you should first reference the MTS zoom level configuration documentation to understand how much precision your data needs to determine your maxzoom in your tileset recipe.
Tilesets that use a maxzoom between 17 and 22 (1 centimeter precision) are the most expensive. You need to contact us first if your use case warrants that level of precision. Next, tilesets that use a maxzoom between 14 and 16 (30 centimeter precision) are the most expensive, followed by tilesets that use a maxzoom between 11 and 13 (1 meter precision). Tilesets that use a maxzoom between 6 and 10 (10 meter precision) are the least expensive. Learn more about how these pricing levels in the MTS pricing guide.
The maxzoom value does not determine which zoom level a map zooms to. Your
map will still zoom past the maxzoom specified in your tileset recipe
because of overzooming.
When you create your tileset recipe, maxzoom is one of the required options. This example recipe creates a tileset with a maxzoom of 8:
{
"version": 1,
"layers": {
"trees": {
"source": "mapbox://tileset-source/{username}/trees-data",
"minzoom": 4,
"maxzoom": 8
}
}
}
Reduce maxzoom using Tippecanoe
If you’re using Tippecanoe to create your tileset before you upload it with the Uploads API, you can use the -z zoom or --maximum-zoom=zoom commands to specify what maxzoom to use. If you don’t specify a maxzoom, Tippecanoe will use a maxzoom of 14 by default.
The following flag will create a tileset with a maxzoom of 6:
-z 6
The following flag will create a tileset with a maxzoom of 10:
--maximum-zoom=10
Reduce maxzoom using the Uploads API or Mapbox Studio
If you upload data using Mapbox Studio or upload data directly with the Uploads API, it’s not possible for you to specify what maxzoom to use for your tileset. The Uploads API guesses what level of precision your tileset needs, based on the data you upload.
If you need a different level of precision than the one the Uploads API chooses for you, we recommend that you use MTS. MTS gives you more control over the precision of your tilesets and, ultimately, your costs. Learn how to use MTS with the Tilesets CLI in the Get started using MTS and the Tilesets CLI tutorial.
If you are uploading a GeoTIFF using the Uploads API, maxzoom is determined by the minimum number of meters per pixel. You can reduce the maxzoom by downsampling the image (using a tool like GDAL or Rasterio so it contains the appropriate number of meters per pixel depending on the maxzoom of your target tileset processing level. You can use this chart to find the number of meters per pixel by zoom level.
Adjust your update frequency
The frequency with which you update your data has the second biggest impact on the price. When you are determining the optimal rate at which to update your tilesets, consider:
- How often your data changes
- How much of your data changes when it does change
- What type of data is changing (geometries or attributes)
When you update your tilesets with either MTS or the Uploads API, right now it’s only possible to re-tile all your data, no matter how much of your data changes with each update. For example, even if only 5% of your data changes every day, you still have to re-tile your entire tileset to see these changes on your map.
If your data doesn’t update that quickly, or if only a small amount of your data updates at a time, you can batch your data updates together outside of Mapbox until you reach a certain threshold of data changes before you update your tilesets. For example, in your database, you can keep two states of your data at one time:
- A copy of the data you most recently sent to Mapbox
- A copy of your data that receives real time updates
You can continuously calculate the difference between the two states of data (using feature counts, hashing the feature geometries and taking the difference, or similar strategies) until more than 30% of your data has changed, and then you can update your Mapbox tilesets.
You can also set a fixed frequency for your data updates regardless of how much your data has changed so that you can more accurately predict your future costs.
Update your tileset only when the geometries change
If most of your updates affect your data's attributes rather than their geometries, you may be able to leave the volatile attributes out of the tileset and instead join them on the client-side. This way, you can update your data's attributes without updating the whole tileset.
For example, consider a state-level unemployment dataset: the state geometries rarely change, while the unemployment numbers change often. A cost-effective strategy would be to create a static state boundaries tileset and then join the unemployment data dynamically on the client. See the Data Joins with Mapbox Boundaries tutorial for more information on how to use this data-join technique.
Reduce your area
If you have already lowered your maxzoom and adjusted your update frequency and would still like to reduce your tilesets-related costs, then reducing the area of your data will have the next biggest impact.
See the How area is calculated troubleshooting guide for more details on how this value is determined.
Reduce area using MTS
With MTS, you can use the bbox option in your tileset recipe to reduce the area of your tileset to a bounding box. MTS has filter expressions you can use in your recipe to filter out features from your tileset, which may reduce your tileset’s area. This is helpful if you only want to create a tileset of a subset of your data.
You can use the Tilesets CLI estimate-area command to estimate tiled area and make appropriate adjustments to your tileset.
Reduce maxzoom using other tools
Regardless of how you create your Mapbox tilesets, you can limit the area of your data in whatever software tool you use to create your data before tiling it with Mapbox.
How do I lower my tileset hosting costs?
Like tileset processing, pricing for tileset hosting is also based on the precision of your tileset (in other words, its maxzoom) and the area of your data. So all the above options for lowering your tileset processing costs will also help you reduce your tileset hosting costs for any future tilesets you create. But because tileset hosting is a recurring charge, another option you have for reducing your hosting costs is to delete tilesets.
Delete and re-tile tilesets that have not been optimized
The only way to reduce the hosting costs of any of your existing tilesets is to first delete any tilesets that you want to optimize and then re-tile your data based on the optimization options above.
Permanently delete unused tilesets
If you have any tilesets that you no longer use, it’s a good practice to delete those tilesets so that you’re not incurring any unnecessary, recurring charges.
You can delete your tilesets in two ways:
- Programmatically using MTS
- Using Mapbox Studio
Delete a tileset with MTS
You can use the delete tileset endpoint of MTS to delete any tilesets you created with MTS, the Uploads API, and Mapbox Studio. This endpoint doesn’t have a bulk delete option, so you can only delete one tileset at a time.
This example request deletes a tileset using cURL:
$ curl -X DELETE "https://api.mapbox.com/tilesets/v1/{username.tileset_id}?access_token=YOUR MAPBOX ACCESS TOKEN
To use this endpoint, you need a Mapbox access token with tilesets:write scope.
Delete a tileset in Mapbox Studio
You can also use Mapbox Studio to delete any tilesets you created with either MTS or the Uploads API:
- Navigate to the Mapbox Studio Tilesets page.
- In your list of custom tilesets, find the tileset you want to delete.
- Click on the options menu (three vertical dots) to the right of the tileset name.
- Select the Delete option.
- You will be prompted with a confirmation message. Once you click the Delete button in this message, your tileset will be permanently deleted and you will not be able to recover it.