Add your data
Learn about the different ways you can overlay your data on a map.
This guide focuses on the process of taking geographic data that already exists and transforming it into a format that can be used on a web or mobile map. This could be data that you downloaded from an open data portal, data that you drew in a GIS application, aerial imagery taken by a drone, or something else.
How do I add my data to a map?
Below are four options to add your custom data to a map. If your data has to be hosted externally, skip to Option 4.
Option 1: Upload data with Mapbox Studio
Best for styling your data on a map using a no-code style editor and to quickly publish map changes to your live app with minimal changes to client-side code.
This option converts your source data into a tileset that is hosted on the Mapbox platform. Tilesets are a styleable format optimized for high-performant rendering across all platforms.
Supported formats: MBTiles, KML, GPX, GeoJSON, Shapefile (zipped), CSV file, GeoTIFF
Limitations: 300 MB filesize limit.
Walk through adding your data to a map and styling it.
Option 2: Use the Mapbox Tiling Service (MTS)
Best for jobs of any size and update frequency where you want more control over how your source data is transformed and tiled. MTS is also a good option if you want to programmatically create tilesets.
Supported formats: Line-delimited GeoJSON, GeoJSON (Tilesets CLI). Note that there are several publicly available tools (like mapshaper) that convert formats like Shapefiles, KML, and CSV to GeoJSON.
Limitations: Each uploaded file must be below 20 GB. The maximum combined total size of all files that compose a tileset source is 50 GB. Read more about MTS restrictions and limits.
Create and publish a custom tileset using sample data.
Option 3: Use the Uploads API
If you want to programmatically create a tileset and cannot use MTS (because GeoJSON is not a suitable format for your data or your data is in a raster format), use the Uploads API.
Supported formats: MBTiles, KML, GPX, GeoJSON, Shapefile (zipped), CSV file, GeoTIFF
Get started with the Uploads API.
Option 4: Load your data at runtime
If your data lives in a third-party data-source, you can load it on the client during runtime using the addSource method. The examples below show how you can load an externally-hosted GeoJSON on web or mobile.
map.on('load', () => {
map.addSource('earthquakes', {
type: 'geojson',
// Use a URL for the value for the data property.
data: 'https://docs.mapbox.com/mapbox-gl-js/assets/earthquakes.geojson'
});
map.addLayer({
'id': 'earthquakes-layer',
'type': 'circle',
'source': 'earthquakes',
'paint': {
'circle-radius': 4,
'circle-stroke-width': 2,
'circle-color': 'red',
'circle-stroke-color': 'white'
}
});
});
let earthquakeSource = GeoJSONSource(id: "earthquakes")
earthquakeSource.data = .url("https://www.mapbox.com/mapbox-gl-js/assets/earthquakes.geojson")
earthquakeSource.generateId = true
do {
try mapView.mapboxMap.addSource(earthquakeSource)
} catch {
print("Ran into an error adding a source: (error)")
}
style.addSource(geoJsonSource("earthquakes") {url("https://www.mapbox.com/mapbox-gl-js/assets/earthquakes.geojson")})
Dive even deeper with these code examples:
| Web | iOS | Android |
|---|---|---|
How do I style my data?
You can either style your data at runtime or in Studio.
- Runtime Styling: This option is ideal for event-based styling (for example, if a user hovers over data and it changes color). This option is also good if you want styling variants but don't want to support multiple styles in Studio.
- Styling in Studio: This option is ideal if you want to style your data without having to alter client-side code or redeploy your application. It also keeps all your map styling in one place.
Style your data dynamically at runtime
After adding your data to a new layer, style it using one of the available paint properties for that layer type.
The example snippet below show how you can style custom line data on web with Mapbox GL JS:
map.addLayer({
'id': 'route',
'type': 'line',
'source': 'route',
'layout': {
'line-join': 'round',
'line-cap': 'round'
},
'paint': {
'line-color': '#888',
'line-width': 8
}
});
Style your map in Studio
Any data uploaded to our platform is accessible from within Studio for quick styling. Changes you publish in Studio will be reflected in your mobile and web applications with no additional code changes needed.
Learn more about styling in Studio.
How much will it cost?
Tilesets uploaded in Mapbox Studio are free, and do not incur processing or hosting charges. Tilesets uploaded using the Mapbox Tiling Service (MTS) or the Uploads API are billed by tileset hosting and tileset processing.