Skip to main content

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.

  1. Download the data you'll use to create the tileset:
arrow-downDownload line-delimited GeoJSON
  1. Create a tileset source named country-polygons with the data you downloaded.
tilesets upload-source username country-polygons ~/your/local/path/countries.ldgeojson
  1. 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 ]
  1. 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"
  1. Now you're ready to publish your tileset and start processing your data.
tilesets publish username.bbox-usa

Preview your tileset

  1. 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>
<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="" rel="stylesheet">
<script src=""></script>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
<div id="map"></div>
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'
'id': 'countries-bbox-id',
'type': 'line',
'source': 'country-boundaries-bbox',
// your source layer name, see
'source-layer': 'bbox',
'layout': {
'line-join': 'round',
'line-cap': 'round'
'paint': {
'line-color': '#ff69b4',
'line-width': 1


Recipe options used

FieldDescriptionData type
sourceThe source data to use for this layer. Tileset sources are created with the Create a tileset source endpoint of Mapbox Tiling Service (MTS).String
minzoomSpecify the minimum zoom at which the data in your tileset will be available.Integer
maxzoomSpecify 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
bboxSpecify the bounding box limits to generate data for your tileset.Array
Was this example helpful?