Extend Mapbox Boundaries
Familiarity with front-end development, command line tools, and GIS. Access to Mapbox Boundaries.
Access to the Mapbox Boundaries tilesets is controlled by Mapbox account access token. If you do not have access on your account, contact Mapbox sales to request access to Boundaries tilesets.
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:
- Identify which feature properties in the shapefile will be useful in the final tiles and format those properties in preparation for tile creation.
- 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.
- Right click the shapefile in the layer panel and select
Export
>Save Features As
. - Choose the
GeoJSON
format and the CRS asEPSG:4326 (WGS84)
. - Only select the properties that you wish to export.
- 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.
- Open the QGIS processing toolbox from the menu.
- Open the
Point on Surface
algorithm. - Choose the previously exported
us-school-district-polygons
as the input layer. - 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.
If you notice geometry errors during any of the processing steps, use the Fix Geometries
algorithm from the QGIS processing toolbox to fix any issues with the input data.
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:
- One source layer for all polygons.
- 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. Use2
for a country level dataset and higher numbers like8
for a city level dataset. - The
--maximum-zoom
level for the tiles which controls the maximum accuracy. The default is14
, which gives an accuracy of around 4 meters. For boundaries, a maximum zoom of12
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. Use0
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 thefeature_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.
There is fixed limit to the amount of data that can be stored into a vector tile. Depending on your use case, you may want to adjust the starting zoom level at which te data is visible -Z
, the simplification or the number of feature attributes to control how many features you can efficiently pack into a tile.
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.
Alternatively, you can upload your tileset from the command line using the Uploads API. The API also gives control over setting a custom tileset ID.
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.
Find the complete list of Mapbox Boundaries tilesets in the reference documentation.
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.