Search | API | Mapbox

Documentation for the Search API is also available in Japanese.

Public beta for the Search API

The Mapbox Search API is in public beta. During the public beta phase, the Mapbox Search API is only available for Japanese-language queries for locations in Japan. If you want a service that provides worldwide search results for queries in a variety of languages, use the Mapbox Geocoding API.

Your feedback will help us improve the Search API during the public beta phase.

The Mapbox Search API can be used to provide an interactive search experience for end users, or can support stand-alone forward and reverse geocoding queries.

playground

Search API playground

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

guide

Japan-specific considerations for the Search API

When you are using the Mapbox Search API to do Japanese-language searches for Japanese locations, several factors can impact the quality of the results you receive, include the scripts that the Search API supports, the Japanese address data coverage, and how to format search queries.

Search API endpoints

The Search API includes six different endpoints: /suggest, /retrieve, /forward, /permanent/forward, /reverse, and /permanent/reverse.

Suggest

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 searches to the /suggest endpoint. When a user selects a result on the application UI, that gets sent to the /retrieve endpoint. For more details, see the Retrieve a suggestion section of this documentation.

Retrieve

If the user selects one of the results from the /suggest endpoint, that gets sent to the /retrieve endpoint, which provides detailed information about that feature including geographic coordinates. Once a /retrieve action is taken, the Search API returns GeoJSON with coordinate information for the selected feature or features. For more details, see the Retrieve a suggested feature section of this documentation.

Forward geocoding

The /forward endpoint allows you to look up a single location by name and returns its geographic coordinates. For more details, see the Forward geocoding section of this documentation.

Permanent forward geocoding

The /permanent/forward endpoint is used for use cases that require storing position data. Like the /forward endpoint, it allows you to look up a single location by name and returns its geographic coordinates. For more details, see the Permanent forward geocoding section of this documentation.

Reverse geocoding

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. For more details, see the Reverse geocoding section of this documentation.

Permanent reverse geocoding

The /permanent/reverse endpoint is used for use cases that require storing position data. Like the /reverse endpoint, it allows you to look up a single pair of coordinates and returns the geographic feature or features that exist at that location. For more details, see the Permanent reverse geocoding section of this documentation.

Administrative unit types

Various types of administrative units are available via the Search 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.
`prefecture`	Japanese administrative unit analogous to `region`.
`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).
`city`	Japanese administrative unit analogous to `place`.
`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.
`oaza`	Japanese administrative unit analogous to `locality`.
`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 geocoding requests.
`chome`	Japanese administrative unit analogous to `neighborhood`. Not available for reverse geocoding requests.
`block`	The block number.
`street`	The street, with no house number.
`address`	Individual residential or business addresses as a street with house number. In a Japanese context, this is the block number and the house number. All components smaller than `chome` are designated as an `address`.

Retrieve a suggestion

get

/search/v1/suggest/{search_text}

Retrieve a suggestion. This endpoint provides place predictions about what an end user is searching for, based on autocomplete of the user query. This endpoint, along with the retrieve endpoint, can be used to add autocomplete functionality to applications that include geographic searches.

POI search not available

During the Search API's public beta phase, point of interest (POI) search is not available. This includes named buildings, local stores, and areas of interest such as public parks. POI search will be implemented later in the development process. If you need POI search capabilities right now, we suggest using the Mapbox Geocoding API.

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.
`search_text`	string	The user's query string. The query string is limited to 120 characters.
`language`	string	The ISO language code to be returned. For the most accurate results, this parameter's value should be `ja`.
`country`	string	An ISO 3166 alpha 2 country code. For the most accurate results, this parameter's value should be `JP`.

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

Optional parameters	Type	Description
`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.
`limit`	integer	The number of results to return, up to 10.
`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.
`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.
`proximity`	number	Bias the response to favor results that are closer to this location, 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.
`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.
`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`, `neighborhood`, `chome`, `block`, `street`, and `address`. See the Administrative unit types section for details about these types.

Example request: Retrieve a suggestion

# Search for 新橋一丁十番一号,東京都港区新橋1丁目10番1号 with limit=1

$ curl "https://api.mapbox.com/search/v1/suggest/新橋一丁十番一号,東京都港区新橋1丁目10番1号?language=ja&limit=1&session_token=[GENERATED-UUID]&proximity=13.38333,52.51667&country=JP&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Retrieve a suggestion

The response to a request to the /suggest endpoint is an array of JSON suggestion objects. A suggestion will include a result name, a short description, 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 information provided in the /suggest result's "action" block. The "action" block is opaque and can be used without inspection in your application.

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
`attribution`	string	The attribution data for results.
`version`	string	The service version information. Include this information if you report an issue to Mapbox.
`response_uuid`	string	The service response identifier. Include this information if you report an issue to Mapbox.
`suggestions`	array of objects	The returned suggestion objects. See the table below for details on the properties contained by each suggestion object.

Each suggestion object contains the following properties:

Property	Type	Description
`feature_name`	string	The name of the feature.
`matching_name`	string	The feature name, as matched by the search algorithm.
`description`	string	Additional details, such as city and state for addresses.
`action`	object	The action block indicates the next step to continue with this suggestion.
`action.endpoint`	string	The endpoint to point the next request to. The current options are `suggest` and `retrieve`. The `/suggest` call is used when the API determines the next best option is another round of suggestions, and the `/retrieve` call is used when the API determines it understands what feature the user is looking for and that the user is ready for the geographic coordinates of the results.
`action.method`	string	The type of HTTP methods that are allowed for the next request. Options are `POST` or, less commonly, `GET`.
`action.body`	object	The body to pass to `HTTP POST /retrieve` when fetching GeoJSON.
`action.multi_retrievable`	boolean	Indicates whether the feature can be fetched as part of a batch retrieve. Not applicable during the public beta phase.
`result_type`	array	The type of result using the global context hierarchy (`region`, `place`, `locality`, `neighborhood`, `address`). See the Administrative unit types section for details about these types.
`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"`.
`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 feature to the origin point 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.
`maki`	string	A string representing an associated Maki icon to use for this result.
`language`	string	An IETF language tag indicating the language of the result.
`internal_id`	string	ID for internal metadata. This ID is not guaranteed to be stable or unique, and is not useful for development.
`external_ids`	object	IDs passed through from external data providers. These IDs are not guaranteed to be stable or unique, and are not useful for development.
`context`	array	The context of the feature.
`context.localized_layer`	string	The Japanese `place_type`. See the Administrative unit types section for details about these place types.
`context.layer`	string	The global `place_type` that corresponds to the Japanese `place_type` in `context.localized_layer`. See the Administrative unit types section for details about these place types.
`context.name`	string	The name of the feature.
`metadata`	object	Japanese address metadata fields.
`metadata.iso_3166_1`	string	The country code.
`metadata.iso_3166_2`	string	The country code and its country subdivision code.

Example response: Retrieve a suggestion

{
  "suggestions": [{
    "feature_name": "〒105-0004 東京都港区新橋1丁目10番1号",
    "matching_name": "〒105-0004 東京都港区新橋1丁目10番1号",
    "description": "",
    "result_type": [
      "address"
    ],
    "language": "ja",
    "action": {
      "endpoint": "retrieve",
      "method": "POST",
      "body": {
        "id": "abc123"
      },
      "multi_retrievable": false
    },
    "maki": "marker",
    "internal_id": "example internal id",
    "external_ids": {
      "service": "2wwRMXwBRYqRl13lTvTP"
    },
    "context": [{
        "layer": "block",
        "localized_layer": "block",
        "name": "10"
      },
      {
        "layer": "neighborhood",
        "localized_layer": "chome",
        "name": "1丁目"
      },
      {
        "layer": "locality",
        "localized_layer": "oaza",
        "name": "新橋"
      },
      {
        "layer": "place",
        "localized_layer": "city",
        "name": "港区"
      },
      {
        "layer": "region",
        "localized_layer": "prefecture",
        "name": "東京都"
      }
    ],
    "metadata": {
      "iso_3166_1": "jp",
      "iso_3166_2": "JP-13",
      "reading": {
        "ja_kana": "ﾄｳｷｮｳﾄﾐﾅﾄｸｼﾝﾊﾞｼ",
        "ja_latin": "toukyouto minatoku shinbashi"
      }
    }
  }],
  "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": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "4b659949-c8c7-42d8-a541-6b427e5806cc"
}

Retrieve a suggested feature

post

/search/v1/retrieve/

After a successful call to the /suggest endpoint, you will use the information contained in the response's action block to retrieve detailed information about the feature. Using this endpoint requires no knowledge of what the possible parameters to pass are. Instead, you must pass information in the action block returned from the call to /suggest to this endpoint.

POI search not available

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.

Request body properties	Type	Description
`id`	string	The ID of the suggestion to retrieve, taken from `action.body.id` in the response from the `/suggest` endpoint.

Example request: Retrieve a suggested feature

POST /search/v1/retrieve?session_token=[GENERATED-UUID]&access_token=YOUR_MAPBOX_ACCESS_TOKEN

Example request body:

{
	"id": "12345"
}

Response: Retrieve a suggested feature

The /retrieve endpoint returns a GeoJSON FeatureCollection.

Property	Type	Description
`type`	string	This will always be `"FeatureCollection"`.
`attribution`	string	The attribution data for results.
`version`	string	The service version information. Include this information if you report an issue to Mapbox.
`response_uuid`	string	The service response identifier. Include this information if you report an issue to Mapbox.
`features`	array of objects	The returned feature objects. See the table below for details on the properties contained by each feature object.

Each feature in the response body contains the following properties:

Property	Type	Description
`bbox`	array	A bounding box in the format `minimum longitude`,`minimum latitude`,`maximum longitude`,`maximum latitude`. Not available during the public beta phase.
`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"`.
`type`	string	This will always be `"Feature"`.
`properties`	object	Specific properties associated with the returned feature.
`properties.maki`	string	A string representing an associated Maki icon to use for this result.
`properties.metadata`	object	Japanese address metadata fields.
`properties.metadata.iso_3166_1`	string	The country code.
`properties.metadata.iso_3166_2`	string	The country code and its country subdivision code.
`properties.address`	string	For results with an address, the locally formatted address.
`properties.feature_name`	string	The name of the feature.
`properties.matching_name`	string	The feature name, as matched by the search algorithm.
`properties.internal_id`	string	ID for internal metadata. This ID is not guaranteed to be stable or unique, and is not useful for development.
`properties.external_ids`	object	IDs passed through from external data providers. These IDs are not guaranteed to be stable or unique, and are not useful for development.
`properties.place_type`	array	The result type. See the Administrative unit types section for details about these place types.
`properties.language`	string	The IETF language tag.
`properties.address_number`	string	The house number for address objects.
`properties.context`	array of objects	The context of the feature.
`properties.context.localized_layer`	string	The Japanese `place_type`. See the Administrative unit types section for details about these place types.
`properties.context.layer`	string	The global `place_type` that corresponds to the Japanese `properties.place_type` in `context.localized_layer`. See the Administrative unit types section for details about these place types.
`properties.context.name`	string	The name of the feature.

Example response: Retrieve a suggested feature

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "coordinates": [
        139.7596417,
        35.6675028
      ],
      "type": "Point"
    },
    "properties": {
      "feature_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "matching_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "description": "",
      "place_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "id": "2wwRMXwBRYqRl13lTvTP",
      "place_type": [
        "address"
      ],
      "context": [{
          "layer": "block",
          "localized_layer": "block",
          "name": "10"
        },
        {
          "layer": "chome",
          "localized_layer": "chome",
          "name": "1丁目"
        },
        {
          "layer": "oaza",
          "localized_layer": "oaza",
          "name": "新橋"
        },
        {
          "layer": "city",
          "localized_layer": "city",
          "name": "港区"
        },
        {
          "layer": "prefecture",
          "localized_layer": "prefecture",
          "name": "東京都"
        }
      ],
      "language": "ja",
      "maki": "marker",
      "internal_id": "example internal id",
      "external_ids": {
        "japan_address": "2wwRMXwBRYqRl13lTvTP"
      },
      "accuracy": "rooftop",
      "address": "〒105-0004 東京都港区新橋1丁目10番1号",
      "address_number": "1",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13",
        "reading": {
          "ja_kana": "ﾄｳｷｮｳﾄﾐﾅﾄｸｼﾝﾊﾞｼ",
          "ja_latin": "toukyouto minatoku shinbashi"
        }
      }
    }
  }],
  "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": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "55491b50-f5df-4725-aeb1-3e8ed4a07b17"
}

Forward geocoding

get

/search/v1/forward/{search_text}

Retrieve detailed information about a specific feature, including geographic coordinates, in response to a user query.

POI search not available

Required parameters	Type	Description
`access_token`	string	A Mapbox access token with default permissions.
`search_text`	string	The user's query string. The query string is limited to 120 characters.
`language`	string	The ISO language code to be returned. For the most accurate results, this parameter's value should be `ja`.
`country`	string	An ISO 3166 alpha 2 country code. For the most accurate results, this parameter's value should be `JP`.

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

Optional parameters	Type	Description
`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.
`limit`	integer	The number of results to return, up to 10.
`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.
`proximity`	number	Bias the response to favor results that are closer to this location, 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.
`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`, `neighborhood`, `chome`, `block`, `street`, and `address`. See the Administrative unit types section for details about these types.

Example request: Forward geocoding

$ curl "https://api.mapbox.com/search/v1/forward/新橋一丁十番一号,東京都港区新橋1丁目10番1号?language=ja&limit=1&proximity=13.38333,52.51667&country=JP&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Permanent forward geocoding

get

/search/v1/permanent/forward/{search_text}

The Mapbox Terms of Service state that all data returned by the /suggest, /retrieve, /forward, or /reverse endpoints is only available for temporary use. If your use case requires storing position data, contact Mapbox sales. This is consistent with the Terms of Service for Mapbox Geocoding API calls made to the mapbox.places-permanent endpoint.

The /permanent/forward endpoint takes the same path and query parameters as the /forward endpoint.

Response: Forward geocoding

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

Property	Type	Description
`type`	string	This will always be `"FeatureCollection"`.
`attribution`	string	The attribution data for results.
`version`	string	The service version information. Include this information if you report an issue to Mapbox.
`response_uuid`	string	The service response identifier. Include this information if you report an issue to Mapbox.
`features`	array of objects	The returned feature objects. See the table below for details on the properties contained by each feature object.

Each feature in the response body contains the following properties:

Property	Type	Description
`bbox`	array	A bounding box in the format `minimum longitude`,`minimum latitude`,`maximum longitude`,`maximum latitude`. Not available during the public beta phase.
`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"`.
`type`	string	This will always be `"Feature"`.
`properties`	object	Specific properties associated with the returned feature.
`properties.maki`	string	A string representing an associated Maki icon to use for this result.
`properties.metadata`	object	Japanese address metadata fields.
`properties.metadata.iso_3166_1`	string	The country code.
`properties.metadata.iso_3166_2`	string	The country code and its country subdivision code.
`properties.address`	string	For results with an address, the locally formatted address.
`properties.address_number`	string	The house number for address objects.
`properties.feature_name`	string	The name of the feature.
`properties.matching_name`	string	The feature name, as matched by the search algorithm.
`properties.place_type`	array	The result type. See the Administrative unit types section for details about these place types.
`properties.language`	string	The IETF language tag.
`properties.internal_id`	string	ID for internal metadata. This ID is not guaranteed to be stable or unique, and is not useful for development.
`properties.external_ids`	object	IDs passed through from external data providers. These IDs are not guaranteed to be stable or unique, and are not useful for development.
`properties.context`	array of objects	The context of the feature.
`properties.context.localized_layer`	string	The Japanese `place_type`. See the Administrative unit types section for details about these place types.
`properties.context.layer`	string	The global `place_type` that corresponds to the Japanese `properties.place_type` in `context.localized_layer`. See the Administrative unit types section for details about these place types.
`properties.context.name`	string	The name of the feature.

Example response: Forward geocoding

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "coordinates": [
        139.7596417,
        35.6675028
      ],
      "type": "Point"
    },
    "properties": {
      "feature_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "matching_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "description": "",
      "place_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "id": "2wwRMXwBRYqRl13lTvTP",
      "place_type": [
        "address"
      ],
      "context": [{
          "layer": "block",
          "localized_layer": "block",
          "name": "10"
        },
        {
          "layer": "chome",
          "localized_layer": "chome",
          "name": "1丁目"
        },
        {
          "layer": "oaza",
          "localized_layer": "oaza",
          "name": "新橋"
        },
        {
          "layer": "city",
          "localized_layer": "city",
          "name": "港区"
        },
        {
          "layer": "prefecture",
          "localized_layer": "prefecture",
          "name": "東京都"
        }
      ],
      "language": "ja",
      "maki": "marker",
      "internal_id": "example internal id",
      "external_ids": {
        "japan_address": "2wwRMXwBRYqRl13lTvTP"
      },
      "accuracy": "rooftop",
      "address": "〒105-0004 東京都港区新橋1丁目10番1号",
      "address_number": "1",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13",
        "reading": {
          "ja_kana": "ﾄｳｷｮｳﾄﾐﾅﾄｸｼﾝﾊﾞｼ",
          "ja_latin": "toukyouto minatoku shinbashi"
        }
      }
    }
  }],
  "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": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "733725e4-3992-43e5-9cad-bac75698eb59"
}

Reverse geocoding

get

/search/v1/reverse/{search_text}

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.

Required parameters	Type	Description
`access_token`	string	A Mapbox access token with default permissions.
`search_text`	string	The user's query string. The query string is limited to 120 characters.
`language`	string	The ISO language code to be returned. For the most accurate results, this parameter's value should be `ja`.

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

Optional parameters	Type	Description
`limit`	integer	The number of results to return, up to 10.
`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: Reverse geocoding

$ curl "https://api.mapbox.com/search/v1/reverse/139.58028,35.29556?language=ja&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Permanent reverse geocoding

get

/search/v1/permanent/reverse/{search_text}

The /permanent/reverse endpoint takes the same path and query parameters as the /reverse endpoint.

Response: Reverse geocoding

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

Property	Type	Description
`type`	string	This will always be `"FeatureCollection"`.
`attribution`	string	The attribution data for results.
`version`	string	The service version information. Include this information if you report an issue to Mapbox.
`response_uuid`	string	The service response identifier. Include this information if you report an issue to Mapbox.
`features`	array of objects	The returned feature objects. See the table below for details on the properties contained by each feature object.

Each feature in the response body contains the following properties:

Property	Type	Description
`bbox`	array	A bounding box in the format `minimum longitude`,`minimum latitude`,`maximum longitude`,`maximum latitude`. Not available during the public beta phase.
`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"`.
`type`	string	This will always be `"Feature"`.
`properties`	object	Specific properties associated with the returned feature.
`properties.maki`	string	A string representing an associated Maki icon to use for this result.
`properties.metadata`	object	Japanese address metadata fields.
`properties.metadata.iso_3166_1`	string	The country code.
`properties.metadata.iso_3166_2`	string	The country code and its country subdivision code.
`properties.address`	string	For results with an address, the locally formatted address.
`properties.feature_name`	string	The name of the feature.
`properties.matching_name`	string	The feature name, as matched by the search algorithm.
`properties.place_type`	array	The result type. See the Administrative unit types section for details about these place types.
`properties.language`	string	The IETF language tag.
`properties.internal_id`	string	ID for internal metadata. This ID is not guaranteed to be stable or unique, and is not useful for development.
`properties.external_ids`	object	IDs passed through from external data providers. These IDs are not guaranteed to be stable or unique, and are not useful for development.
`properties.address_number`	string	The house number for address objects.
`properties.context`	array of objects	The context of the feature.
`properties.context.localized_layer`	string	The Japanese `place_type`. See the Administrative unit types section for details about these place types.
`properties.context.layer`	string	The global `place_type` that corresponds to the Japanese `properties.place_type` in `context.localized_layer`. See the Administrative unit types section for details about these place types.
`properties.context.name`	string	The name of the feature.

Example response: Reverse geocoding

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "coordinates": [
        139.58041388935513,
        35.29559166696336
      ],
      "type": "Point"
    },
    "properties": {
      "feature_name": "逗子5丁目2番",
      "matching_name": "逗子5丁目2番",
      "description": "日本, 神奈川県逗子市逗子5丁目2番16",
      "place_name": "日本, 神奈川県逗子市逗子5丁目2番16",
      "id": "address.141324126",
      "place_type": [
        "address"
      ],
      "context": [{
          "layer": "postcode.15947689941269040",
          "localized_layer": "postcode.15947689941269040",
          "name": "249-0006"
        },
        {
          "layer": "place.9212495244633840",
          "localized_layer": "place.9212495244633840",
          "name": "逗子市"
        },
        {
          "layer": "region.3991212366959510",
          "localized_layer": "region.3991212366959510",
          "name": "神奈川県"
        },
        {
          "layer": "country.9827633378530190",
          "localized_layer": "country.9827633378530190",
          "name": "日本"
        }
      ],
      "language": "ja",
      "maki": "marker",
      "internal_id": "example internal id",
      "external_ids": {
        "carmen": "address.141324126",
        "federated": "carmen.address.141324126"
      },
      "accuracy": "point",
      "address_number": "16",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-14"
      },
      "routable_points": []
    }
  }],
  "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": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "29135029-2b4d-477e-bc30-67303b12ddad"
}

Search API errors

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.
`Not found`	`404`	No `search_text` was provided in the query.

Search API restrictions and limits

The default rate limit for the Mapbox Search API is 600 requests per minute. If you require a higher rate limit, contact Mapbox Sales.
Calls to the Search 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 API is billed in the Session-based pricing section of this documentation.

Search API pricing

Usage of the Search API is billed either by search session or by API call, depending on the Search API endpoints that you use. During the beta phase's limited release in Japan, details about the number of requests included in the free tier and the cost per request beyond what is included in the free tier are available on the Japanese-language pricing page.

Session-based pricing

The Search 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.

For more specific details on session pricing, contact Mapbox sales.

Per-call pricing

Calls to the Search API's /forward, /permanent/forward, /reverse, and /permanent/reverse endpoints are billed by API calls. For more details on how calls to these endpoints are billed, see the Japanese-language pricing page.