Legacy pricing
This guide refers to legacy pricing for existing tilesets users before August 1, 2024. Legacy pricing is based on square kilometers and precision levels. Newer pricing based on processing compute is available. For more information, see the new tilesets pricing guide and email tilesets-pricing@mapbox.com.
When you use MTS, you can see your usage statistics on your statistics dashboard, and you will see two different line items: tileset processing and tileset hosting. The cost of each will depend on the area of your tiled data and the precision level of your tileset.
Tileset area
Tileset processing and hosting costs are directly proportional to the area of the tileset in square kilometers (km2).
How area is calculated
When you upload a tileset using the Mapbox Tiling Service (MTS) or the Uploads API, Mapbox charges for the area of the tiles that contain features from that tileset, at the specified precision level. There is usually only one precision level per tileset unless it is a multi-layer tileset created using MTS.
For each precision level, area is always calculated at one zoom level:
Tileset maxzoom | Precision | Zoom level at which area is calculated |
|---|---|---|
| 0-5 | Free | N/A |
| 6-10 | 10m | 6 |
| 11-13 | 1m | 11 |
| 14-16 | 30cm | 14 |
| 17-22 | 1cm | 17 |
The following example tiles a GeoJSON file that contains the rough outline of California. The area is being calculated at two precision levels: 10 meter and 1 meter.
10 meter precision: The area for 10 meter precision (
maxzoom 6-10) is calculated at zoom 6. The tiles at zoom 6 are
large, so the area per tile is also large, but there are few tiles that
contain features from the original GeoJSON (the outline of California) at
this precision.
1 meter precision: The area for 1 meter precision (
maxzoom 11-13) is calculated at zoom 11. At this precision, the
number of tiles that contain features from the original dataset increase
exponentially (each zoom level contains four times as many tiles as the
previous zoom level), but the area per individual tile also decreases
substantially:
Viewing area information for tilesets
To view area information for tilesets in your account, navigate to your tilesets list page in Mapbox Studio. To the right of each tileset you will see the precision and area in square kilometers for the tileset.
All tilesets created or updated after June 30, 2020 have a color-coded bar that indicates its area. Green indicates the tileset is a 10m tileset, yellow indicates it is a 1m tileset, orange indicates it is a 30cm tileset, and red indicates it is a 1cm tileset.
Estimating area for tilesets
To estimate the area of the tileset, use the estimate-area command in the Tilesets CLI. The command will return the estimated area in km2 for the tileset.
Improving area estimation processing times
If you are using the Tilesets CLI estimate-area command to estimate the tiled area of source data, the estimation process can take a long time if the file is large. There are two strategies you can use to make the process shorter:
- Split your file into smaller files (1 GB or less). These smaller files should be geographically bound; if you don’t split the original file geographically, you run the risk of having an inaccurate estimate with overlapping areas.
- Skip validation. The Tilesets CLI
estimate-areacommand estimates the tiled area of source data in square kilometers, which can help you generate a pricing estimate. By default,estimate-areavalidates data so it processes the entire file in memory before beginning the upload. For large files, this validation means it may take a long time to generate a square kilometer estimate. You can use the--no-validationoption to bypass this behavior, which will significantly decrease your upload time.
Tileset processing
MTS tilesets
Each time you publish a tileset with MTS, you will see a one-time tileset processing charge. The total cost of tileset processing depends on two factors:
- Precision level, which is determined by the
maxzoomused in the tileset recipe. Precision approximately describes the range of accuracy of tiled data relative to the real world. - Area, in square kilometers (km2), of your tiled data. This area is the total area of all tiles that contact features from your data at your specified precision level. See How area is calculated for more details on how this value is determined.
There are four possible line items related to tileset processing, each associated with a different precision level and pricing. MTS supports four precision levels: 10 meter, 1 meter, 30 centimeter, and 1 centimeter. The line item you see on your invoice depends on the maxzoom value you use in your tileset recipe:
Tileset recipe's maxzoom value | Line item | Notes |
|---|---|---|
| 0-5 | Free | Appropriate for low-resolution administrative boundaries like countries and states. |
| 6-10 | Tileset Processing 10m(cost per km2) | Appropriate for low-resolution administrative boundaries like countries and states. |
| 11-13 | Tileset Processing 1m(cost per km2) | Appropriate for high-resolution administrative boundaries like neighborhoods or census tracts. |
| 14-16 | Tileset Processing 30cm(cost per km2) | Appropriate for buildings, roads, and points of interest. |
| 17-22 | Tileset Processing 1cm(cost per km2) | Contact us to create a tileset with a maxzoom greater than 16. |
Uploads API tilesets
Mapbox Studio is powered by the Uploads API, but is subject to usage restrictions and alternative pricing. See the Mapbox Studio pricing guide for more details.
The precision level for Uploads API tilesets depends on the source file format of the upload.
Vector and MBTiles tileset's maxzoom value | Tiff tileset's maxzoom value | Precision level |
|---|---|---|
| 0-5 | 0-6 | Free |
| 6-10 | 7-11 | 10m |
| 11-13 | 12-14 | 1m |
| 14-16 | 15-17 | 30cm |
| 17+ | 18+ | 1cm |
Tileset hosting
After you publish a tileset with MTS, you will begin to see a recurring tileset hosting charge for every day your tileset is hosted on Mapbox's servers. This charge covers the cost of storing your tiled and processed data on Mapbox servers and will depend on several factors:
- Precision level, which is determined by the
maxzoomused in the tileset recipe. Precision approximately describes the range of accuracy of tiled data relative to the real world. - Square kilometer days is equal to the area tiled multiplied by the number of days hosted. The maximum possible value for a tileset's square kilometer days is the area of the tileset multiplied by 30 (the total days in the billing period).
- Area tiled, in square kilometers (km2), of your tiled data. This area is the total area of all tiles that contact features from your data at your specified precision level. See How area is calculated for more details on how this value is determined.
- Days hosted in your account in a given month-long billing period.
There are four possible line items related to tileset hosting, each associated with a different precision level and pricing. MTS supports four precision levels: 10 meter, 1 meter, 30 centimeter, and 1 centimeter. The line item you see on your invoice depends on the maxzoom value you use in your tileset recipe:
Tileset recipe's maxzoom value | Line item | Notes |
|---|---|---|
| 0-5 | Free | Appropriate for low-resolution administrative boundaries like countries and states. |
| 6-10 | Tileset Hosting 10m(cost per km2) | Appropriate for low-resolution administrative boundaries like countries and states. |
| 11-13 | Tileset Hosting 1m(cost per km2) | Appropriate for high-resolution administrative boundaries like neighborhoods or census tracts. |
| 14-16 | Tileset Hosting 30cm(cost per km2) | Appropriate for buildings, roads, and points of interest. |
| 17-22 | Tileset Hosting 1cm(cost per km2) | Contact us to host a tileset with a maxzoom greater than 16. |
For a tileset that has been published multiple times, hosting costs for a given day reflect the latest area of the tileset on that day. For example, a tileset that originally had an area of 10 square kilometers, but had an area of 5 square kilometers after an additional publish job will only incur tileset hosting costs for 5 square kilometers of data.
Estimate your usage metrics
The Tileset Explorer provides you with additional information that can help you estimate your usage metrics. To access the Tileset Explorer, go to your Mapbox Studio Tilesets page and click on a tileset's name.
Once the Explorer has opened, the Billing metrics graph will appear in the bottom left corner of the page. But, if your tileset is a free tier tileset, a graph will not appear because there will be no billing metrics to track.
This graph will provide an overview of how a tileset contributes to your monthly processing and hosting costs based on the area tiled and precision level.
Managing costs
For both processing and hosting, the most expensive tilesets are those that both cover a large area, like the entire world, and require high precision, for example a global road network
Managing 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 is not possible to lower processing costs associated with any tilesets you have 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.
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.
See How area is calculated for more details on how this value is determined.
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.
Managing 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.