Mapbox Tiling Service

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 U.S. 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 U.S.

"version": 1,
"layers": {
"countries": {
"source": "mapbox://tileset-source/{username}/country-polygons",
"minzoom": 0,
"maxzoom": 5,
"tiles": {
"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.

No BBox | recipe
BBox | recipe

Using the Tilesets CLI to generate a tileset

  1. Download the data you'll use to create the tileset
  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 (e.g. 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, 49.5904, -66.9326]
  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
  1. You'll first need to 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" />
<script src=""></script>
<link href="" rel="stylesheet" />
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
<div id="map"></div>
mapboxgl.accessToken = '<your access token here>';
var map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/light-v10',
zoom: 1,
center: [-71.4935, 41.5852]
map.on('load', function() {
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 page helpful?