Country boundaries - limiting geographic area
Source data can often contain more information than what's needed in your map. For example, a political boundary dataset could contain boundaries for the entire world, when you may only need political boundaries for North America or the USA. In a recipe, you can specify a bounding box to limit the geographic extent of the data that will be tiled. The bbox
is an array of four numbers representing WGS84 longitudes and latitudes: [ minlon, minlat, maxlon, maxlat ]
.
The bbox
option can also be helpful for iterating on different recipes. By reducing the amount of data you're tiling, you can reduce your tileset costs and also the amount of time it takes for your job to process. To quickly view updates, you must remove client-side caching of tiles.
If you specify a bbox
in the features section of the recipe, all features will be clipped to this bounding box, so at every zoom level the geographic extent of the tileset will be limited in the same way. A tileset generated from a features bbox
is more visually consistent, but tiles that only include part of the bbox
may be limited or unioned differently than they would be if there was no bounding box.
USA Bounding Box
The recipe below produces a tileset that only contains data within a bounding box that covers the continental USA.
{
"version": 1,
"layers": {
"countries": {
"source": "mapbox://tileset-source/{username}/country-polygons",
"minzoom": 0,
"maxzoom": 5,
"features": {
"bbox": [ -125.0011, 24.9493, -66.9326, 49.5904 ]
}
}
}
}
The tileset on the left was generated without using a bbox
option. The map on the right is a tileset generated with the sample recipe above, defining bbox
by features.
Using the Tilesets CLI to generate a tileset
This section describes how to use the Tilesets CLI to generate a tileset.
- Download the data you'll use to create the tileset:
- Create a tileset source named
country-polygons
with the data you downloaded.
tilesets upload-source username country-polygons ~/your/local/path/countries.ldgeojson
- Create your recipe as a local JSON file (for example
bbox-recipe.json
) with yourcountry-polygons
tileset source
{
"version": 1,
"layers": {
"your_layer_name": {
"source": "mapbox://tileset-source/{username}/country-polygons",
"minzoom": 0,
"maxzoom": 5,
"features": {
"bbox": [ -125.0011, 24.9493, -66.9326, 49.5904 ]
}
}
}
}
- Create a tileset with the id
username.bbox-usa
using your recipe and name it"bbox usa"
. This will be an empty tileset to start, until you publish it.
tilesets create username.bbox-usa --recipe ~/your/local/path/bbox-recipe.json --name "bbox usa country boundaries"
- Now you're ready to publish your tileset and start processing your data.
tilesets publish username.bbox-usa
Preview your tileset
- You can now add your new tileset to a map style to visualize its data. Below is an example of how to add the
username.bbox-usa
tileset as a vector tile source to a Mapbox GL JS map style.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Country boundaries - limiting geographic area</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
// TO MAKE THE MAP APPEAR YOU MUST
// ADD YOUR ACCESS TOKEN FROM
// https://account.mapbox.com
mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/light-v10',
zoom: 1,
center: [-71.4935, 41.5852]
});
map.on('load', () => {
map.addSource('country-boundaries-bbox', {
type: 'vector',
url: 'mapbox://examples.bbox-usa'
});
map.addLayer({
'id': 'countries-bbox-id',
'type': 'line',
'source': 'country-boundaries-bbox',
// your source layer name, see https://docs.mapbox.com/help/glossary/source-layer/
'source-layer': 'bbox',
'layout': {
'line-join': 'round',
'line-cap': 'round'
},
'paint': {
'line-color': '#ff69b4',
'line-width': 1
}
});
});
</script>
</body>
</html>
Recipe options used
Field | Description | Data type |
---|---|---|
source | The source data to use for this layer. Tileset sources are created with the Create a tileset source endpoint of Mapbox Tiling Service (MTS). | String |
minzoom | Specify the minimum zoom at which the data in your tileset will be available. | Integer |
maxzoom | Specify the maximum zoom at which the data your tileset will be tiled. Your map can be viewed past this zoom level because of overzooming, but the data at zoom levels greater than the maxzoom will be less precise. | Integer |
bbox | Specify the bounding box limits to generate data for your tileset. | Array |