Details API
The Details API provides access to POI (Points of Interest) metadata, boundary details, addresses and places. The Details API provides developers with a streamlined solution for incorporating comprehensive location data into their applications, enhancing user experience with more detailed and context-aware mapping information.
Private Preview
The Details API is in Private Preview. Data provided through the API and usage parameters are subject to change without prior notice. For more information about Details API pricing and usage limitations, reach out to the Mapbox Sales team.
The Details API is specifically designed to enrich map, search, and navigation experiences, providing access to rich location data. Depending on the feature type requested, developers can retrieve place photos, visiting and delivery information, opening hours, and locations details. Details API is seamlessly integrated with Mapbox Search products enabling location data to be used in a wide array of use cases, fulfilling the need for rich, context-specific information relevant to the map users’ content.
PLAYGROUND
Details API Developer Playground
Try Details API queries and view the response data in a sample UI.
Details API Endpoint
The Details API has a single endpoint - /retrieve - to retrieve POI metadata and Mapbox Boundary details. Depending on your use case, /retrieve endpoint can be used with GET for retrieving a single location detail or POST for retrieving multiple location details.
Get mapbox_id for a feature
mapbox_id serves as a unique identifier for a geographic feature such as POI, Address, Boundary or Place. All requests to the Details API require a mapbox_id.
To get the mapbox_id associated with a particular feature, inspect the response data returned from a search request made through the Search Box API or the Geocoding API. For Mapbox Boundaries, a mapbox_id is included for each feature in the Boundaries tileset.
Retrieve POI Details
With the Details API, developers can query specific details of a POI and retrieve metadata like photos, contact information and venue details.
Retrieve basic attributes
get
https://api.mapbox.com/search/details/v1/retrieve/{mapbox_id}
Requesting the /retrieve endpoint with a mapbox_id will return the basic metadata for a POI, which includes attributes such as POI name, address, coordinates, primary photo and category classification.
To retrieve additional attributes beyond the basic data for a POI, see Retrieve attribute sets
| Required parameters | Type | Description |
|---|---|---|
mapbox_id | string | A unique identifier for the geographic feature |
access_token | string | A Mapbox access token with default permissions. |
| Optional parameters | Type | Description |
|---|---|---|
worldview | string | The two digit ISO country code (such as 'JP') to requests a worldview for the location data, if applicable data is available. This parameters will only be applicable for Boundaries and Places feature types. |
language | string | The ISO language code to be returned. If not provided, the default is English. |
Example request: Retrieve basic attributes
# Get details for West Front Capitol Park in Washington DC, USA
# mapbox_id for this POI is dXJuOm1ieHBvaTphMDAzZDViMi0xNDdiLTRkNDItYWI2MC04NTY4Njg1Y2EyNTA
$ curl "https://api.mapbox.com/search/details/v1/retrieve/dXJuOm1ieHBvaTphMDAzZDViMi0xNDdiLTRkNDItYWI2MC04NTY4Njg1Y2EyNTA?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Response: Retrieve basic attributes
The response to a request to the /retrieve endpoint is a GeoJSON feature that includes related metadata attributes. When attribute_sets parameter is not provided, only basic attributes will be provided in the response.
A request for the basic attributes includes the following properties:
| Property | Type | Description |
|---|---|---|
geometry.coordinates | array | The geographical coordinates of the result. |
geometry.type | string | This will always be "Point". |
properties.address | string | The address of the result including the address number and street. |
properties.context | object | The context of the feature, structured in layers according to the Administrative unit types. The availability of these layers depends on the feature type and the geographic location. |
properties.context.country | object | The country of the result. This layer includes properties id, name, country_code (the ISO_3166_1 alpha 2 code), and country_code_alpha_3 (the ISO_3166_1 alpha 3 code). |
properties.context.region | object | The region of the result. This layer includes properties id, name, region_code, and region_code_full (the ISO_3166_2 code). |
properties.context.postcode | object | The postcode of the result. This layer includes properties id and name. |
properties.context.district | object | The district of the result. This layer includes properties id and name. |
properties.context.place | object | The place of the result. This layer includes properties id and name. |
properties.context.locality | object | The locality of the result. This layer includes properties id and name. |
properties.context.neighborhood | object | The neighborhood of the result. This layer includes properties id and name. |
properties.coordinates | object | The geographical coordinates of the result. |
properties.coordinates.longitude | number | The longitudinal coordinate of the result. |
properties.coordinates.latitude | number | The latitudinal coordinate of the result. |
properties.coordinates.routable_points | array | An array of objects containing information about the feature's routable points. A routable point object contains properties name, latitude, and longitude. |
properties.external_ids | object | An object containing the IDs of the feature found in external databases, with the keys being the data source names and the values being the IDs. |
properties.feature_type | string | The type of the result. For POIs, this will be poi. For categories, this will be category. For address-type results, the global context hierarchy is used (country, region, postcode, district, place, locality, neighborhood, address). See the Administrative unit types section for details about these types. |
properties.full_address | string | The full address of the result, which concatenates address and place_formatted. |
properties.language | string | An IETF language tag indicating the language of the result. This value depends on the request parameter and the availability of the requested language translation is not guaranteed for all features. |
properties.maki | string | A string representing an associated Maki icon to use for this result. |
properties.mapbox_id | string | A unique ID associated with the feature. |
properties.metadata | object | An object containing additional metadata for the feature, if applicable. |
properties.name | string | The name of the feature. |
properties.operational_status | string | The operational status for the location or associated business. The string value contains active, or closed. |
properties.place_formatted | string | A formatted string of result context comprised of the place, region, country, and postcode. It is the part of the result which comes after address. |
properties.poi_category | array | An array including the POI categories the result falls into, if it is a POI. |
properties.poi_category_ids | array | An array including the canonical POI category IDs the result falls into, if it is a POI. |
properties.metadata.wheelchair_accessible | boolean | (Optional) Indicates whether the location is accessible by wheelchair. Possible values are true or false. |
properties.metadata.primary_photo | string | (Optional) The URL for the primary photo of the location. |
properties.brand | array | (Optional) The names of the brands associated with the POI. |
properties.brand_id | array | (Optional) The unique identifier for the brands associated with the POI. |
type | string | This will always be "Feature". |
The optional properties are not provided for all features, and the availability depends on the type of feature and geography.
|
Example response: Retrieve POI metadata
{
"type": "Feature",
"geometry": {
"coordinates": [
-77.010529,
38.889838
],
"type": "Point"
},
"properties": {
"address": "Washington",
"context": {
"country": {
"country_code": "US",
"country_code_alpha_3": "USA",
"id": "",
"name": "United States"
},
"neighborhood": {
"id": "dXJuOm1ieHBsYzpHYUVzN0E",
"name": "National Mall"
},
"place": {
"id": "dXJuOm1ieHBsYzpGSmlvN0E",
"name": "Washington"
},
"postcode": {
"id": "dXJuOm1ieHBsYzpBNkR1N0E",
"name": "20024"
},
"region": {
"id": "",
"name": "District of Columbia",
"region_code": "DC",
"region_code_full": "US-DC"
}
},
"coordinates": {
"latitude": 38.889838,
"longitude": -77.010529,
"routable_points": [
{
"latitude": 38.890573,
"longitude": -77.012128,
"name": "default"
}
]
},
"external_ids": {
"foursquare": "4c30bfa1ed37a593cf4d6903"
},
"feature_type": "poi",
"full_address": "Washington, District of Columbia 20024, United States",
"language": "en",
"maki": "marker",
"mapbox_id": "dXJuOm1ieHBvaTphMDAzZDViMi0xNDdiLTRkNDItYWI2MC04NTY4Njg1Y2EyNTA",
"metadata": {
"primary_photo": "https://ir.4sqi.net/img/general/original/599157053_FnwxpFSzBTDE2pzpIT24DR11ZFnlF9uM3IUzt5lAMAY.jpg"
},
"name": "West Front Capitol",
"operational_status": "active",
"place_formatted": "District of Columbia 20024, United States",
"poi_category": [
"outdoors",
"park"
],
"poi_category_ids": [
"outdoors",
"park"
]
}
}
Retrieve attribute sets
The /retrieve endpoint also provides detailed metadata about location features.
get
https://api.mapbox.com/search/details/v1/retrieve/{mapbox_id}
To request additional attributes, add attribute_sets parameter in your request for the/retrieve endpoint.
| Required parameters | Type | Description |
|---|---|---|
access_token | string | A Mapbox access token with default permissions. |
| Optional parameters | Type | Description |
|---|---|---|
attribute_sets | string | Coma separated labels for the attribute set requested. Allowed values for attribute sets are basic, visit, photos and venue. For a detail description of attribute sets, visit Attribute Sets section of this document. |
Example request: Retrieve attribute sets
# Get details for Planet Word in Washington DC, USA
# mapbox_id for this POI is dXJuOm1ieHBvaTo0ZTg2ZWFkNS1jOWMwLTQ3OWEtOTA5Mi1kMDVlNDQ3NDdlODk
$ curl "https://api.mapbox.com/search/details/v1/retrieve/dXJuOm1ieHBvaTo0ZTg2ZWFkNS1jOWMwLTQ3OWEtOTA5Mi1kMDVlNDQ3NDdlODk?attribute_sets=basic,visit,venue,photos&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Response: Retrieve Attribute Sets
Besides the basic metadata attributes described above, developers can request additional attributes by setting attribute_sets parameter with attribute set values, for example &attribute_sets=basic,photos,visit. The requested metadata will be provided in metadata object in the response.
| Attribute Set | Description |
|---|---|
| basic | Essential information about a location such as name, address and coordinates. This is the default value for attribute_sets parameter, and will be provided when attribute_sets is not provided in the request. |
| Photos | A collection of photos related to the location. |
| Visit | Visiting information for the location like website, phone number and social media handles. |
| Venue | Specific information about the location including a detailed description text, user reviews, price level and popularity. |
Response: "photos" attribute Set
Provide "photos" value in attribute_sets parameter to retrieve photos attribute set. The presence of this attribute set varies based on the feature type and geographic location, and is not guaranteed for all features.
| Property | Type | Description |
|---|---|---|
properties.metadata.photos | array | (Optional) A collection of photos related to the feature. |
Response: "visit" attribute Set
Provide visit value in attribute_sets parameter to retrieve visit information. Visit information includes phone number, social media profile handles, website address and opening hours based on availability. The presence of this attribute set and related attributes are based on the feature type and geographic location, and is not guaranteed for all features.
| Property | Type | Description |
|---|---|---|
properties.metadata.facebook_id | string | (Optional) The Facebook ID associated with the feature. |
properties.metadata.open_hours.periods | array | (Optional) An object containing the opening hours for the feature. This object includes properties for each day of the week (Day 0 is Sunday), specifying the open and close times. All times are provided in local time. |
properties.metadata.open_hours.weekday_text | array | (Optional) An array of strings representing the opening hours for each day of the week, Monday being the first day of week. |
properties.metadata.phone | string | (Optional) The phone number associated with the location. |
properties.metadata.website | string | (Optional) The website URL associated with the location. |
properties.metadata.fax | string | (Optional) The fax number associated with the location. |
properties.metadata.email | string | (Optional) The email address associated with the location. |
properties.metadata.instagram | string | (Optional) The Instagram handle associated with the location. |
properties.metadata.twitter | string | (Optional) The Twitter handle associated with the location. |
Response: "venue" attribute Set
Provide venue value in attribute_sets parameter to retrieve venue information. Venue information includes detailed text description for the location, user rating, popularity, price level, dining and take out information. The presence of this attribute set and related attributes are based on the feature type and geographic location, and is not guaranteed for all features.
| Property | Type | Description |
|---|---|---|
properties.metadata.detailed_description | string | (Optional) A comprehensive description of the feature. |
properties.metadata.price_level | string | (Optional) The price level of the location, represented by a string including dollar signs. The values scale from Cheap "$" to Most Expensive "$$$$". |
properties.metadata.review_count | integer | (Optional) The number of reviews for the location. |
properties.metadata.rating | float | (Optional) The average rating of the location, on a scale from 1 to 5. |
properties.metadata.popularity | float | (Optional) A popularity score for the location, calculated based on user engagement and review counts. The value scales from 0 to 1, 1 being the most popular. |
properties.metadata.delivery | boolean | (Optional) Indicates whether the location offers delivery services. |
properties.metadata.drive_through | boolean | (Optional) Indicates whether the location has a drive-through service. |
properties.metadata.reservable | boolean | (Optional) Indicates whether the location accepts reservations. |
properties.metadata.parking_available | boolean | (Optional) Indicates whether parking is available at the location. |
properties.metadata.valet_parking | boolean | (Optional) Indicates whether valet parking services are offered. |
properties.metadata.street_parking | boolean | (Optional) Indicates the availability of street parking near the location. |
properties.metadata.serves_breakfast | boolean | (Optional) Indicates whether breakfast is served. |
properties.metadata.serves_brunch | boolean | (Optional) Indicates whether brunch is served. |
properties.metadata.serves_dinner | boolean | (Optional) Indicates whether dinner is served. |
properties.metadata.serves_lunch | boolean | (Optional) Indicates whether lunch is served. |
properties.metadata.takeout | boolean | (Optional) Indicates whether takeout services are available. |
properties.metadata.serves_vegan | boolean | (Optional) Indicates whether vegan diet options are available. |
properties.metadata.serves_vegetarian | boolean | (Optional) Indicates whether vegetarian diet options are available. |
properties.metadata.serves_wine | boolean | (Optional) Indicates whether wine is served. |
properties.metadata.serves_beer | boolean | (Optional) Indicates whether beer is served. |
Example response: Retrieve attribute sets
{
"geometry": {
"coordinates": [
-77.029129,
38.902309
],
"type": "Point"
},
"properties": {
"address": "1300 I St NW",
"context": {
"address": {
"address_number": "1300",
"id": "",
"name": "1300 I St NW",
"street_name": "i street nw"
},
"country": {
"country_code": "US",
"country_code_alpha_3": "USA",
"id": "",
"name": "United States"
},
"neighborhood": {
"id": "dXJuOm1ieHBsYzpDaXpzN0E",
"name": "Downtown"
},
"place": {
"id": "dXJuOm1ieHBsYzpGSmlvN0E",
"name": "Washington"
},
"postcode": {
"id": "dXJuOm1ieHBsYzpBNTd1N0E",
"name": "20005"
},
"region": {
"id": "",
"name": "District of Columbia",
"region_code": "DC",
"region_code_full": "US-DC"
},
"street": {
"id": "",
"name": "i street nw"
}
},
"coordinates": {
"latitude": 38.902309,
"longitude": -77.029129,
"routable_points": [
{
"latitude": 38.902309,
"longitude": -77.029625,
"name": "default"
}
]
},
"external_ids": {
"foursquare": "5e4aa71ee6eec6000844fbfc"
},
"feature_type": "poi",
"full_address": "1300 I St NW, Washington, District of Columbia 20005, United States",
"language": "en",
"maki": "marker",
"mapbox_id": "dXJuOm1ieHBvaTo0ZTg2ZWFkNS1jOWMwLTQ3OWEtOTA5Mi1kMDVlNDQ3NDdlODk",
"metadata": {
"facebook_id": "212540879151543",
"instagram": "planetworddc",
"open_hours": {
"periods": [
{
"close": {
"day": 0,
"time": "1700"
},
"open": {
"day": 0,
"time": "1000"
}
},
{
"close": {
"day": 3,
"time": "1700"
},
"open": {
"day": 3,
"time": "1000"
}
},
{
"close": {
"day": 4,
"time": "1700"
},
"open": {
"day": 4,
"time": "1000"
}
},
{
"close": {
"day": 5,
"time": "1700"
},
"open": {
"day": 5,
"time": "1000"
}
},
{
"close": {
"day": 6,
"time": "1700"
},
"open": {
"day": 6,
"time": "1000"
}
}
],
"weekday_text": [
"Monday: Closed",
"Tuesday: Closed",
"Wednesday: 10:00 AM - 5:00 PM",
"Thursday: 10:00 AM - 5:00 PM",
"Friday: 10:00 AM - 5:00 PM",
"Saturday: 10:00 AM - 5:00 PM",
"Sunday: 10:00 AM - 5:00 PM"
]
},
"phone": "(202) 931-3139",
"photos": [
{
"url": "https://ir.4sqi.net/img/general/original/194412_8D0BWWEcRRbgGcsfMpswNiupQRlJLlrQP28Erzloebg.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/115057_MQdN9BDEQZjGuy0XR-wuFc-HASYk7iwvQCD9-oAEgzM.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/3274908_Kay_325FgRI5W6QjYQpgwGlhWC-IJYGRs17KdN3ve-I.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/66077586_3BKtXPeLChnT_FCk5kirieluzV7-Ky8J4E-JZL22Onk.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/19965560_WobfF7-NrFtRk8zEzHcNiLVsdC6Otetx8ATb7EshAbM.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/2322868_DmLkkx6w_B-dUhKESrCycq28r21LVBcGzmND0HfOYek.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/123590354_uqGGItENIJXwCC8-uF3ehDIvY_8Obhj734buR1Y4Vxo.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/194412_A1MklFbySLaCuTp1Mhr29Be_UEhwMbKWK1AeV2TGuV0.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/59629039_NwcrrOsHCZzTiADNsul0dRAh4bZGG_kJ9yTdYt_zpwk.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/24156413_7I-3YDekzbHFgKdK6jhQiV6lWuiQbUDBhem_H5C9EXM.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/24156413_eyXWL0zeTZkxAL9DOlXwq4rOr86WHNvg8xoEC-UDr-I.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/24156413_JKeXAEYToRCHEe7mEryRy_WLDPEDC04m_EkShC26uo4.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/24156413_qIP10lczOEhewkhAOSVF1KcJaFZSglu_uKvuhq9IhYM.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/24156413_yqrLz4ry4OxXpN5H605bOe8dUH2GMItE5Km__Gp-L-o.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/70340760_TawDz7yLBbyuqWxVurmICG70xSK7Wm1nYArJ2dkluYA.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/32924053_zJz3g6mA-X8gp8h2db-GK8UIOmlNOstaRXMHilQPf8U.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/32568130_rW_f8C5JGnHKtA1kuLMOH5HwcRX5gA5WOTEn5dgJggs.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/32568130_RKPKD1qnNKrQUfzzePiFi4aOGnLHdvRptWzFUdUkFgQ.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/70340760_RxOLGr0cd3mlR4nOrh10WFcMs6G_WhZDmFf7bOPYjw4.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/26504858_smq7TWn1uestTqxYQGDOXr7nYe8oEdKDkhX6uQuyj5E.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/16629655_QZo5zhKOEZPTZGTn389tG6auKxK9qHJA3e5nCLFqbyY.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/16629655_L8aigsFNvpuU6ghva2jhoU1Wakjt1hWlJZQvlw0U3S8.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/16629655_WZSdXxFCo6mYU1FQO70zRvwvmPIACsFZhfYJv9yPu64.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/1381541918_ZvHliiD-26bTa-BcBh9rc6cG4rkJ2w5ZfnD6hDJBOto.jpg"
},
{
"url": "https://ir.4sqi.net/img/general/original/203176_PBa31EbvtQzlYjHn_oZ6OUMC6Smh4Z8lQdxPxKaAea0.jpg"
}
],
"popular_hours": [
{
"day": 0,
"intervals": [
{
"end": {
"time": "1700"
},
"start": {
"time": "1000"
}
}
]
},
{
"day": 3,
"intervals": [
{
"end": {
"time": "1700"
},
"start": {
"time": "1000"
}
}
]
},
{
"day": 4,
"intervals": [
{
"end": {
"time": "1600"
},
"start": {
"time": "1000"
}
}
]
},
{
"day": 5,
"intervals": [
{
"end": {
"time": "1600"
},
"start": {
"time": "1000"
}
}
]
},
{
"day": 6,
"intervals": [
{
"end": {
"time": "1700"
},
"start": {
"time": "1000"
}
}
]
}
],
"popularity": 0.9859347240096058,
"primary_photo": "https://ir.4sqi.net/img/general/original/194412_8D0BWWEcRRbgGcsfMpswNiupQRlJLlrQP28Erzloebg.jpg",
"rating": 4.135,
"twitter": "planetworddc",
"website": "http://www.planetwordmuseum.org"
},
"name": "Planet Word",
"operational_status": "active",
"place_formatted": "Washington, District of Columbia 20005, United States",
"poi_category": [
"museum",
"tourist attraction"
],
"poi_category_ids": [
"museum",
"tourist_attraction"
]
},
"type": "Feature"
}
Retrieve boundary details
The Details API enables retrieving details for a specific boundary from the Mapbox Boundaries dataset. Mapbox customers who already use Mapbox Boundaries and want to retrieve an individual boundary detail can use /retrieve endpoint using a boundary feature id.
To use Details API with Mapbox Boundaries, your account need to have an active Mapbox Boundaries data license. If you are interest in Mapbox Boundaries, contact Mapbox Sales. With Details API, you are able to access only to boundary layers that are included in your Mapbox Boundaries license.
get
https://api.mapbox.com/search/details/v1/retrieve/{mapbox_id}
| Required parameters | Type | Description |
|---|---|---|
access_token | string | A Mapbox access token with default permissions. |
| Optional parameters | Type | Description |
|---|---|---|
worldview | string | The two digit ISO country code (such as 'JP') to requests a worldview for the location data, if applicable data is available. This parameters will only be applicable for Boundaries and Places feature types. |
language | string | The ISO language code to be returned. If not provided, the default is English. |
Example request: Retrieve boundary details
# Lookup boundary details for Huntington Beach, CA with boundary id: dXJuOm1ieGJuZDpNc2hFNlE6djQ
$ curl -X GET "https://api.mapbox.com/search/details/v1/retrieve/dXJuOm1ieGJuZDpNc2hFNlE6djQ?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Response: Retrieve boundary details
Each feature in the response body contains the following properties:
| Property | Type | Description |
|---|---|---|
type | string | This field will always contain the value "Feature", adhering to the GeoJSON specification. |
properties.mapbox_id | string | The unique ID identifies the related boundary feature. This ID is unique globally across all worldviews. |
properties.layer_type | string | Identifies the data type for the boundary layer (such as administrative, postal, or statistical). Refer to the Boundary types documentation for a comprehensive list of possible values and their meanings. |
properties.layer_level | integer | Indicates the boundary layer level, ranging from 0 to 5. |
properties.layer_name | string | A concise combination of the boundary's type and level, along with its administrative (adm), postal (pos), or statistical (sta) classification and level (0-5). For instance, an administrative level 1 boundary would be denoted as adm1. |
properties.worldview | string | Determines which set of alternate boundary data is displayed, based on regional map display requirements. The Boundaries reference document explains the possible values. |
properties.unit_code | string | A country-specific code for the feature, such as a postcode. |
properties.unit_code_description | string | Describes the unit_code in detail. |
properties.name | string | The local name of the feature. |
properties.name_en | string | Provides an English translation or Latin transliteration of the local name. This is typically provided when the original name is in a non-Latin script; otherwise, it may be null. |
properties.name_translations | JSON | Contains additional translations or aliases for the feature name. This may be null. |
properties.description | string | Textual description of the boundary level, which varies by each country's boundary hierarchy. For example, in the US, admin-1 boundaries are described as states, but in Italy, they are described as regions. |
properties.wikidata_id | string | The Wikidata ID associated with the boundary, if available. Not all features have a direct association with a Wikidata entity, hence this may be null. |
properties.source_date | string | Indicates how recent the boundary data is. |
properties.iso_3166_1_alpha_3 | string | The ISO 3166-1 alpha-3 code of the feature's parent country or territory. |
properties.iso_3166_1 | string | The ISO 3166-1 alpha-2 code of the feature's parent country or territory. |
properties.relational.grouping_attributes | object | An object containing properties that link the feature to relevant geographic groups. |
properties.relational.join_attributes | JSON | A JSON object containing properties that link the feature to relevant geographic codes. |
properties.relational.parents.parent_0 | string | Includes the ID of the level-0 parent feature, if applicable. |
properties.relational.parents.parent_1 | string | The ID of the level-1 parent of the feature, if present. |
properties.relational.parents.parent_2 | string | The ID of the level-2 parent of the feature, if present. |
properties.relational.parents.parent_3 | string | The ID of the level-3 parent of the feature, if present. |
properties.relational.parents.parent_4 | string | The ID of the level-4 parent of the feature, if present. |
properties.tileset.polygon_z_min | integer | Specifies the minimum zoom level at which a polygon feature is visible in a tileset. |
properties.tileset.point_z_min | integer | Specifies the minimum zoom level at which a point feature is visible in a tileset. |
geometry.centroid | array | Provides an approximate central point of the feature's polygon, formatted as [longitude, latitude]. |
bbox | array | Defines the feature's bounding box with coordinates [min long, min lat, max long, max lat at]. Features crossing the dateline will have longitude values outside the standard range of -180 to 180 degrees. |
properties.tileset.polygon_tileset_id | string | The ID of the tileset containing the feature's polygon. Refer to the Tilesets documentation for more details. |
properties.tileset.polygon_source_layer | string | The name of the source-layer within the polygon tileset that contains the feature. |
properties.tileset.point_tileset_id | string | The ID of the tileset containing the feature's point. Refer to the tilesets documentation for more details. |
properties.tileset.point_source_layer | string | The name of the source-layer within the point tileset that contains the feature. |
properties.area_sqkm | integer | The area of the boundary feature, expressed in square kilometers. |
type | string | This will always be "Feature". |
Example response: Retrieve boundary details
{
"bbox": [
-118.0742,
33.6296,
-117.9395,
33.7562
],
"geometry": {
"coordinates": [
-118.0066,
33.6925
],
"type": "Point"
},
"id": "dXJuOm1ieGJuZDpNc2hFNlE6djQ",
"properties": {
"area_sqkm": 89,
"description": "postal place",
"iso_3166_1": "US",
"iso_3166_1_alpha_3": "USA",
"layer_level": 2,
"layer_name": "loc2",
"layer_type": "locality",
"mapbox_id": "dXJuOm1ieGJuZDpNc2hFNlE6djQ",
"name": "Huntington Beach",
"name_translations": {
"en": [
"Huntington Beach",
"Huntington Beach, CA",
"Huntington Beach, California"
]
},
"relational": {
"parents": {
"parent_0": "dXJuOm1ieGJuZDo4aERwOnY0",
"parent_1": "dXJuOm1ieGJuZDpCVUxwOnY0"
}
},
"source_date": "2022",
"tileset": {
"point_source_layer": "points_locality_2",
"point_tileset_id": "mapbox.boundaries-locPoints-v4",
"point_z_min": 3,
"polygon_source_layer": "boundaries_locality_2",
"polygon_tileset_id": "mapbox.boundaries-loc2-v4",
"polygon_z_min": 4
},
"wikidata_id": "Q5917",
"worldview": "all"
},
"type": "Feature"
}
Retrieve multiple location details
With /retrieve endpoint, you can request multiple location details by adding mapbox_ids in the POST request body in the JSON format.
post
https://api.mapbox.com/search/details/v1/retrieve
Request Body (JSON)
{
"ids": "..."
}
| Required values | Type | Description |
|---|---|---|
ids | JSON | Comma delimited list of up to 100 Mapbox IDs |
| URL parameters | Type | Description |
|---|---|---|
access_token | string | (Required) A Mapbox access token with default permissions. |
worldview | string | The two digit ISO country code (such as 'JP') to requests a worldview for the location data, if applicable data is available. This parameters will only be applicable for Boundaries and Places feature types. |
language | string | The ISO language code to be returned. If not provided, the default is English. |
Administrative unit types
Various types of administrative units are available via the Search Box API. Any type might appear as a top-level response, as context in a top-level response, or as a filtering option using the optional types parameter. See the following table for available administrative unit types.
| Administrative unit type | Description |
|---|---|
country | Generally recognized countries or, in some cases like Hong Kong, an area of quasi-national administrative status 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. |
postcode | Postal codes used in country-specific national addressing systems. |
district | Features that are smaller than top-level administrative features but typically larger than cities, in countries that use such an additional layer in postal addressing (for example, prefectures in China). |
place | Typically these are cities, villages, municipalities, etc. They’re usually features used in postal addressing, and are suitable for display in ambient end-user applications where current-location context is needed (for example, in weather displays). |
locality | Official sub-city features present in countries where such an additional administrative layer is used in postal addressing, or where such features are commonly referred to in local parlance. Examples include city districts in Brazil and Chile and arrondissements in France. |
neighborhood | Colloquial sub-city features often referred to in local parlance. Unlike locality features, these typically lack official status and may lack universally agreed-upon boundaries. Not available for reverse lookup requests. |
street | The street, with no house number. |
address | Individual residential or business addresses as a street with house number. |
Details 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 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 | The mapbox_id for the requested feature does not exist. |
Details API restrictions and limits
- The Mapbox Terms of Service state that all data returned by the Details API endpoints is only available for temporary use. If your use case requires storing position data, contact Mapbox sales.
- The default rate limit for the Details API is 10 requests per second. If you require a higher rate limit, contact Mapbox Sales.
Details API pricing
Pricing for the Details API is request based and the cost of the request will depend on the attribute sets requested. For more details, review Mapbox Search Pricing.