intermediate
JavaScript
Point-in-polygon query with Mapbox Enterprise Boundaries
Prerequisite
Familiarity with front-end development and access to Mapbox Enterprise Boundaries.

Mapbox Enterprise users can add global administrative, postal, and statistical boundaries to their maps and data visualizations. This guide covers how to use Mapbox Enterprise Boundaries with the Mapbox Tilequery API to query points in polygons.

Getting started

Mapbox Enterprise Boundaries are available as a part of an Enterprise plan. If you do not currently have an Enterprise plan or if you do have an Enterprise plan and would like to add access to Mapbox Enterprise Boundaries, contact a Mapbox sales representative to request access. Access to the Enterprise Boundaries tilesets are controlled by your Mapbox account access token.

About the Tilequery API

The Mapbox Tilequery API allows you to get data from a tileset without necessarily rendering a map. You can use the Tilequery API to match points to polygons, in other words, you can provide the coordinates for a point and determine which (if any) polygons in a specified tileset exist at that point.

Here’s what a Tilequery API request using an Enterprise Boundaries tileset would look like:

https://api.mapbox.com/v4/mapbox.enterprise-boundaries-a0-v2/tilequery/{longitude,latitude}.json?access_token=<your access token here>

If the specified point is within a polygon, the Tilequery API response will include a GeoJSON-format body with all features in the tileset. The id property value of the first feature returned is the ID of the Enterprise Boundaries feature that contains the queried point.

Since the feature lookup table contains all Enterprise Boundaries parent features, only one API request is required per point to find all matching parent boundaries. For example, you can query the admin-2 boundary of a point in Italy, and use the lookup table to find the parent features at admin-1 and admin-0.

Query Enterprise Boundaries

Below is an example API response from a sample query to admin-2 in Italy. The query URL is:

https://api.mapbox.com/v4/mapbox.enterprise-boundaries-a2-v2/tilequery/12.87,43.100.json?access_token=<your access token here>

The id returned is the identifier of the Enterprise Boundaries feature containing the point at admin-2.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          12.87,
          43.1
        ]
      },
      "properties": {
        "id": "ITA2054",
        "worldview": "all",
        "tilequery": {
          "distance": 0,
          "geometry": "polygon",
          "layer": "boundaries_admin_2"
          }
      }
    }
  ]
}

Query multiple tilesets

You can query multiple admin levels in one API call using tile compositing. The query below will return the ids at a location for admin-1, admin-2, and admin-3:

https://api.mapbox.com/v4/mapbox.enterprise-boundaries-a3-v2,mapbox.enterprise-boundaries-a2-v2,mapbox.enterprise-boundaries-a1-v2/tilequery/12.87,43.100.json?access_token=<your access token here>

This technique allows for aggregating and visualizing points at any admin level or multiple admin levels, down to individual points, as an API service.

Next steps

Learn more about the Tilequery API

Build an application that determines which timezone you are in using the Mapbox Tilequery API and the native HTML geolocation API with our Create a timezone finder tutorial.

Learn more about Enterprise Boundaries

Learn more about how you can use Mapbox Enterprise Boundaries.

  • Data-joins with Mapbox Enterprise 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 Enterprise Boundaries, using data-driven style notation.
  • Extend Mapbox Enterprise Boundaries: You can extend Mapbox Enterprise Boundaries with any custom data you need for your application. This could mean adding school district, city, market, or property boundaries to your application — all with the same performance and API features of the native product.

Advanced use cases

You can also check out this end to end example, which uses the concepts outlined in both this point-in-polygon query tutorial and the data-join tutorial to create an application featuring an interactive choropleth map.

an end to end example using the data-join technique and TileQuery API