Country boundaries - limiting geographic area | Mapbox Tiling Service

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:

arrow-downDownload line-delimited GeoJSON

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 your country-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.0.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.0.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`

Was this example helpful?

USA Bounding Box​

Using the Tilesets CLI to generate a tileset​

Preview your tileset​

Recipe options used​

USA Bounding Box

Using the Tilesets CLI to generate a tileset

Preview your tileset

Recipe options used