Search
Documentation for the Search API is also available in Japanese.
Public beta for the Search API
The Mapbox Search API is in private beta for worldwide coverage and in public beta for Japan.Unless you are part of the private beta program, the Mapbox Search API is only available for Japanese-language queries for locations in Japan.
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.
PLAYGROUND
Japan Search API playground
Try Japan Search API queries and see the results on a map of Japan.
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. After the /retrieve action occurs, 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. Note that /search/v1 allows localized place names as an alternative to the standard administrative unit. In the beta release, this feature has only been enabled for Japan.
| Administrative unit type | Description | Localized option |
|---|---|---|
country | Generally recognized countries or, in some cases like Hong Kong, an area of quasi-national administrative status with 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 |
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 |
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 |
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 |
block | The block number. Only available in Japan. | |
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. | |
poi | Points of interest. These include restaurants, stores, concert venues, parks, museums, etc. If you wish to receive POI in your results, contact Mapbox sales to be added to the beta program. | |
category | A meta-result, indicating a group of POI results. For example coffee, restaurants, or fuel. Only available in /suggest results. If you wish to receive POI in your results, contact Mapbox sales to be added to the beta program. |
Session Phase 1: Request suggestions
get
https://api.mapbox.com/search/v1/suggest/{search_text}
Request a suggestion. The suggest 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 in public beta
Point of interest (POI) Search is only available to customers in private beta mode. This includes named buildings, local stores, and areas of interest such as public parks.
| 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. |
country | string | An ISO 3166 alpha 2 country code. |
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 for address or POI. When types=category this limit may be up to 100. The initial suggestion will return up to 10 results, but up to 100 POI will be included in the corresponding retrieve. |
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, address, 'poi, and category. See the Administrative unit types section for details about these types. POI and types are only available for beta customers, but in the future these may also be included by default. |
Category suggestion requires at least one of bbox, origin or proximity to be specified.
Example requests: Request a suggestion
# Search for Empire State Building with limit=1
$ curl "https://api.mapbox.com/search/v1/suggest/Empire%20State%20Building?language=en&limit=1&session_token=[GENERATED-UUID]&proximity=-75.38661,39.82049&country=US&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
# 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: Request 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 name as matched by the search algorithm. Note that this may include alternative names, synonyms, or location details besides the official feature name. |
highlighted_name | string | The name, as matched by the search algorithm wrapped in tags. While this field will be populated in all geographies, the matching tags are only populated for Japanese POI. |
description | string | Formatted context hierarchy for the given location. For US addresses, this includes City, State Abbreviation Postcode. For POI, this is the fully-formatted address. Meta results (for example category) will include the kind of meta result. |
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. Only POI results may be multi-retrieved for map display. |
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 localized 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 localized 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 | Address metadata fields. |
metadata.iso_3166_1 | string | The country code. |
metadata.iso_3166_2 | string | The country code and its country subdivision code. |
internal_id | string | An ephemeral ID; not recommended for production use. |
external_ids | string | A collection of vendor-provided IDs. Not recommended for production. |
Example responses: Request a suggestion
{
"suggestions": [
{
"feature_name": "Empire State Building",
"matching_name": "Empire State Building",
"highlighted_name": "Empire State Building",
"description": "20 West 34th Street, New York City, New York 10118, United States of America",
"result_type": ["poi"],
"language": "en",
"action": {
"endpoint": "retrieve",
"method": "POST",
"body": {
"id": "abc123"
},
"multi_retrievable": true
},
"coordinates": "-73.985703,40.748402",
"maki": "marker",
"category": [
"historic site",
"tourist attraction",
"monument",
"viewpoint"
],
"internal_id": "example internal id",
"external_ids": {
"mbx_poi": "0ad30d457a8755215c6de72a9f90e2320bb911283a32358b70b1b80ce51da099",
"foursquare": "43695300f964a5208c291fe3",
"federated": "poi.0ad30d457a8755215c6de72a9f90e2320bb911283a32358b70b1b80ce51da099",
"tripadvisor": "104365"
},
"mapbox_id": "CkIKQDBhZDMwZDQ1N2E4NzU1MjE1YzZkZTcyYTlmOTBlMjMyMGJiOTExMjgzYTMyMzU4YjcwYjFiODBjZTUxZGEwOTk=",
"context": [
{
"layer": "address",
"localized_layer": "address",
"name": "20 West 34th Street, New York City, NY 10001"
},
{
"layer": "street",
"localized_layer": "street",
"name": "west 34th street"
},
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "10118"
},
{
"layer": "neighborhood",
"localized_layer": "neighborhood",
"name": "Koreatown"
},
{
"layer": "place",
"localized_layer": "place",
"name": "New York City"
},
{
"layer": "region",
"localized_layer": "region",
"name": "New York"
},
{
"layer": "country",
"localized_layer": "country",
"name": "United States of America"
}
],
"metadata": {
"iso_3166_1": "US",
"iso_3166_2": "US-NY"
}
}
],
"attribution": "© 2022 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": "4:36ab3a1922e482256ec7ebc7069bb94f805bf5ca",
"response_uuid": "958dc02c-fb82-4b6c-9732-4d307fb66521"
}
{
"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": "© 2022 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"
}
{
"suggestions": [
{
"feature_name": "Coffee",
"matching_name": "Coffee",
"highlighted_name": "Coffee",
"description": "Category",
"result_type": [
"category"
],
"language": "en",
"action": {
"endpoint": "retrieve",
"method": "POST",
"body": {
"id": "KpVh_NjD8JvR8gjOV7tdqqycNzrC55xjG3BB7kNILsu3rmturQHGDUEMcGlaQY6Cu5cCcnz8RMVRo0lUnVnfC1CUdqgeSqTkreNyVjIR3hzFb7L62ZasnYQgFvbCi6guXA1Ai1NVyRYPDzLjy-JhOz2YHiwv8Wyk9Fi6q-od7XxXliDzmxAZ0zo7YgRgNKA-zTSo3__i3ogdrYW0uz1sKY4wMTw_0KKcuZ0WQhaNUh9Y3ZrAhaAkj6MvtDj6ArrxRsLm-jzC29pqRz3c5mg3LcODCTyqFU8D0-4zKD-1hTIQIgYkQHo_x_-BQO8J9skJTm67Io0UDUqixmxX1w7VhyqCEw8ezx8d3Rp3-ourQT6ZCmzTaDC11DrGnc4ZQ0ayR4AcrwbdKV0YnTKYh0KdMa2kxLjxcq5OP6mkep1jHlamJTAd7Qka5p5gw4pvkBf5kcT2c7Zkk6HDdJDDqVruSbElBRRyLYhynYvoFGYrDGGjAQELlK7xLnMBETewCEDpUmshnjEXeI-gwK9ZtBm05cYiMi8BEYiYuUrGVu-VRcUqBoh8-rbBNoYxnHgGZnmIeDVX6iRAqqLECuKW1lzIdYFCtEYUc1HtNT8ZftaL96-CtpNHv9mf0STW68J5e3dU_WP_VVIx4lLBZeflVAb2ICVL99zjskbrXO9CYTBx9WOWtc0fvIu1GSIxltpIu3HXlumayk2Y7PEAw1tvExzfdvYqHNboFCLRe4XvP196fcup7_3mZ6ndGECkq0SdAfhiUIScWNSOu3FDM-R7Cpk4KKT2nxibzmwDuzEzwqeam49S2FhU7p3miMAQGcmhhgqwbhDJ6hqO2m3WGtFCtXvdZXX15yoT7hme29UXrIHOFGq9Qs0ZHo9tcnfUHQnET80Hi6otebeFDpp6S6B9qgY442FtX0gzZCM0VuCo4u-SZRgy86YwKjGmgqs1nqrta46hhpajdnXb5AGBiemHmx6URWC__QKflpt4BxiIyRgzkJMLYDhnktczNJakugWQThwrUm1NrmBogTPJFlTl"
},
"multi_retrievable": false
},
"maki": "cafe",
"category": [
"Coffee"
],
"internal_id": "42CAgOTEktT0_KJKAA==.42eAgMSCTN2C_Ezd4tSisszkVAA=.Y2OAgOT8tLTUVAA=",
"external_ids": {
"federated": "category.coffee"
}
}
],
"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": "5:541dd5c3358c4070719c266470cfb8430d72dd24",
"response_uuid": "da631e7b-75fd-4dc3-9a1e-4915b2c16a29"
}
Session Phase 2: Retrieve a suggested feature
post
https://api.mapbox.com/search/v1/retrieve/
After one or more calls to the /suggest endpoint, you will use the information contained in the response's action block to retrieve detailed information about the feature, including coordinates. 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.
While a retrieve for a place or address will return details for a single result, a retrieve on a category result will return up to limit POI belonging to that category.
POI now available in public beta
Point of interest (POI) Search is now available to customers in private beta mode. This includes named buildings, local stores, and areas of interest such as public parks.
| 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 details for a suggestion
The /retrieve endpoint returns a GeoJSON FeatureCollection. In the case of a category selection, /retrieve will return an array of GeoJSON features.
| 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. Only available for places layers. |
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 | 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.feature_name | string | The name of the feature. |
properties.matching_name | string | The name as matched by the search algorithm. Note that this may include alternative names, synonyms, or location details besides the official feature name. |
highlighted_name | string | The name, as matched by the search algorithm wrapped in tags. While this field will be populated in all geographies, the matching tags are only populated for Japanese POI. |
properties.place_name | string | A string representing the feature in the requested language, if specified, and its full result hierarchy. |
properties.description | string | For POI, the locally formatted address. For place_types, the fully formatted context hierarchy above the given level. |
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 localized 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 localized 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 responses: Retrieve a suggested feature
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [5.049746, 51.650652],
"type": "Point"
},
"properties": {
"feature_name": "Efteling",
"matching_name": "Efteling",
"highlighted_name": "Efteling",
"description": "Europalaan 1, 5171 RP Kaatsheuvel, Netherlands",
"place_name": "Efteling, Europalaan 1, 5171 RP Kaatsheuvel, Netherlands",
"id": "2xAyKYEBLMhwlZV-L0T3",
"place_type": ["poi"],
"context": [
{
"layer": "address",
"localized_layer": "address",
"name": "Europalaan 1, 5171 KW Kaatsheuvel The Netherlands"
},
{
"layer": "street",
"localized_layer": "street",
"name": "europalaan"
},
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "5171 RP"
},
{
"layer": "neighborhood",
"localized_layer": "neighborhood",
"name": "De Klinkenpolder"
},
{
"layer": "place",
"localized_layer": "place",
"name": "Kaatsheuvel"
},
{
"layer": "country",
"localized_layer": "country",
"name": "Netherlands"
}
],
"maki": "marker",
"poi_category": ["theme park", "entertainment"],
"internal_id": "example internal id",
"external_ids": {
"tripadvisor": "262610",
"foursquare": "4a72b543f964a52041db1fe3",
"federated": "poi.067e4e1ea55235c67f4601f56d2889ebf6c380220de994e902f33ab59dd988e1",
"mbx_poi": "067e4e1ea55235c67f4601f56d2889ebf6c380220de994e902f33ab59dd988e1"
},
"mapbox_id": "CkIKQDA2N2U0ZTFlYTU1MjM1YzY3ZjQ2MDFmNTZkMjg4OWViZjZjMzgwMjIwZGU5OTRlOTAyZjMzYWI1OWRkOTg4ZTE=",
"metadata": {
"review_count": 7787,
"phone": "+31 416 537 777",
"website": "http://www.efteling.com/",
"average_rating": 4.5,
"detailed_description": "Discover Holland's hidden gem. Efteling is a unique theme park with a fairytale atmosphere, natural surroundings and a wide range of thrilling and enchanting attractions, making it the ideal family short-break destination!",
"primary_photo": [
{
"width": 50,
"height": 50,
"url": "https://media-cdn.tripadvisor.com/media/photo-t/12/5b/6f/3c/efteling-the-magic-land.jpg"
},
{
"width": 150,
"height": 150,
"url": "https://media-cdn.tripadvisor.com/media/photo-l/12/5b/6f/3c/efteling-the-magic-land.jpg"
},
{
"width": 250,
"height": 188,
"url": "https://media-cdn.tripadvisor.com/media/photo-f/12/5b/6f/3c/efteling-the-magic-land.jpg"
},
{
"width": 550,
"height": 413,
"url": "https://media-cdn.tripadvisor.com/media/photo-s/12/5b/6f/3c/efteling-the-magic-land.jpg"
},
{
"width": 960,
"height": 720,
"url": "https://media-cdn.tripadvisor.com/media/photo-o/12/5b/6f/3c/efteling-the-magic-land.jpg"
}
],
"open_hours": {
"open_type": "Scheduled",
"open_periods": [
{
"open": {
"day": 0,
"time": {
"hour": 11,
"minute": 0
}
},
"close": {
"day": 0,
"time": {
"hour": 18,
"minute": 0
}
}
},
{
"open": {
"day": 1,
"time": {
"hour": 11,
"minute": 0
}
},
"close": {
"day": 1,
"time": {
"hour": 18,
"minute": 0
}
}
},
{
"open": {
"day": 2,
"time": {
"hour": 11,
"minute": 0
}
},
"close": {
"day": 2,
"time": {
"hour": 18,
"minute": 0
}
}
},
{
"open": {
"day": 3,
"time": {
"hour": 11,
"minute": 0
}
},
"close": {
"day": 3,
"time": {
"hour": 18,
"minute": 0
}
}
},
{
"open": {
"day": 4,
"time": {
"hour": 11,
"minute": 0
}
},
"close": {
"day": 4,
"time": {
"hour": 18,
"minute": 0
}
}
},
{
"open": {
"day": 5,
"time": {
"hour": 10,
"minute": 0
}
},
"close": {
"day": 5,
"time": {
"hour": 18,
"minute": 0
}
}
},
{
"open": {
"day": 6,
"time": {
"hour": 10,
"minute": 0
}
},
"close": {
"day": 6,
"time": {
"hour": 18,
"minute": 0
}
}
}
]
},
"iso_3166_1": "NL",
"iso_3166_2": "NL-NB"
}
}
}
],
"attribution": "© 2022 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": "4:36ab3a1922e482256ec7ebc7069bb94f805bf5ca",
"response_uuid": "fcdd5da0-2bb2-48ac-bf73-8da68fffc5ac"
}
{
"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": "© 2022 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"
}
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [-6.6543203, 55.204344],
"type": "Point"
},
"properties": {
"feature_name": "Koko",
"matching_name": "Koko",
"highlighted_name": "Koko",
"description": "10 Castle Erin Road, Portrush, None, United Kingdom",
"place_name": "Koko, 10 Castle Erin Road, Portrush, None, United Kingdom",
"id": "zAK63YEBNHearXczfx0E",
"place_type": ["poi"],
"context": [
{
"layer": "address",
"localized_layer": "address",
"name": "10 Castle Erin Road, Portrush BT56 8DH, United Kingdom"
},
{
"layer": "street",
"localized_layer": "street",
"name": "Castle Erin Road"
},
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "None"
},
{
"layer": "neighborhood",
"localized_layer": "neighborhood",
"name": "None"
},
{
"layer": "place",
"localized_layer": "place",
"name": "Portrush"
},
{
"layer": "country",
"localized_layer": "country",
"name": "United Kingdom"
}
],
"maki": "restaurant",
"poi_category": [
"food",
"food and drink",
"coffee shop",
"coffee",
"cafe"
],
"internal_id": "Y2aAgIL8TAA=.42eAgMSCTN2C_Ezd4tSisszkVAA=.U2aAgLT80qLiwtLEolQ9U-NUy7QkAwsTS4vUNPNUC8tkI5OkZEMzAA==",
"external_ids": {
"mbx_poi": "d290c111831b4b1bb441ca1f9c03775e7e0d787f69c670fdf66d5b036445f5a1",
"federated": "poi.d290c111831b4b1bb441ca1f9c03775e7e0d787f69c670fdf66d5b036445f5a1",
"foursquare": "53e9fb08498ef7e89c24bc16"
},
"mapbox_id": "CkIKQGQyOTBjMTExODMxYjRiMWJiNDQxY2ExZjljMDM3NzVlN2UwZDc4N2Y2OWM2NzBmZGY2NmQ1YjAzNjQ0NWY1YTE=",
"metadata": {
"primary_photo": [],
"iso_3166_1": "GB",
"iso_3166_2": "GB-NIR"
}
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [-2.751394, 52.708212],
"type": "Point"
},
"properties": {
"feature_name": "Aroma Tea & Coffee Merchants",
"matching_name": "Aroma Tea & Coffee Merchants",
"highlighted_name": "Aroma Tea & Coffee Merchants",
"description": "8a St Marys Pl, Shrewsbury, SY1 1DZ, United Kingdom",
"place_name": "Aroma Tea & Coffee Merchants, 8a St Marys Pl, Shrewsbury, SY1 1DZ, United Kingdom",
"id": "oOgD3YEBNHearXczYB58",
"place_type": ["poi"],
"context": [
{
"layer": "address",
"localized_layer": "address",
"name": "8a St Marys Pl"
},
{
"layer": "street",
"localized_layer": "street",
"name": "st marys pl"
},
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "SY1 1DZ"
},
{
"layer": "place",
"localized_layer": "place",
"name": "Shrewsbury"
},
{
"layer": "country",
"localized_layer": "country",
"name": "United Kingdom"
}
],
"maki": "cafe",
"poi_category": ["coffee roaster", "coffee", "food and drink"],
"internal_id": "Y2aAgIL8TAA=.42eAgMSCTN2C_Ezd4tSisszkVAA=.U2aAgLT80qLiwtLEolQ9MwMTIxNTg1QT8yQL4zSzREPLtJQkkyQDAA==",
"external_ids": {
"federated": "poi.a0d64973784b740fae2b89645e5e36ac818d46a3a58974057bfea54b58d0ff33",
"foursquare": "6042450e47b83f6a19fdb4b0",
"mbx_poi": "a0d64973784b740fae2b89645e5e36ac818d46a3a58974057bfea54b58d0ff33"
},
"mapbox_id": "CkIKQGEwZDY0OTczNzg0Yjc0MGZhZTJiODk2NDVlNWUzNmFjODE4ZDQ2YTNhNTg5NzQwNTdiZmVhNTRiNThkMGZmMzM=",
"metadata": {
"primary_photo": [],
"iso_3166_1": "GB",
"iso_3166_2": "GB-ENG"
}
}
}
],
"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": "5:541dd5c3358c4070719c266470cfb8430d72dd24",
"response_uuid": "26d4c339-91cc-474b-b417-48056ab38220"
}
Forward geocoding
get
https://api.mapbox.com/search/v1/forward/{search_text}
Retrieve detailed information about a specific feature, including geographic coordinates, in response to a user query.
POI search now available in public beta
Point of interest (POI) Search is only available to customers in private beta mode. This includes named buildings, local stores, and areas of interest such as public parks.
| 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. |
country | string | An ISO 3166 alpha 2 country code. |
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, address and poi. See the Administrative unit types section for details about these types. Note that meta types such as category are only supported in session requests. POI are only available for beta customers, but in the future these may also be included by default. |
Example requests: Forward geocoding
$ curl "https://api.mapbox.com/search/v1/forward/34170%20Gannon%20Terrace?language=en&limit=1&proximity=-121.90662,37.42827&country=US&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
$ 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
https://api.mapbox.com/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 for place or address types, contact Mapbox sales. POI will not be included in permanent geocoding results. This is consistent with the Terms of Service for Mapbox Geocoding API calls 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.
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.
| 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 | 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.description | string | For POI, the locally formatted address. For place_types, the fully formatted context hierarchy above the given level. |
properties.address_number | string | The house number for address objects. |
properties.feature_name | string | The name of the feature. |
properties.matching_name | string | The name as matched by the search algorithm. Note that this may include alternative names, synonyms, or location details besides the official feature name. |
highlighted_name | string | The name, as matched by the search algorithm wrapped in tags. While this field will be populated in all geographies, the matching tags are only populated for Japanese POI. |
properties.place_name | string | A string representing the feature in the requested language, if specified, and its full result hierarchy. |
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 localized 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 localized 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 responses: Forward geocoding
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [-122.05963, 37.56153],
"type": "Point"
},
"properties": {
"feature_name": "34170 Gannon Terrace",
"matching_name": "34170 Gannon Terrace",
"highlighted_name": "34170 Gannon Terrace",
"description": "Fremont, California 94555, United States",
"place_name": "34170 Gannon Terrace, Fremont, California 94555, United States",
"id": "address.1556645983160292",
"place_type": ["address"],
"context": [
{
"layer": "neighborhood.7327715941516860",
"localized_layer": "neighborhood.7327715941516860",
"name": "Ardenwood"
},
{
"layer": "postcode.11243426117484610",
"localized_layer": "postcode.11243426117484610",
"name": "94555"
},
{
"layer": "place.11532961120628200",
"localized_layer": "place.11532961120628200",
"name": "Fremont"
},
{
"layer": "district.11187960009291250",
"localized_layer": "district.11187960009291250",
"name": "Alameda County"
},
{
"layer": "region.9803118085738010",
"localized_layer": "region.9803118085738010",
"name": "California"
},
{
"layer": "country.14135384517372290",
"localized_layer": "country.14135384517372290",
"name": "United States"
}
],
"language": "en",
"maki": "marker",
"internal_id": "example internal id",
"external_ids": {
"federated": "carmen.address.1556645983160292",
"carmen": "address.1556645983160292"
},
"accuracy": "rooftop",
"address_number": "34170",
"metadata": {
"iso_3166_1": "us",
"iso_3166_2": "US-CA"
},
"routable_points": [
{
"name": "Address",
"coordinates": [-122.059679, 37.561366]
}
]
}
}
],
"attribution": "© 2022 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": "4:36ab3a1922e482256ec7ebc7069bb94f805bf5ca",
"response_uuid": "b32870f4-fa52-48f5-98c4-2200bb13ce7c"
}
{
"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": "© 2022 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
https://api.mapbox.com/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. |
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, address, and poi. See the Administrative unit types section for details about these types. POI are only available for beta customers, but in the future these may also be included by default. |
Example requests: Reverse geocoding
$ curl "https://api.mapbox.com/search/v1/reverse/13.329048,52.51258?language=de&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
$ curl "https://api.mapbox.com/search/v1/reverse/139.58028,35.29556?language=ja&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Permanent reverse geocoding
get
https://api.mapbox.com/search/v1/permanent/reverse/{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 for address or place types, contact Mapbox sales. POI will not be included in permanent geocoding results. This is consistent with the Terms of Service for Mapbox Geocoding API calls to the mapbox.places-permanent endpoint.
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.
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.
| 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 | 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.feature_name | string | The name of the feature. |
properties.matching_name | string | The name as matched by the search algorithm. Note that this may include alternative names, synonyms, or location details besides the official feature name. |
highlighted_name | string | The name, as matched by the search algorithm wrapped in tags. While this field will be populated in all geographies, the matching tags are only populated for Japanese POI. |
properties.place_name | string | A string representing the feature in the requested language, if specified, and its full result hierarchy. |
properties.place_type | array | The result type. See the Administrative unit types section for details about these place types. |
properties.description | string | For POI, the locally formatted address. For place_types, the fully formatted context hierarchy above the given level. |
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 localized 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 localized 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 responses: Reverse geocoding
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [13.3295589, 52.5125463],
"type": "Point"
},
"properties": {
"feature_name": "Straße Des 17. Juni 115",
"matching_name": "Straße Des 17. Juni 115",
"highlighted_name": "Straße Des 17. Juni 115",
"description": "10623 Berlin, Deutschland",
"place_name": "Straße Des 17. Juni 115, 10623 Berlin, Deutschland",
"id": "address.3419053976491624",
"place_type": ["address"],
"context": [
{
"layer": "postcode.5398366936640250",
"localized_layer": "postcode.5398366936640250",
"name": "10623"
},
{
"layer": "locality.12210531181979940",
"localized_layer": "locality.12210531181979940",
"name": "Charlottenburg"
},
{
"layer": "place.14094307404564380",
"localized_layer": "place.14094307404564380",
"name": "Berlin"
},
{
"layer": "country.10814856728480410",
"localized_layer": "country.10814856728480410",
"name": "Deutschland"
}
],
"language": "de",
"maki": "marker",
"internal_id": "example internal id",
"external_ids": {
"federated": "carmen.address.3419053976491624",
"carmen": "address.3419053976491624"
},
"accuracy": "rooftop",
"address_number": "115",
"metadata": {
"iso_3166_1": "de"
},
"routable_points": [
{
"name": "Address",
"coordinates": [13.32955240836938, 52.51264818693428]
}
]
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [13.329777, 52.512344],
"type": "Point"
},
"properties": {
"feature_name": "Chemiegebäude C TU Berlin",
"matching_name": "Chemiegebäude C TU Berlin",
"highlighted_name": "Chemiegebäude C TU Berlin",
"description": "Straße des 17. Juni 115, 10623 Berlin, Deutschland",
"place_name": "Chemiegebäude C TU Berlin, Straße des 17. Juni 115, 10623 Berlin, Deutschland",
"id": "ZHtfKIEBLMhwlZV-fxwF",
"place_type": ["poi"],
"context": [
{
"layer": "address",
"localized_layer": "address",
"name": "Straße des 17. Juni 115"
},
{
"layer": "street",
"localized_layer": "street",
"name": "straße des 17 juni"
},
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "10623"
},
{
"layer": "neighborhood",
"localized_layer": "neighborhood",
"name": "Berlin-10623"
},
{
"layer": "place",
"localized_layer": "place",
"name": "Berlin"
},
{
"layer": "country",
"localized_layer": "country",
"name": "Deutschland"
}
],
"maki": "marker",
"poi_category": ["universitätsgebäude"],
"internal_id": "example internal id",
"external_ids": {
"federated": "poi.cf57c7f9cb1ef13109b9110018d46716dcfc8b1dc835f541e1aece69f283a8f7",
"foursquare": "4d3569c6329e54812c70ca1d",
"mbx_poi": "cf57c7f9cb1ef13109b9110018d46716dcfc8b1dc835f541e1aece69f283a8f7"
},
"mapbox_id": "CkIKQGNmNTdjN2Y5Y2IxZWYxMzEwOWI5MTEwMDE4ZDQ2NzE2ZGNmYzhiMWRjODM1ZjU0MWUxYWVjZTY5ZjI4M2E4Zjc=",
"metadata": {
"primary_photo": [],
"iso_3166_1": "DE",
"iso_3166_2": "DE-BE"
}
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [13.3297794, 52.5129985],
"type": "Point"
},
"properties": {
"feature_name": "RWE-Effizienz",
"matching_name": "RWE-Effizienz",
"highlighted_name": "RWE-Effizienz",
"description": "10623, Deutschland",
"place_name": "RWE-Effizienz, 10623, Deutschland",
"id": "3-aBKIEBLMhwlZV-ZzLV",
"place_type": ["poi"],
"context": [
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "10623"
},
{
"layer": "country",
"localized_layer": "country",
"name": "Deutschland"
}
],
"maki": "marker",
"poi_category": ["ladestation", "transport"],
"internal_id": "example internal id",
"external_ids": {
"mbx_poi": "bac9da3a9611cfaf6690c583e67b9d6f0534ff1189171ba4a57e5278284f6f86",
"osm": "n1272542311",
"federated": "poi.bac9da3a9611cfaf6690c583e67b9d6f0534ff1189171ba4a57e5278284f6f86"
},
"mapbox_id": "CkIKQGJhYzlkYTNhOTYxMWNmYWY2NjkwYzU4M2U2N2I5ZDZmMDUzNGZmMTE4OTE3MWJhNGE1N2U1Mjc4Mjg0ZjZmODY=",
"metadata": {
"primary_photo": [],
"iso_3166_1": "DE",
"iso_3166_2": "DE-BE"
}
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [13.329943, 52.512203],
"type": "Point"
},
"properties": {
"feature_name": "INI Chemie TU Berlin",
"matching_name": "INI Chemie TU Berlin",
"highlighted_name": "INI Chemie TU Berlin",
"description": "Straße des 17. Juni 115, 10623 Berlin, Deutschland",
"place_name": "INI Chemie TU Berlin, Straße des 17. Juni 115, 10623 Berlin, Deutschland",
"id": "z_QpKYEBLMhwlZV-Lx1H",
"place_type": ["poi"],
"context": [
{
"layer": "address",
"localized_layer": "address",
"name": "Straße des 17. Juni 115"
},
{
"layer": "street",
"localized_layer": "street",
"name": "straße des 17 juni"
},
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "10623"
},
{
"layer": "neighborhood",
"localized_layer": "neighborhood",
"name": "Berlin-10623"
},
{
"layer": "place",
"localized_layer": "place",
"name": "Berlin"
},
{
"layer": "country",
"localized_layer": "country",
"name": "Deutschland"
}
],
"maki": "marker",
"poi_category": ["universitätsgebäude"],
"internal_id": "example internal id",
"external_ids": {
"foursquare": "5166e725e4b0532deebdf0b6",
"federated": "poi.eafb7426dd4209ee679236576265a9b2a1374aa784f2fb8e690f680abbad6a70",
"mbx_poi": "eafb7426dd4209ee679236576265a9b2a1374aa784f2fb8e690f680abbad6a70"
},
"mapbox_id": "CkIKQGVhZmI3NDI2ZGQ0MjA5ZWU2NzkyMzY1NzYyNjVhOWIyYTEzNzRhYTc4NGYyZmI4ZTY5MGY2ODBhYmJhZDZhNzA=",
"metadata": {
"primary_photo": [],
"iso_3166_1": "DE",
"iso_3166_2": "DE-BE"
}
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [13.327865, 52.512276],
"type": "Point"
},
"properties": {
"feature_name": "Fachbereich Logistik",
"matching_name": "Fachbereich Logistik",
"highlighted_name": "Fachbereich Logistik",
"description": "Straße des 17. Juni 135, 10623 Berlin, Deutschland",
"place_name": "Fachbereich Logistik, Straße des 17. Juni 135, 10623 Berlin, Deutschland",
"id": "pQnqJ4EBLMhwlZV-Ik2S",
"place_type": ["poi"],
"context": [
{
"layer": "address",
"localized_layer": "address",
"name": "Straße des 17. Juni 135"
},
{
"layer": "street",
"localized_layer": "street",
"name": "straße des 17 juni"
},
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "10623"
},
{
"layer": "neighborhood",
"localized_layer": "neighborhood",
"name": "Berlin-10623"
},
{
"layer": "place",
"localized_layer": "place",
"name": "Berlin"
},
{
"layer": "country",
"localized_layer": "country",
"name": "Deutschland"
}
],
"maki": "marker",
"poi_category": ["büro"],
"internal_id": "example internal id",
"external_ids": {
"foursquare": "5475a534498e3f576fa1b5d9",
"federated": "poi.0918e824a5229b4682881bb3383d8f192a059709db2c2659e5b93fa89f50f455",
"mbx_poi": "0918e824a5229b4682881bb3383d8f192a059709db2c2659e5b93fa89f50f455"
},
"mapbox_id": "CkIKQDA5MThlODI0YTUyMjliNDY4Mjg4MWJiMzM4M2Q4ZjE5MmEwNTk3MDlkYjJjMjY1OWU1YjkzZmE4OWY1MGY0NTU=",
"metadata": {
"primary_photo": [],
"iso_3166_1": "DE",
"iso_3166_2": "DE-BE"
}
}
}
],
"attribution": "© 2022 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": "4:36ab3a1922e482256ec7ebc7069bb94f805bf5ca",
"response_uuid": "f728ec84-5599-4ac5-aee3-dda48d970e74"
}
{
"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": "© 2022 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"
}
Category Hot Button
get
https://api.mapbox.com/search/v1/category/{category_id}
Retrieve detailed information about a specific feature, including geographic coordinates, in response to a user query.
POI search now available in public beta
Point of interest (POI) Search is only available to customers in private beta mode. This includes named buildings, local stores, and areas of interest such as public parks.
| Required parameters | Type | Description |
|---|---|---|
access_token | string | A Mapbox access token with default permissions. |
canonical_id | string | The canonical ID of a Mapbox category. These may be obtained from a /suggest or /list/category call. Category names are guaranteed stable for 30 days. It is recommended that users refresh canonical IDs on a periodic basis. |
language | string | The ISO language code to be returned. |
country | string | An ISO 3166 alpha 2 country code. |
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. Note that meta types such as category are only supported in session requests. |
Example requests: Category Hot Button Search
$ curl "https://api.mapbox.com/search/v1/category/coffee?language=en&limit=5&proximity=-78.476678,38.029306&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Response: Category Hot Button search
The response to a request to the /category/{category_id} endpoint is a GeoJSON FeatureCollection.
Using the limit parameter, you can increase the maximum number of results up to 100. 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.
| 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 |
|---|---|---|
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 | 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.description | string | For POI, the locally formatted address. For place_types, the fully formatted context hierarchy above the given level. |
properties.address_number | string | The house number for address objects. |
properties.feature_name | string | The name of the feature. |
properties.matching_name | string | Duplicate of properties.feature_name. |
highlighted_name | string | Duplicate of properties.feature_name. |
properties.place_name | string | A string representing the feature in the requested language, if specified, and its full result hierarchy. |
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 localized 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 localized 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 responses: Category Hot Button
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [-78.478664, 38.030008],
"type": "Point"
},
"properties": {
"feature_name": "Java Java Cafe",
"matching_name": "Java Java Cafe",
"highlighted_name": "Java Java Cafe",
"description": "421 E Main St, Virginia 22902, United States of America",
"place_name": "Java Java Cafe, 421 E Main St, Virginia 22902, United States of America",
"id": "s7_YsYEBLMhwlZV-mB3E",
"place_type": ["poi"],
"context": [
{
"layer": "address",
"localized_layer": "address",
"name": "421 E Main St"
},
{
"layer": "street",
"localized_layer": "street",
"name": "e main st"
},
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "22902"
},
{
"layer": "neighborhood",
"localized_layer": "neighborhood",
"name": "North Downtown"
},
{
"layer": "region",
"localized_layer": "region",
"name": "Virginia"
},
{
"layer": "country",
"localized_layer": "country",
"name": "United States of America"
}
],
"maki": "restaurant",
"poi_category": [
"food",
"food and drink",
"coffee shop",
"coffee",
"cafe"
],
"internal_id": "Y2aAgIL8TAA=.42eAgMSCTN2C_Ezd4tSisszkVAA=.U2aAgLT80qLiwtLEolQ9kyRzc0MTS7M0SzOTRFMjA1ND8ySj1FRjAA==",
"external_ids": {
"federated": "poi.52dc76305c4b719dd2470a6ed92829eecd98ee4d990d2cc5cc486fc13959095b",
"safegraph": "233-222@63g-bf8-x5z",
"mbx_poi": "52dc76305c4b719dd2470a6ed92829eecd98ee4d990d2cc5cc486fc13959095b",
"foursquare": "4b771496f964a520517b2ee3"
},
"mapbox_id": "CkIKQDUyZGM3NjMwNWM0YjcxOWRkMjQ3MGE2ZWQ5MjgyOWVlY2Q5OGVlNGQ5OTBkMmNjNWNjNDg2ZmMxMzk1OTA5NWI=",
"metadata": {
"primary_photo": [],
"iso_3166_1": "US",
"iso_3166_2": "US-VA"
}
}
}
],
"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": "5:541dd5c3358c4070719c266470cfb8430d72dd24",
"response_uuid": "00000000-0000-0000-0000-000000000000"
}
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [139.761493, 35.676906],
"type": "Point"
},
"properties": {
"feature_name": "Patagonia",
"matching_name": "Patagonia",
"highlighted_name": "Patagonia",
"description": "東京都千代田区丸の内３－１－１",
"place_name": "Patagonia, 東京都千代田区丸の内３－１－１",
"id": "z9fWqYEBJNOCvqh5yCj1",
"place_type": ["poi"],
"context": [
{
"layer": "address",
"localized_layer": "address",
"name": "東京都千代田区丸の内３－１－１"
},
{
"layer": "street",
"localized_layer": "street",
"name": "丸の内３-１-１"
},
{
"layer": "postcode",
"localized_layer": "postcode",
"name": "100-0005"
}
],
"maki": "shop",
"poi_category": ["ショップ>スポーツ用品", "ショップ"],
"brand": [],
"internal_id": "Y2aAgIL8TAA=.42eAgMSCTN2C_Ezd4tSisszkVAA=.U2aAgLT80qLiwtLEolQ9UyMjU_PkJDNDwxQjg0TLtLRUA0vTpNREAA==",
"external_ids": {
"foursquare": "52257cb611d20a9ffe095bea",
"mbx_poi": "55481c53b3b1d1a32563260c74e9ed3579989c092a840d4b2eeef6236d813af8",
"federated": "poi.55481c53b3b1d1a32563260c74e9ed3579989c092a840d4b2eeef6236d813af8"
},
"mapbox_id": "CkIKQDU1NDgxYzUzYjNiMWQxYTMyNTYzMjYwYzc0ZTllZDM1Nzk5ODljMDkyYTg0MGQ0YjJlZWVmNjIzNmQ4MTNhZjg=",
"metadata": {
"iso_3166_1": "JP",
"iso_3166_2": "JP-13"
}
}
}
],
"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": "17:20edfdc9a9545e04146c74ba4f0faf9cce5b8b57",
"response_uuid": "405be5a0-84e8-4b8e-93c2-318c30f74720"
}
List Categories
get
https://api.mapbox.com/search/v1/list/category
Retrieve the list of canonical category IDs for category hot button search.
| Required parameters | Type | Description |
|---|---|---|
access_token | string | A Mapbox access token with default permissions. |
language | string | The ISO language code to be returned. |
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 canonical IDs to return, up to 10000. |
industry_code | string | Specify taxonomy to retrieve. Allowed values are global and japan |
Example requests: Category List
$ curl "https://api.mapbox.com/search/v1/list/category?language=en&limit=10000&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Response: Category List
The response to a request to the /list/category/ endpoint is an array of categories..
Using the limit parameter, you can increase the maximum number of results up to 10000. 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.
| Property | Type | Description |
|---|---|---|
type | string | This will always be "listItems". |
attribution | string | The attribution data for results. |
version | string | The service version information. Include this information if you report an issue to Mapbox. |
listItems | array of objects | The returned category objects. See the table below for details on the properties contained by each feature object. |
Each category in the response body contains the following properties:
| Property | Type | Description |
|---|---|---|
canonical_id | string | The canonical ID of the item. |
icon | string | maki to use with objects of this category |
name | string | Display name for category in the requested language. |
Search API errors
Public beta for the Search API
If your account is not enabled for the global private beta and you are making requests outside Japan you will receive a 401 response with the error, that the feature is not enabled.
Response body message | HTTP error code | Description |
|---|---|---|
Not authorized | 401 | Check the access token used in the query. |
Bad request | 400 | Check 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
/suggestand/retrieveendpoints must include asession_tokenparameter. Each API call in a search session counts individually against the rate limit. For example, 10 sequential calls to/suggestwith the samesession_tokenand one call to/retrieveare 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:
- Make a call to
/suggestfollowed by a call to/retrievewith a commonsession_token. - Make 50 successive calls to
/suggestwith a commonsession_tokenbut are not followed by a call to/retrieve. - Make a call to
/suggestand 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.