Country boundaries

Simplifying your data means removing complexity in the vertices of your geometry. Each vertex must be translated to vector tile coordinates. The fewer vertices to translate, the faster processing becomes. Often you can simplify your data without any visual change, but oversimplifying could remove important granularity in your data as well as potentially create invalid geometries if lines begin overlapping.

Simplification tools typically take a tolerance parameter to specify how much to simplify. For MTS, recipe simplification typically ranges from 0 - 40, with a value 20 indicating moderate simplification. 4 is the default parameter if you do not specify a value in your recipe. The default simplification value simplifies your data so that is not distinguishable visually but will still make the tiles as small as possible under the constraints of tile boundaries.

Why would you want to use simplification?

There are two primary use cases for simplification:

Preserve shape. Set simplification to 0 to preserve the shape of the gridded data exactly. For example, weather data will need to be precise to visualize near real time precipitation.
Reduce complexity. Set simplification to a moderate value such as 15 to 20 if your tiles are large and you want to make them smaller for faster map loads. Simplification does not affect the resolution of your data at higher zoom levels. In the example below, we show how country boundary data can be simplified and still have the visualized effect needed.

The recipe below is an example of why simplification can be effective. This example of simplification uses country boundary data from Natural Earth Data. In this mapping scenario, we want a visual of where country boundaries exist, but the exact precision of the boundary is not significant - we don't need to display highly detailed country borders. To achieve this output, you would use the simplification option in the features configuration to keep the number of nodes small in the final tiles.

Zoom in and out to view the effects of simplification on the country boundaries dataset.

The tileset on the left contains country boundaries with the default simplification value of 4. The tileset on the right contains country boundaries with a simplification value of 20.

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 simplification-recipe.json) with your country-polygons tileset source


{
  "version": 1,
  "layers": {
    "countries": {
      "source": "mapbox://tileset-source/{username}/country-polygons",
      "minzoom": 0,
      "maxzoom": 5,
      "features": {
        "simplification": 20
      }
    }
  }
}

Create a tileset with the id username.countries-simplification using your recipe and name it "country boundaries simplification". This will be an empty tileset to start, until you publish it.


tilesets create username.countries-simplification --recipe ~/your/local/path/simplification-recipe.json --name "country boundaries simplification"

Now you're ready to publish your tileset and start processing your data


tilesets publish username.countries-simplification

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.countries-simplification tileset as a vector tile source to a Mapbox GL JS map style.


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Country boundaries - simplifying political boundary data</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: 8,
    center: [-71.4935, 41.5852]
  });

  map.on('load', () => {
    map.addSource('country-boundaries-simplified', {
      type: 'vector',
      url: 'mapbox://examples.countries-simplification'
    });
    map.addLayer({
      'id': 'countries-simplification-data',
      'type': 'line',
      'source': 'country-boundaries-simplified',
      'source-layer': 'countries_polygons',
      '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. A value of 0 here ensures that the countries will be visible at a global level.	`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. A value of 5 here ensures that the countries will be visible as the user zooms in slightly, but will not be visible if they zoom in significantly.	`Integer`

| features.simplification | Specify an integer value or expression that is greater than zero to control the level of simplification that occurs for features. The value provided is relative to the extent provided for the tiles, with a larger value resulting in more simplification. A value of 20 here indicates a moderate amount of simplification that will become more apparent as a user zooms in on country boundaries. | Integer expression |

Additional Developer Resources

Mapbox Developer Discord

Developer Cheatsheet

Mapbox Support

Ask AI

Was this example helpful?

Why would you want to use simplification?​