Search Box API | API Docs

The Mapbox Search Box API is the easiest way to add interactive location search to connected cars, micro-mobility services, delivery apps, and more. Search Box API supports interactive location search or stand-alone queries to search addresses, places, and points of interest.

playground

Search Box API Developer Playground

Try Search API queries and see the results on a map.

chevron-right

guide

Japan-specific considerations for the Search Box API

Learn how to use Search Box API for Japanese-language searches for Japanese locations.

chevron-right

The Search Box API includes following the endpoints to support various location search use cases:

/suggest and /retrieve endpoints are used together to build an Interactive Search for your app.
/category endpoint is used to perform a Category Search
/reverse endpoint is used to perform a Reverse lookup

Interactive Search

With the Search Box API, developers can create an autocomplete search experience that makes it easier for users to find not only addresses, but also points of interest (POIs), categories of POIs, street names, neighborhoods, localities, place names, districts, postcodes, regions, and countries.

playground

Search Box API User Demo

Try Search Box API powered interactive search on a map.

chevron-right

The /suggest endpoint is used in combination with the /retrieve endpoint to create an interactive search experience for end users. Within your application, send user search queries to the /suggest endpoint to get suggested results for the given search query.

When a user selects a result on the application UI, you should trigger a /retrieve request to get detailed information about the selection.

Get suggested results

get

https://api.mapbox.com/search/searchbox/v1/suggest?q={search_text}

This endpoint provides a list of suggested search results for the user query. This endpoint, along with the /retrieve endpoint, can be used to add autocomplete search functionality to your applications=.

Required parameters	Type	Description
`q`	string	The user's query string. The query is limited to 256 characters.
`access_token`	string	A Mapbox access token with default permissions.
`session_token`	string	A customer-provided session token value, which groups a series of requests together for billing purposes. UUIDv4 is recommended. For more information on how `session_token` is used to group Search API calls into one session, see the Session-based pricing section of this documentation.

You can further refine the results of a query to this endpoint with the following optional parameters:

Optional parameters	Type	Description
`language`	string	The ISO language code to be returned. If not provided, the default is English.
`limit`	integer	The number of results to return, up to 10.
`proximity`	string	Bias the response to favor results that are closer to a specific location. Provide either `ip` to get results closest to the user's IP location or provide two comma-separated coordinates in `longitude,latitude` order. If not provided, the default is IP proximity. When both `proximity` and `origin` are provided, `origin` is interpreted as the target of a route, while `proximity` indicates the current user location.
`origin`	number	The location from which to calculate distance, provided as two comma-separated coordinates in `longitude,latitude` order. When both `proximity` and `origin` are provided, `origin` is interpreted as the target of a route, while `proximity` indicates the current user location. This parameter is required for distance-to-target estimates, but may incur additional latency.
`bbox`	number	Limit results to only those contained within the supplied bounding box. Bounding boxes should be supplied as four numbers separated by commas, in `minimum longitude`,`minimum latitude`,`maximum longitude`,`maximum latitude` order. The bounding box cannot cross the 180th meridian.
`navigation_profile`	string	The navigation routing profile to use. Available profiles are: `driving`, `walking`, and `cycling`. `navigation_profile` and `origin` are required for distance calculations.
`route`	string	A polyline encoded linestring describing the route to be used for searching. This parameter enables searching along a route. Both polyline5 and polyline6 precision are accepted, but must be specified using the `route_geometry` parameter.
`route_geometry`	string	Passed in conjunction with a route polyline describing its precision. Options are `polyline` or `polyline6`. If this parameter is not provided with a `route`, the default is `polyline`. Accurate results depend on including the correct `route_geometry` for the `route` provided.
`sar_type`	string	This indicates that the user intends to perform a higher cost search-along-route request. This should be included when `route` is included and should have a value of `isochrone`.
`time_deviation`	number	Maximum detour in estimated minutes from route.
`eta_type`	string	Used to estimate the time of arrival from the location specified in `origin`. The only allowed value for this parameter is `navigation`. This parameter, along with `origin` and `navigation_profile`, is required for ETA calculations. ETA calculations will incur additional latency.
`country`	string	An ISO 3166 alpha 2 country code.
`types`	string	Limit results to one or more types of features, provided as a comma-separated list. Pass one or more of the type names as a comma separated list. If no types are specified, all possible types may be returned. Available types are: `country`, `region`, `postcode`, `district`, `place`, `city`, `locality`, `neighborhood`, `street`, and `address`. See the Administrative unit types section for details about these types.
`poi_category`	string	Limit results to those that belong to one or more categories, provided as a comma-separated list.
`radius`	number	Radius for the area to search within around a point.
`user_id`	string	A customer provided user id.
`rich_metadata_provider`	string	A comma-separated list of rich metadata providers to include in a suggestion result.
`poi_category_exclusions`	string	A comma-separated list of canonical category names that limits POI results to those that are not part of the given categories.

Example request: Get suggested results

# Search for Michigan Stadium with limit=1

$ curl "https://api.mapbox.com/search/searchbox/v1/suggest?q=Michigan%20Stadium?language=en&limit=1&session_token=[GENERATED-UUID]&proximity=-83.748708,42.265837&country=US&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Get suggested results

The response to a request to the /suggest endpoint is an array of JSON suggestion objects. A suggestion will include a result name, address information, geographical context, and additional metadata when available (such as distance to proximity point). It does not include geographic coordinates. To get coordinates, make a call to the /retrieve endpoint with the mapbox_id provided in the /suggest result.

Using the limit parameter, you can increase the maximum number of results up to 10. Pagination is not available, but this feature may be added in a later release. There is not an option to customize the order of search results.

Each result object contains the following properties:

Property	Type	Description
`suggestions`	array of objects	The returned suggestion objects. See the table below for details on the properties contained in each suggestion object.
`attribution`	string	The attribution data for results.

Each suggestion object contains the following properties:

Property	Type	Description
`name`	string	The name of the feature.
`name_preferred`	string	The preferred name of the feature, if different than `name`.
`mapbox_id`	string	The id to use with `/retrieve` to obtain full feature details.
`feature_type`	string	The type of the result. For POIs, this will be `poi`. For categories, this will be `category`. For address-type results, the global context hierarchy is used (`country`, `region`, `postcode`, `district`, `place`, `locality`, `neighborhood`, `address`). See the Administrative unit types section for details about these types.
`address`	string	The address of the result containing the address number and street.
`full_address`	string	The full address of the result, which concatenates `address` and `place_formatted`.
`place_formatted`	string	A formatted string of result context comprised of the place, region, country, and postcode.
`context`	object	The context of the feature. This context has layers that follow the Administrative unit types.
`context.country`	object	The country of the result. This layer includes properties `id`, `name`, `country_code` (the ISO_3166_1 alpha 2 code), and `country_code_alpha_3` (the ISO_3166_1 alpha 3 code).
`context.region`	object	The region of the result. This layer includes properties `id`, `name`, `region_code`, and `region_code_full` (the ISO_3166_2 code).
`context.postcode`	object	The postcode of the result. This layer includes properties `id` and `name`.
`context.district`	object	The district of the result. This layer includes properties `id` and `name`.
`context.place`	object	The place of the result. This layer includes properties `id` and `name`.
`context.locality`	object	The locality of the result. This layer includes properties `id` and `name`.
`context.neighborhood`	object	The neighborhood of the result. This layer includes properties `id` and `name`.
`context.address`	object	The address of the result including the address number and street. This layer includes properties `id`, `name`, `address_number`, `street_name`.
`context.street`	object	The street of the result. This layer includes properties `id` and `name`.
`language`	string	An IETF language tag indicating the language of the result.
`maki`	string	A string representing an associated Maki icon to use for this result.
`poi_category`	array	An array including the POI categories the result falls into, if it is a POI.
`poi_category_ids`	array	An array including the canonical POI category IDs the result falls into, if it is a POI.
`brand`	string	The brand name of the result, if it is a POI and is applicable.
`brand_id`	string	The canonical brand ID of the result, if it is a POI and is applicable.
`external_ids`	object	An object containing the IDs of the feature found in external databases, with the keys being the data source names and the values being the IDs.
`metadata`	object	An object containing additional metadata for the feature, if applicable.
`distance`	number	An approximate distance to the `origin` location, in meters. Only provided when `origin` and `navigation_profile` are used in the request.
`eta`	number	The estimated time of arrival from the origin point to the feature, in minutes. Only provided when `eta_type`, `origin`, and `navigation_profile` are used in the request. If an address is not on the road network, an ETA will not be provided.
`added_distance`	number	The distance added to an input route by including the given suggestion, in meters.
`added_time`	number	The estimated time added to an input route by including the given suggestion, in minutes.

Example responses: Get suggested results

{
  "suggestions": [
    {
      "name": "Michigan Stadium",
      "mapbox_id": "Example ID",
      "feature_type": "poi",
      "address": "1201 S Main St",
      "full_address": "1201 S Main St, Ann Arbor, Michigan 48104, United States of America",
      "place_formatted": "Ann Arbor, Michigan 48104, United States of America",
      "context": {
        "country": {
          "name": "United States of America",
          "country_code": "US",
          "country_code_alpha_3": "USA"
        },
        "region": {
          "name": "Michigan",
          "region_code": "MI",
          "region_code_full": "US-MI"
        },
        "postcode": {"name": "48104"},
        "place": {"name": "Ann Arbor"},
        "neighborhood": {"name": "South Main"},
        "street": {"name": "s main st"}
      },
      "language": "en",
      "maki": "marker",
      "poi_category": ["track", "sports"],
      "poi_category_ids": ["track", "sports"],
      "external_ids": {
        "safegraph": "Example ID",
        "foursquare": "Example ID"
      },
      "metadata": {}
    }
  ],
  "attribution": "© 2023 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)"
}

Retrieve a suggested feature

The /retrieve endpoint provides detailed information about a feature including geographic coordinates. In a search session, this endpoint is called when the user selects an item from the suggested results provided by /suggest endpoint. For more details, see the Retrieve a suggested feature section of this documentation.

get

https://api.mapbox.com/search/searchbox/v1/retrieve/{id}

After a successful call to the /suggest endpoint, you will use the ID contained in a suggestion's mapbox_id property to retrieve detailed information about the feature.

Required parameters	Type	Description
`access_token`	string	A Mapbox access token with default permissions.
`session_token`	string	A customer-provided session token value, which groups a series of requests together for billing purposes. UUIDv4 is recommended. For more information on how `session_token` is used to group Search API calls into one session, see the Session-based pricing section of this documentation.

Example request: Retrieve a suggested feature

# Retrieve a suggested feature

$ curl "https://api.mapbox.com/search/searchbox/v1/retrieve/{id}?session_token=[GENERATED-UUID]&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Retrieve a suggested feature

The /retrieve endpoint returns a GeoJSON FeatureCollection.

Property	Type	Description
`type`	string	This will always be `"FeatureCollection"`.
`features`	array of objects	The returned feature objects. See the table below for details on the properties contained by each feature object.
`attribution`	string	The attribution data for results.

Each feature in the response body contains the following properties:

Property	Type	Description
`type`	string	This will always be `"Feature"`.
`geometry`	object	An object describing the spatial geometry of the returned feature.
`geometry.coordinates`	array	The coordinates of the feature, formatted as `[longitude,latitude]`.
`geometry.type`	string	This will always be `"Point"`.
`properties`	object	The specific properties associated with the returned feature.
`properties.name`	string	The name of the feature.
`properties.name_preferred`	string	The preferred name of the feature, if different than `properties.name`.
`properties.mapbox_id`	string	The ID associated with the feature.
`properties.feature_type`	string	The type of the result. For POIs, this will be `poi`. For address-type results, the global context hierarchy is used (`country`, `region`, `postcode`, `district`, `place`, `locality`, `neighborhood`, `address`). See the Administrative unit types section for details about these types.
`properties.address`	string	The address of the result containing the address number and street.
`properties.full_address`	string	The full address of the result, which concatenates `properties.address` and `properties.place_formatted`.
`properties.place_formatted`	string	A formatted string of result context comprised of the place, region, country, and postcode. It is the part of the result which comes after `address`.
`properties.context`	object	The context of the feature.
`properties.context.country`	object	The country of the result. This layer includes properties `id`, `name`, `country_code` (the ISO_3166_1 alpha 2 code), and `country_code_alpha_3` (the ISO_3166_1 alpha 3 code).
`properties.context.region`	object	The region of the result. This layer includes properties `id`, `name`, `region_code`, and `region_code_full` (the ISO_3166_2 code).
`properties.context.postcode`	object	The postcode of the result. This layer includes properties `id` and `name`.
`properties.context.district`	object	The district of the result. This layer includes properties `id` and `name`.
`properties.context.place`	object	The place of the result. This layer includes properties `id` and `name`.
`properties.context.locality`	object	The locality of the result. This layer includes properties `id` and `name`.
`properties.context.neighborhood`	object	The neighborhood of the result. This layer includes properties `id` and `name`.
`properties.context.address`	object	The address of the result including the address number and street. This layer includes properties `id`, `name`, `address_number`, and `street_name`.
`properties.context.street`	object	The street of the result. This layer includes properties `id` and `name`.
`properties.coordinates`	object	The geographical coordinates of the result.
`properties.coordinates.longitude`	number	The longitudinal coordinate of the result.
`properties.coordinates.latitude`	number	The latitudinal coordinate of the result.
`properties.coordinates.accuracy`	string	The accuracy of the geographical coordinate of the result. This is only available for address-type results and the options are `rooftop`, `parcel`, `point`, `interpolated`, `intersection`, `approximate`, and `street`.
`properties.coordinates.routable_points`	array	An array of objects containing information about the feature's routable points. A routable point object contains properties `name`, `latitude`, and `longitude`.
`properties.bbox`	array	A bounding box in the format `minimum longitude`,`minimum latitude`,`maximum longitude`,`maximum latitude`.
`properties.language`	string	An IETF language tag indicating the language of the result.
`properties.maki`	string	A string representing an associated Maki icon to use for this result.
`properties.poi_category`	array	An array including the POI categories the result falls into, if it is a POI.
`properties.poi_category_ids`	array	An array including the canonical POI category IDs the result falls into, if it is a POI.
`properties.brand`	string	The brand name of the result, if it is a POI and is applicable.
`properties.brand_id`	string	The canonical brand ID of the result, if it is a POI and is applicable.
`properties.external_ids`	object	An object containing the IDs of the feature found in external databases, with the keys being the data source names and the values being the IDs.
`properties.metadata`	object	An object containing additional metadata for the feature, if applicable.

Example responses: Retrieve a suggested feature

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {"coordinates": [-83.748708, 42.265837], "type": "Point"},
      "properties": {
        "name": "Michigan Stadium",
        "mapbox_id": "Example ID",
        "feature_type": "poi",
        "address": "1201 S Main St",
        "full_address": "1201 S Main St, Ann Arbor, Michigan 48104, United States of America",
        "place_formatted": "Ann Arbor, Michigan 48104, United States of America",
        "context": {
          "country": {
            "name": "United States of America",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          },
          "region": {
            "name": "Michigan",
            "region_code": "MI",
            "region_code_full": "US-MI"
          },
          "postcode": {"name": "48104"},
          "place": {"name": "Ann Arbor"},
          "neighborhood": {"name": "South Main"},
          "street": {"name": "s main st"}
        },
        "coordinates": {
          "latitude": 42.265837,
          "longitude": -83.748708,
          "routable_points": [
            {"name": "default", "latitude": 42.265837, "longitude": -83.748708}
          ]
        },
        "maki": "marker",
        "poi_category": ["track", "sports"],
        "poi_category_ids": ["track", "sports"],
        "external_ids": {
          "safegraph": "Example ID",
          "foursquare": "Example ID"
        },
        "metadata": {}
      }
    }
  ],
  "attribution": "© 2023 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)"
}

Category Search

Category Search makes it possible to browse entire categories of results, like coffee shops, hotels, and bookstores around a specific location or along a route.

The /category endpoint provides a list of POIs for a given location. In a search use case, this endpoint is used to create hot-buttons to execute search for a specific category, e.g. a coffee button that surfaces all nearby coffee shops. For more details, see the Get category suggestions section of this documentation.

Retrieve POIs by category

get

https://api.mapbox.com/search/searchbox/v1/category/{canonical_category_id}

Use the Category Search endpoint if you want to query points of interest (POIs) results filtered by a category at a specific location or along a route. The endpoint will only return POIs with the specified category.

Examples how you can use the /category endpoint:

Find food around you (food_and_drink)
Find an Indian restaurant (indian_restaurant)
Find a gas station along a route (gas_station)

Required parameters	Type	Description
`access_token`	string	A Mapbox access token with default permissions.

You can further refine the results of a query to this endpoint with the following optional parameters:

Optional parameters	Type	Description
`language`	string	The ISO language code to be returned. If not provided, the default is English.
`limit`	integer	The number of results to return, up to 25.
`proximity`	string	Bias the response to favor results that are closer to a specific location. Provide either `ip` to get results closest to the user's IP location or provide two comma-separated coordinates in `longitude,latitude` order. If not provided, the default is IP proximity. When both `proximity` and `origin` are provided, `origin` is interpreted as the target of a route, while `proximity` indicates the current user location.
`origin`	number	The location from which to calculate distance, provided as two comma-separated coordinates in `longitude,latitude` order. When both `proximity` and `origin` are provided, `origin` is interpreted as the target of a route, while `proximity` indicates the current user location.
`bbox`	number	Limit results to only those contained within the supplied bounding box. Bounding boxes should be supplied as four numbers separated by commas, in `minimum longitude`,`minimum latitude`,`maximum longitude`,`maximum latitude` order. The bounding box cannot cross the 180th meridian.
`navigation_profile`	string	The navigation routing profile to use. Available profiles are: `driving`, `walking`, and `cycling`.
`route`	string	A polyline encoded linestring describing the route to be used for searching. This parameter enables searching along a route. Both polyline5 and polyline6 precision are accepted, but must be specified using the `route_geometry` parameter.
`route_geometry`	string	Passed in conjunction with a route polyline describing its precision. Options are `polyline` or `polyline6`. If this parameter is not provided with a `route`, the default is `polyline`. Accurate results depend on including the correct `route_geometry` for the `route` provided.
`sar_type`	string	This indicates that the user intends to perform a higher cost search-along-route request. This should be included when `route` is included and should have a value of `isochrone`.
`time_deviation`	number	Maximum detour in estimated minutes from route.
`country`	string	An ISO 3166 alpha 2 country code.
`types`	string	Limit results to one or more types of features, provided as a comma-separated list. Pass one or more of the type names as a comma separated list. If no types are specified, all possible types may be returned. Available types are: `country`, `region`, `postcode`, `district`, `place`, `city`, `locality`, `neighborhood`, `street`, and `address`. See the Administrative unit types section for details about these types.
`poi_category`	string	Limit results to those that belong to one or more categories, provided as a comma-separated list.
`radius`	number	Radius for the area to search within around a point.
`user_id`	string	A customer provided user id.
`rich_metadata_provider`	string	A comma-separated list of rich metadata providers to include in a suggestion result.
`poi_category_exclusions`	string	A comma-separated list of canonical category names that limits POI results to those that are not part of the given categories.

Example request: Retrieve a suggested feature

# Search for POIs in the `coffee` category 

$ curl -X GET "https://api.mapbox.com/search/searchbox/v1/category/coffee?access_token=YOUR_MAPBOX_ACCESS_TOKEN&language=en&limit=5&proximity=-122.41%2C39&bbox=-124.35526789303981%2C38.41262975705166%2C-120.52250410696067%2C39.54169087094499

Response: Retrieve POIs by category

The /category endpoints returns a GeoJSON FeatureCollection

Property	Type	Description
`type`	string	This will always be `"FeatureCollection"`.
`features`	array of objects	The returned feature objects. See the table below for details on the properties contained by each feature object.
`attribution`	string	The attribution data for results.

Each feature in the response body contains the following properties:

Property	Type	Description
`type`	string	This will always be `"Feature"`.
`geometry`	object	An object describing the spatial geometry of the returned feature.
`geometry.coordinates`	array	The coordinates of the feature, formatted as `[longitude,latitude]`.
`geometry.type`	string	This will always be `"Point"`.
`properties`	object	The specific properties associated with the returned feature.
`properties.name`	string	The name of the feature.
`properties.name_preferred`	string	The preferred name of the feature, if different than `properties.name`.
`properties.mapbox_id`	string	The ID associated with the feature.
`properties.feature_type`	string	The type of the result. For POIs, this will be `poi`. For address-type results, the global context hierarchy is used (`country`, `region`, `postcode`, `district`, `place`, `locality`, `neighborhood`, `address`). See the Administrative unit types section for details about these types.
`properties.address`	string	The address of the result containing the address number and street.
`properties.full_address`	string	The full address of the result, which concatenates `properties.address` and `properties.place_formatted`.
`properties.place_formatted`	string	A formatted string of result context comprised of the place, region, country, and postcode. It is the part of the result which comes after `address`.
`properties.context`	object	The context of the feature.
`properties.context.country`	object	The country of the result. This layer includes properties `id`, `name`, `country_code` (the ISO_3166_1 alpha 2 code), and `country_code_alpha_3` (the ISO_3166_1 alpha 3 code).
`properties.context.region`	object	The region of the result. This layer includes properties `id`, `name`, `region_code`, and `region_code_full` (the ISO_3166_2 code).
`properties.context.postcode`	object	The postcode of the result. This layer includes properties `id` and `name`.
`properties.context.district`	object	The district of the result. This layer includes properties `id` and `name`.
`properties.context.place`	object	The place of the result. This layer includes properties `id` and `name`.
`properties.context.locality`	object	The locality of the result. This layer includes properties `id` and `name`.
`properties.context.neighborhood`	object	The neighborhood of the result. This layer includes properties `id` and `name`.
`properties.context.address`	object	The address of the result including the address number and street. This layer includes properties `id`, `name`, `address_number`, and `street_name`.
`properties.context.street`	object	The street of the result. This layer includes properties `id` and `name`.
`properties.coordinates`	object	The geographical coordinates of the result.
`properties.coordinates.longitude`	number	The longitudinal coordinate of the result.
`properties.coordinates.latitude`	number	The latitudinal coordinate of the result.
`properties.coordinates.accuracy`	string	The accuracy of the geographical coordinate of the result. This is only available for address-type results and the options are `rooftop`, `parcel`, `point`, `interpolated`, `intersection`, `approximate`, and `street`.
`properties.coordinates.routable_points`	array	An array of objects containing information about the feature's routable points. A routable point object contains properties `name`, `latitude`, and `longitude`.
`properties.bbox`	array	A bounding box in the format `minimum longitude`,`minimum latitude`,`maximum longitude`,`maximum latitude`.
`properties.language`	string	An IETF language tag indicating the language of the result.
`properties.maki`	string	A string representing an associated Maki icon to use for this result.
`properties.poi_category`	array	An array including the POI categories the result falls into, if it is a POI.
`properties.poi_category_ids`	array	An array including the canonical POI category IDs the result falls into, if it is a POI.
`properties.brand`	string	The brand name of the result, if it is a POI and is applicable.
`properties.brand_id`	string	The canonical brand ID of the result, if it is a POI and is applicable.
`properties.external_ids`	object	An object containing the IDs of the feature found in external databases, with the keys being the data source names and the values being the IDs.
`properties.metadata`	object	An object containing additional metadata for the feature, if applicable.

Example response: Retrieve a POI by category

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "coordinates": [-122.582748, 39.029528], "type": "Point" },
      "properties": {
        "name": "Stonehouse Cellars",
        "mapbox_id": "CkIKQDRlNTdiODcxY2QyZjI0OGMwODNjZjE2Yzc1NTIyZDEyMjAyYzkzMmYzYTIwN2YwOTQ4ZDYxYjk1MTU5MmQ4ZjY=",
        "feature_type": "poi",
        "address": "500 Old Long Valley Rd",
        "full_address": "500 Old Long Valley Rd, Clearlake Oaks, California 95423, United States of America",
        "place_formatted": "Clearlake Oaks, California 95423, United States of America",
        "context": {
          "country": {
            "name": "United States of America",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          },
          "region": {
            "name": "California",
            "region_code": "CA",
            "region_code_full": "US-CA"
          },
          "postcode": { "name": "95423" },
          "place": { "name": "Clearlake Oaks" },
          "street": { "name": "old long valley rd" }
        },
        "coordinates": {
          "latitude": 39.029528,
          "longitude": -122.582748,
          "routable_points": [
            {
              "name": "default",
              "latitude": 39.029528,
              "longitude": -122.582748
            }
          ]
        },
        "maki": "restaurant",
        "poi_category": [
          "restaurant",
          "food",
          "food and drink",
          "winery",
          "bar",
          "nightlife"
        ],
        "poi_category_ids": [
          "restaurant",
          "food",
          "food_and_drink",
          "winery",
          "bar",
          "nightlife"
        ],
        "external_ids": { "foursquare": "55208bfe498e78a725b4030d" },
        "metadata": { "primary_photo": [] }
      }
    }
  ],
  "attribution": "© 2023 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)"
}

The request to the /list/category endpoint will return a list of all the available categories with their canonical ID and name in the language you specified. This endpoint does not describe parent/child relationships and cannot be used to infer relationships between categories.

get

https://api.mapbox.com/search/searchbox/v1/list/category

Required parameters	Type	Description
`access_token`	string	A Mapbox access token with default permissions.

Optional parameters	Type	Description
`language`	string	The ISO language code to be returned. If not provided, English (en) will be used as the default.


# Get category list

$ curl -X GET "https://api.mapbox.com/search/searchbox/v1/list/category?access_token=YOUR_MAPBOX_ACCESS_TOKEN&language=en"

The response will be a collection of category list items.

Property	Type	Description
`list_items`	array	This will always be `"Feature"`.
`attribution`	string	The attribution data for results.
`version`	string	The service version information. Include this information if you report an issue to Mapbox.

Each item in list_items has the following properties:

Property	Type	Description
`canonical_id`	string	The canonical category ID to use in a category “Hot Button” search
`icon`	string	The maki icon to use with the category
`name`	string	The category name in the requested language

{
    "listItems": [
        {
            "canonical_id": "services",
            "icon": "marker",
            "name": "Services",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "71fed985-aa4b-4e50-83f1-97e5a0a0751e"
        },
        {
            "canonical_id": "shopping",
            "icon": "marker",
            "name": "Shopping",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "9d383df0-2f35-4932-9368-8cf0f488e701"
        },
        {
            "canonical_id": "food_and_drink",
            "icon": "marker",
            "name": "Food and Drink",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "20dbf11b-a90d-4571-8996-a1ccbfbd8680"
        },
        {
            "canonical_id": "food",
            "icon": "restaurant",
            "name": "Food",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "af0d6328-1e96-43d7-8925-decb4ed04a06"
        },
        {
            "canonical_id": "restaurant",
            "icon": "restaurant",
            "name": "Restaurant",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "1a9e12e7-2e8d-47ee-9c3d-1aaa7ced55b6"
        },
        {
            "canonical_id": "health_services",
            "icon": "marker",
            "name": "Health Services",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "f111ad81-9b4f-4346-b1dd-d7190a202276"
        },
        {
            "canonical_id": "office",
            "icon": "marker",
            "name": "Office",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "8388a638-fdae-42f0-b3e7-ee1c1f786601"
        },
        {
            "canonical_id": "education",
            "icon": "marker",
            "name": "Education",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "c530d2d8-ee87-4481-9289-088b97b796fa"
        },
        {
            "canonical_id": "nightlife",
            "icon": "marker",
            "name": "Nightlife",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "ecd6c887-9952-45a1-848d-ee50177cb61d"
        },
        {
            "canonical_id": "lodging",
            "icon": "lodging",
            "name": "Lodging",
            "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
            "uuid": "8de7b125-ac68-488f-b122-5c8b2706ff15"
        }
    ],
    "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
    "version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629"
}

Reverse lookup

With Reverse lookup, you can get a list of addresses and POIs around a given coordinate (e,g, what is around 33.9416° N, 118.4085° W).

The /reverse endpoint allows you to look up a single pair of coordinates and returns the geographic feature or features that exist at that location.

Perform a reverse lookup

get

https://api.mapbox.com/search/searchbox/v1/reverse?longitude={longitude}&latitude={latitude}

Required parameters	Type	Description
`access_token`	string	A Mapbox access token with default permissions.
`longitude`	string	The longitudinal coordinate of coordinate for the reverse query.
`latitude`	string	The latitudinal coordinate of coordinate for the reverse query.

You can further refine the results of a query to this endpoint with the following optional parameters:

Optional parameters	Type	Description
`language`	string	The ISO language code to be returned. If not provided, the default is English.
`limit`	integer	The number of results to return, up to 10.
`country`	string	An ISO 3166 alpha 2 country code.
`types`	string	Limit results to one or more types of features, provided as a comma-separated list. Pass one or more of the type names as a comma separated list. If no types are specified, all possible types may be returned. Available types are: `country`, `region`, `prefecture`, `postcode`, `district`, `place`, `city`, `locality`, `oaza`, `block`, `street`, and `address`. See the Administrative unit types section for details about these types.

Example request: Perform a reverse lookup

$ curl "https://api.mapbox.com/search/searchbox/v1/reverse?longitude=-118.471383&latitude=34.023653&language=de&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Perform a reverse lookup

The response to a request to the /reverse endpoint is a GeoJSON FeatureCollection.

Property	Type	Description
`type`	string	This will always be `"FeatureCollection"`.
`features`	array of objects	The returned feature objects. See the table below for details on the properties contained by each feature object.
`attribution`	string	The attribution data for results.

Each feature in the response body contains the following properties:

Property	Type	Description
`type`	string	This will always be `"Feature"`.
`geometry`	object	An object describing the spatial geometry of the returned feature.
`geometry.coordinates`	array	The coordinates of the feature, formatted as `[longitude,latitude]`.
`geometry.type`	string	This will always be `"Point"`.
`properties`	object	The specific properties associated with the returned feature.
`properties.name`	string	The name of the feature.
`properties.name_preferred`	string	The preferred name of the feature, if different than `properties.name`.
`properties.mapbox_id`	string	The ID associated with the feature.
`properties.feature_type`	string	The type of the result. For POIs, this will be `poi`. For address-type results, the global context hierarchy is used (`country`, `region`, `postcode`, `district`, `place`, `locality`, `neighborhood`, `address`). See the Administrative unit types section for details about these types.
`properties.address`	string	The address of the result containing the address number and street.
`properties.full_address`	string	The full address of the result, which concatenates `properties.address` and `properties.place_formatted`.
`properties.place_formatted`	string	A formatted string of result context comprised of the place, region, country, and postcode. It is the part of the result which comes after `address`.
`properties.context`	object	The context of the feature.
`properties.context.country`	object	The country of the result. This layer includes properties `id`, `name`, `country_code` (the ISO_3166_1 alpha 2 code), and `country_code_alpha_3` (the ISO_3166_1 alpha 3 code).
`properties.context.region`	object	The region of the result. This layer includes properties `id`, `name`, `region_code`, and `region_code_full` (the ISO_3166_2 code).
`properties.context.postcode`	object	The postcode of the result. This layer includes properties `id` and `name`.
`properties.context.district`	object	The district of the result. This layer includes properties `id` and `name`.
`properties.context.place`	object	The place of the result. This layer includes properties `id` and `name`.
`properties.context.locality`	object	The locality of the result. This layer includes properties `id` and `name`.
`properties.context.neighborhood`	object	The neighborhood of the result. This layer includes properties `id` and `name`.
`properties.context.address`	object	The address of the result including the address number and street. This layer includes properties `id`, `name`, `address_number`, and `street_name`.
`properties.context.street`	object	The street of the result. This layer includes properties `id` and `name`.
`properties.coordinates`	object	The geographical coordinates of the result.
`properties.coordinates.longitude`	number	The longitudinal coordinate of the result.
`properties.coordinates.latitude`	number	The latitudinal coordinate of the result.
`properties.coordinates.accuracy`	string	The accuracy of the geographical coordinate of the result. This is only available for address-type results and the options are `rooftop`, `parcel`, `point`, `interpolated`, `intersection`, `approximate`, and `street`.
`properties.coordinates.routable_points`	array	An array of objects containing information about the feature's routable points. A routable point object contains properties `name`, `latitude`, and `longitude`.
`properties.bbox`	array	A bounding box in the format `minimum longitude`,`minimum latitude`,`maximum longitude`,`maximum latitude`.
`properties.language`	string	An IETF language tag indicating the language of the result.
`properties.maki`	string	A string representing an associated Maki icon to use for this result.
`properties.poi_category`	array	An array including the POI categories the result falls into, if it is a POI.
`properties.poi_category_ids`	array	An array including the canonical POI category IDs the result falls into, if it is a POI.
`properties.brand`	string	The brand name of the result, if it is a POI and is applicable.
`properties.brand_id`	string	The canonical brand ID of the result, if it is a POI and is applicable.
`properties.external_ids`	object	An object containing the IDs of the feature found in external databases, with the keys being the data source names and the values being the IDs.
`properties.metadata`	object	An object containing additional metadata for the feature, if applicable.

Example response: Perform a reverse lookup

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "coordinates": [13.3295589, 52.5125463], "type": "Point" },
      "properties": {
        "name": "Straße Des 17. Juni 115",
        "mapbox_id": "dXJuOm1ieGFkcjo2YjU1MDMxMy1iNzM0LTQxNjYtYjk0MC0zZTU1MTE4MmQwOGY",
        "feature_type": "address",
        "address": "Straße Des 17. Juni 115",
        "full_address": "Straße Des 17. Juni 115, 10623 Berlin, Germany",
        "place_formatted": "10623 Berlin, Germany",
        "context": {
          "country": {
            "id": "dXJuOm1ieHBsYzpJam8",
            "name": "Germany",
            "country_code": "DE",
            "country_code_alpha_3": "DEU"
          },
          "postcode": { "id": "dXJuOm1ieHBsYzpVYTQ2", "name": "10623" },
          "place": { "id": "dXJuOm1ieHBsYzpBY1E2", "name": "Berlin" },
          "locality": {
            "id": "dXJuOm1ieHBsYzpBd1pxT2c",
            "name": "Charlottenburg"
          },
          "address": {
            "id": "dXJuOm1ieGFkcjo2YjU1MDMxMy1iNzM0LTQxNjYtYjk0MC0zZTU1MTE4MmQwOGY",
            "name": "Straße Des 17. Juni 115",
            "address_number": "Straße",
            "street_name": "Des 17. Juni 115"
          },
          "street": { "name": "Des 17. Juni 115" }
        },
        "coordinates": {
          "latitude": 52.5125463,
          "longitude": 13.3295589,
          "accuracy": "rooftop",
          "routable_points": [
            {
              "name": "default",
              "latitude": 52.51264818693428,
              "longitude": 13.32955240836938
            }
          ]
        },
        "language": "en",
        "maki": "marker",
        "external_ids": {},
        "metadata": {}
      }
    }
  ],
  "attribution": "© 2023 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)"
}

Administrative unit types

Various types of administrative units are available via the Search Box API. Any type might appear as a top-level response, as context in a top-level response, or as a filtering option using the optional types parameter. See the following table for available administrative unit types.

Administrative unit type	Description
`country`	Generally recognized countries or, in some cases like Hong Kong, an area of quasi-national administrative status that has been given a designated country code under ISO 3166-1.
`region`	Top-level sub-national administrative features, such as states in the United States or provinces in Canada or China.
`postcode`	Postal codes used in country-specific national addressing systems.
`district`	Features that are smaller than top-level administrative features but typically larger than cities, in countries that use such an additional layer in postal addressing (for example, prefectures in China).
`place`	Typically these are cities, villages, municipalities, etc. They’re usually features used in postal addressing, and are suitable for display in ambient end-user applications where current-location context is needed (for example, in weather displays).
`locality`	Official sub-city features present in countries where such an additional administrative layer is used in postal addressing, or where such features are commonly referred to in local parlance. Examples include city districts in Brazil and Chile and arrondissements in France.
`neighborhood`	Colloquial sub-city features often referred to in local parlance. Unlike `locality` features, these typically lack official status and may lack universally agreed-upon boundaries. Not available for reverse lookup requests.
`street`	The street, with no house number.
`address`	Individual residential or business addresses as a street with house number.

Language and Geography Support

Supported languages

The Search Box API supports text queries in following languages; Czech, Croatian, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Japanese, Lithuanian, Latvian, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Turkish, Ukrainian.

You can set a language by providing supported IETF language tags to the language API parameter. You can also provide a comma separated list of language codes. In this case, the first supported language encountered in the list will be used to process the request.

Supported geographies

The Search Box API supports United States, Canada and Europe. More locales will be rolled out incrementally throughout the Public Preview.

Response body `message`	HTTP error code	Description
`Not authorized`	`401`	Check the access token used in the query.
`Bad request`	`400`	Check the the request for syntax errors in the endpoint, path parameters, and query parameters.
`Forbidden`	`403`	There may be an issue with your account. Check your Account page for more details. In some cases, using an access tokens with URL restrictions can also result in a `403` error. For more information, see our Token management guide.

The Mapbox Terms of Service state that all data returned by the Search Box API endpoints is only available for temporary use. If your use case requires storing position data, contact Mapbox sales.
The default rate limit for the Mapbox Search Box API is 10 requests per second. If you require a higher rate limit, contact Mapbox Sales.
Calls to the Search Box API's /suggest and /retrieve endpoints must include a session_token parameter. Each API call in a search session counts individually against the rate limit. For example, 10 sequential calls to /suggest with the same session_token and one call to /retrieve are 11 requests per the rate limit, but are billed as belonging to a single session. See more about how the Search Box API is billed in the Session Billing section of this documentation.

Pricing for the Mapbox Search Box API is based on which API endpoints are used. If you are using the /suggest or /retrieve endpoints, usage will be billed per search session. If you are using the /category or /reverse endpoints, usage will be billed per request.

For more details, please review Mapbox Search Pricing.

Session Billing

A Search Session is a series of Search API calls bundled together for billing purposes. The Search Box API's /suggest and /retrieve endpoints must include a session_token parameter. The session_token parameter is used to group a series of requests together into one session for billing purposes.

A session ends after the following actions:

A call is made to /suggest followed by a call to /retrieve with a common session_token.
50 successive calls are made to /suggest with a common session_token but are not followed by a call to /retrieve.
A call is made to /suggest and 60 minutes pass without being followed by a call to /retrieve.

Documentation for Mapbox Search API (earlier release) is available at https://docs.mapbox.com/search/search/.