Tilequery

The Mapbox Tilequery API allows you to retrieve data about specific features from a vector tileset, based on a given latitude and longitude. The Tilequery API makes it possible to query for features within a radius, do point-in-polygon queries, query for features in multiple composite layers, and augment data from the Mapbox Geocoding API with custom data.

Mapbox Tilequery API has some functional similarities to the reverse geocoding function of the Mapbox Geocoding API, which accepts a {longitude},{latitude} pair and returns an address. The Tilequery API returns the location and properties of the features within the query radius.

playground
Tilequery API playground

Create and run Tilequery API queries and see the results on a map.

Retrieve features from vector tiles

get
/v4/{tileset_id}/tilequery/{lon},{lat}.json

Use this endpoint to retrieve features from vector tiles.

Required parametersDescription
tileset_idThe ID of the map being queried. To composite multiple layers, use a comma-separated list of up to 15 tileset IDs.
{lon},{lat}The longitude and latitude to be queried.

You can further refine the results from this endpoint with the following optional parameters:

Optional parametersDescription
radiusThe approximate distance in meters to query for features. Defaults to 0, which performs a point-in-polygon query. Has no upper bound. Required for queries against point and line data. Due to the nature of tile buffering, a query with a large radius made against equally large point or line data may not include all possible features in the results. Queries will use tiles from the maximum zoom of the tileset, and will only include the intersecting tile plus eight surrounding tiles when searching for nearby features.
limitThe number of features between 1-50 to return. Defaults to 5. The specified number of features are returned in order of their proximity to the queried {lon},{lat}.
dedupeDetermines whether the features in the result will be deduplicated (true, default) or not (false). The Tilequery API assumes that features are duplicates if all of the following are true: the features are from the same layer; the features are the same geometry type; and the features have the same ID and the same properties (or just the same properties, if the features do not have IDs).
geometryReturn only a specific geometry type. Options are polygon, linestring, or point. Defaults to returning all geometry types.
layersA comma-separated list of layers to query, rather than querying all layers. If a specified layer does not exist, it is skipped. If no layers exist, returns an empty FeatureCollection.

Point-in-polygon queries

To perform a point-in-polygon query, do not use the radius parameter, which will leave it set at the default value of 0. A point-in-polygon query will only return polygons that your query point is within. Any query point that exists directly along an edge of a polygon will not be returned.

Be aware of the number of results you are returning. There may be overlapping polygons in a tile, especially if you are querying multiple layers. If a query point exists within multiple polygons, there is no way to sort results such that they are returned in the order they were queried. If there are more results than you specified with the limit parameter, they will be cut off once the query hits the maximum number of results.

Example request: Retrieve features from vector tiles

# Retrieve features within a 10 meter radius of the specified location

$ curl "https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/-122.42901,37.80633.json?radius=10&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Return at most 20 features

$ curl "https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/-122.42901,37.80633.json?limit=20&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Query multiple maps

$ curl "https://api.mapbox.com/v4/{tileset_id_1},{tileset_id_2},{tileset_id_3}/tilequery/-122.42901,37.80633.json&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Return only results from the poi_label and building layers within a 30 meter radius of the specified location

$ curl "https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/-122.42901,37.80633.json?radius=30&layers=poi_label,building&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Retrieve features from vector tiles

A request to the Tilequery API returns a GeoJSON FeatureCollection of features at or near the geographic point described by {longitude},{latitude} and within the distance described by the optional radius parameter.

The Tilequery API response is ordered based on which features are closest to the queried {longitude},{latitude}. If point-in-polygon query was performed, then all returned features are directly at the query point and proximity does not influence the order in which they are returned.

Each feature in the response body contains the following properties:

PropertyDescription
typeThis will always be Feature.
idThe identifier of the returned feature, as represented in the queried vector tile.
geometry.typeThis will always be Point. The Tilequery API does not return the full geometry of a feature. Instead, it returns the closest point ({longitude},{latitude}) of a feature.
geometry.coordinatesThe coordinates of the returned feature.
propertiesThe properties of the feature.
properties.tilequery.distanceThe approximate surface distance in meters from the feature result to the queried point. Note that this number represents geographical distance, not distance along the road network. If distance is 0, the query point is within the geometry (point-in-polygon).
properties.tilequery.geometryThe original geometry type of the feature. This can be ”point”, ”linestring”, or ”polygon”. The actual geometry of the feature is not returned in the result set. The original geometry type of a feature impacts what gets returned:
Original geometry of featureResult
polygonIf the query point is within the polygon, the result will be the query point location. If the query point is outside the polygon, the result is the interpolated closest point along the nearest edge of the feature within the radius threshold.
linestringThe result is the interpolated closest point along the feature within the radius threshold.
pointThe result is the nearest point within the radius threshold.
properties.tilequery.layerThe vector tile layer of the feature result.

Example response: Retrieve features from vector tiles

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 4174053671,
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.42901,
          37.80633
        ]
      },
      "properties": {
        "class": "national_park",
        "type": "national_park",
        "tilequery": {
          "distance": 0,
          "geometry": "polygon",
          "layer": "landuse_overlay"
        }
      }
    },
    {
      "type": "Feature",
      "id": 822070541,
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.4289919435978,
          37.806283149631255
        ]
      },
      "properties": {
        "localrank": 1,
        "maki": "park",
        "name": "Fort Mason",
        "name_ar": "Fort Mason",
        "name_de": "Fort Mason",
        "name_en": "Fort Mason Center",
        "name_es": "Fort Mason",
        "name_fr": "Fort Mason",
        "name_pt": "Fort Mason",
        "name_ru": "Fort Mason",
        "name_zh": "梅森堡",
        "name_zh-Hans": "梅森堡",
        "ref": "",
        "scalerank": 1,
        "type": "National Park",
        "tilequery": {
          "distance": 5.4376397785894595,
          "geometry": "point",
          "layer": "poi_label"
        }
      }
    }
  ]
}

Supported libraries: Retrieve features from vector tiles

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Tilequery API errors

Response body messageHTTP status codeDescription
Empty FeatureCollection200If an empty FeatureCollection is returned, check whether the specified layer exists.
Not Authorized - No Token401No token was used in the query.
Not Authorized - Invalid Token401Check the access token you used in the query.
Tileset {tileset name} does not exist404Check the name of the tileset you used in the query.
Tile does not exist404The tile that intersects the specified {lon/lat} location does not exist in the queried tileset. Alternatively, if the tileset was created by MTS but not successfully published, you will see this error.
options.limit must be a number between 1 and 50422The limit specified in the query is larger than 50 or contains non-numeric characters.
Invalid {lon/lat} value: {value}422Check the latitude and longitude values you used in the query.
options.geometry must be \"polygon\", \"linestring\", or \"point\"422The geometry parameter must be one of the options described in the Retrieve features from vector tiles section of this documentation.

Tilequery API restrictions and limits

  • The default rate limit for the Mapbox Tilequery API endpoint is 600 requests per minute. If you require a higher rate limit, contact us.
  • If you exceed the rate limit, you will receive an HTTP 429 Too Many Requests response. For information on rate limit headers, see the Rate limit headers section.

Tilequery API pricing

  • Billed by requests
  • See rates and discounts per Tilequery API request in the pricing page's Maps section

Usage of the Tilequery API is measured in API requests. Each query for geographic features in one or more Mapbox-hosted vector tilesets at a given latitude and longitude will be counted as one Tilequery API request. Details about the number of Tilequery API requests included in the free tier and the cost per request beyond what is included in the free tier are available on the pricing page.