Extend Mapbox Boundaries

Mapbox Boundaries includes coverage for most boundaries of the world, but in some cases you may want additional boundaries like school districts, community areas, or sub-market boundaries for your customers. You can extend Mapbox Boundaries with any custom polygon data and deliver the same frontend, API-driven services for data visualization, analysis, and geofencing applications around the world.

This guide walks through how to format, tile, and host additional boundary data to work in your application alongside Mapbox Boundaries.

Getting started

Here are a few resources you'll need throughout this tutorial:

• Access to Mapbox Boundaries. Access to the Mapbox Boundaries tilesets is controlled by your Mapbox account access token. To request access to Mapbox Boundaries, contact Mapbox sales.
• Data. In this tutorial, you will work with the school district boundaries produced by the US Government. Download the composite 2019 US School District Boundaries shapefile from the National Center for Education Statistics website.
  • Note: The process outlined in this guide requires that your custom data uses polygon or multi-polygon geometries.
• QGIS. QGIS is an open source GIS application. You can download it from http://www.qgis.org/. You should be familiar with the QGIS interface before starting this tutorial.
• Tippecanoe. Tippecanoe is a command line tool for creating Mapbox tilesets.
• Mapbox CLI. You'll use the Mapbox CLI (command line interface) to upload the tileset you create with Tippecanoe to your Mapbox account.

Prepare Data

You'll do two things to prepare the boundary data before creating Mapbox tilesets:

1. Identify which feature properties in the shapefile will be useful in the final tiles and format those properties in preparation for tile creation.
2. Generate polygon and point GeoJSON layers so that the data can be converted to polygon and point vector tiles using Tippecanoe.

Identify and format useful feature properties

Before you convert custom data into vector tiles, it is important to identify which feature properties will be useful in the final tileset and include only those useful properties to keep the tiles small and performant. In most cases, you will want the resulting tileset to include at least these two properties:

• feature_id: A unique integer property can be used to filter and target individual features using GL feature states. This can be either randomly generated or be derived from an official code in the data.
• name An optional text property that can be used add human readable labels to boundary features on the map.

Open the shapefile in QGIS and use the identify tool to inspect the available properties that can be used as a unique identifier.

The GEOID property appears to be unique to each feature so you'll use this as a feature_id. And, use the NAME property for the name. For convenience, it's useful to edit the property names since they cannot be modified later.

Generate polygon and point GeoJSON layers

It is necessary that the boundary data is saved as a GeoJSON file with EPSG:4326 (WGS84) projection before it can be converted into vector tiles with Tippecanoe.

1. Right click the shapefile in the layer panel and select Export > Save Features As.
2. Choose the GeoJSON format and the CRS as EPSG:4326 (WGS84).
3. Only select the properties that you wish to export.
4. Export the file to us-school-district-polygons.geojson.

Additionally, we will also generate a point GeoJSON from the centroid of every feature which are useful for locating the boundary labels on the map.

1. Open the QGIS processing toolbox from the menu.
2. Open the Point on Surface algorithm.
3. Choose the previously exported us-school-district-polygons as the input layer.
4. Export the file to us-school-district-points.geojson.

You should now have two GeoJSON files, us-school-district-polygons.geojson and us-school-district-points.geojson, that you'll use to generate the school district vector tiles.

Create tiles

To create tilesets from your custom data, use the command line tool Tippecanoe to transform your GeoJSON features to vector tiles. You'll need to create two source layers and merge them together into a single tileset source:

1. One source layer for all polygons.
2. One source layer for centroid points.

Tippecanoe has various settings that can control the conversion of the GeoJSON into the vector tiles. The most important settings are:

• The --minimum-zoom level controls the starting zoom at which the features are visible on the map. Use 2 for a country level dataset and higher numbers like 8 for a city level dataset.
• The --maximum-zoom level for the tiles which controls the maximum accuracy. The default is 14, which gives an accuracy of around 4 meters. For boundaries, a maximum zoom of 12 is more appropriate.
• The source --layer name which needs to be unique amongst all the data sources added to the map.
• The --output file name for the vector tiles in MBTiles format.
• The --drop-rate which controls how many points are dropped at low zoom levels. Use 0 to ensure least points are dropped.
• The property that we wish to be used for the unique feature id in the tiles can be set using --use-attribute-for-id and --convert-stringified-ids-to-numbers to ensure that they are converted to integers first. For the school boundaries we will use the feature_id property. Alternatively if you wish to generate a new unique identifier, you can use the --generate-ids setting.
• Set the --simplification scale to simplify complex polygon geometries for more optimized tiles.

Create the polygon source layer

Start by creating a polygon source layer. Use the following Tippecanoe command to transform the example files. We will use a simplification scale of 8 which is a good starting value (use a lower number if more details are required):

tippecanoe -f --output=us-school-district-polygons.mbtiles --layer=us_school_districts --minimum-zoom=2 --maximum-zoom=12 --simplification=8 --use-attribute-for-id=feature_id --convert-stringified-ids-to-numbers us-school-district-polygons.geojson

Create the point source layer

Next, create a point source layer using the following Tippecanoe command. We can use a lower minimum zoom level of 1 for points for it to be visible even when zoomed out beyond the country:

tippecanoe -f --output=us-school-district-points.mbtiles --layer=us_school_districts_points --minimum-zoom=1 --maximum-zoom=12 --drop-rate=0 --use-attribute-for-id=feature_id --convert-stringified-ids-to-numbers us-school-district-points.geojson

Combine layers into a single tileset

Then, join the polygon and point layers into one vector tileset using the following command:

tile-join -f --output=us-school-district.mbtiles us-school-district-polygons.mbtiles us-school-district-points.mbtiles

You can optionally inspect the final MBTiles locally using mbview to confirm it has the expected features and attributes:

mbview us-school-district.mbtiles

Upload to your account

You can upload your tileset to your Mapbox account using Mapbox Studio. After the uploading has finished processing in Mapbox Studio, a tileset ID is generated automatically for you.

Creating a custom Map

After the tileset has been successfully added to your account, you can use start using it to create a custom map style alongside other boundaries tilesets.

Final product

Here is an example style showing how the new US Admin Level 3 data works alongside the base Mapbox Boundaries product.

Next steps

Learn more about how you can use Mapbox Boundaries:

• Point-in-polygon query with Mapbox Boundaries: Determine what polygons exist at a single point using the Mapbox Tilequery API.
• Data-joins with Mapbox Boundaries: The data-join technique involves inner joins between local data, such as the unemployment rate by US state, to vector tile features, such as admin boundaries in Mapbox Boundaries, using data-driven style notation.