Skip to main content

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.

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.

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.

Retrieve POI Details

With 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.

Required parametersTypeDescription
mapbox_idstringA unique identifier for the geographic feature
access_tokenstringA Mapbox access token with default permissions.
Optional parametersTypeDescription
worldviewstringThe 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.
languagestringThe ISO language code to be returned. If not provided, the default is English.

Get mapbox_id for a feature

Mapbox_id serves as a unique identifier for a geographic feature such as POI, Address, Boundary or Place. 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.

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= <UserAccessToken /> "

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:

PropertyTypeDescription
geometry.coordinatesarrayThe geographical coordinates of the result.
geometry.typestringThis will always be "Point".
properties.addressstringThe address of the result including the address number and street.
properties.contextobjectThe 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.countryobjectThe 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.regionobjectThe region of the result. This layer includes properties id, name, region_code, and region_code_full (the ISO_3166_2 code).
properties.context.postcodeobjectThe postcode of the result. This layer includes properties id and name.
properties.context.districtobjectThe district of the result. This layer includes properties id and name.
properties.context.placeobjectThe place of the result. This layer includes properties id and name.
properties.context.localityobjectThe locality of the result. This layer includes properties id and name.
properties.context.neighborhoodobjectThe neighborhood of the result. This layer includes properties id and name.
properties.coordinatesobjectThe geographical coordinates of the result.
properties.coordinates.longitudenumberThe longitudinal coordinate of the result.
properties.coordinates.latitudenumberThe latitudinal coordinate of the result.
properties.coordinates.routable_pointsarrayAn array of objects containing information about the feature's routable points. A routable point object contains properties name, latitude, and longitude.
properties.external_idsobjectAn 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_typestringThe 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_addressstringThe full address of the result, which concatenates address and place_formatted.
properties.languagestringAn 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.makistringA string representing an associated Maki icon to use for this result.
properties.mapbox_idstringA unique ID associated with the feature.
properties.metadataobjectAn object containing additional metadata for the feature, if applicable.
properties.namestringThe name of the feature.
properties.operational_statusstringThe operational status for the location or associated business. The string value contains active, or closed.
properties.place_formattedstringA 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_categoryarrayAn array including the POI categories the result falls into, if it is a POI.
properties.poi_category_idsarrayAn array including the canonical POI category IDs the result falls into, if it is a POI.
properties.metadata.wheelchair_accessibleboolean(Optional) Indicates whether the location is accessible by wheelchair. Possible values are true or false.
properties.metadata.primary_photostring(Optional) The URL for the primary photo of the location.
properties.brandarray(Optional) The names of the brands associated with the POI.
properties.brand_idarray(Optional) The unique identifier for the brands associated with the POI.
typestringThis will always be "Feature".

The optional properties are not provided for all features, and the availability depends on the type of feature and geography.

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 SetDescription
basicEssential 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.
PhotosA collection of photos related to the location.
VisitVisiting information for the location like website, phone number and social media handles.
VenueSpecific 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.

PropertyTypeDescription
properties.metadata.photosarray(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.

PropertyTypeDescription
properties.metadata.facebook_idstring(Optional) The Facebook ID associated with the feature.
properties.metadata.open_hours.periodsarray(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_textarray(Optional) An array of strings representing the opening hours for each day of the week, Monday being the first day of week.
properties.metadata.phonestring(Optional) The phone number associated with the location.
properties.metadata.websitestring(Optional) The website URL associated with the location.
properties.metadata.faxstring(Optional) The fax number associated with the location.
properties.metadata.emailstring(Optional) The email address associated with the location.
properties.metadata.instagramstring(Optional) The Instagram handle associated with the location.
properties.metadata.twitterstring(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.

PropertyTypeDescription
properties.metadata.detailed_descriptionstring(Optional) A comprehensive description of the feature.
properties.metadata.price_levelstring(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_countinteger(Optional) The number of reviews for the location.
properties.metadata.ratingfloat(Optional) The average rating of the location, on a scale from 1 to 5.
properties.metadata.popularityfloat(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.deliveryboolean(Optional) Indicates whether the location offers delivery services.
properties.metadata.drive_throughboolean(Optional) Indicates whether the location has a drive-through service.
properties.metadata.reservableboolean(Optional) Indicates whether the location accepts reservations.
properties.metadata.parking_availableboolean(Optional) Indicates whether parking is available at the location.
properties.metadata.valet_parkingboolean(Optional) Indicates whether valet parking services are offered.
properties.metadata.street_parkingboolean(Optional) Indicates the availability of street parking near the location.
properties.metadata.serves_breakfastboolean(Optional) Indicates whether breakfast is served.
properties.metadata.serves_brunchboolean(Optional) Indicates whether brunch is served.
properties.metadata.serves_dinnerboolean(Optional) Indicates whether dinner is served.
properties.metadata.serves_lunchboolean(Optional) Indicates whether lunch is served.
properties.metadata.takeoutboolean(Optional) Indicates whether takeout services are available.
properties.metadata.serves_vegan_dietstring(Optional) Indicates a rating for vegan diet options that are available. Possible values are Poor, Average, and Great.
properties.metadata.serves_vegetarian_dietstring(Optional) Indicates a ranking for vegetarian diet options that are available. Possible values are Poor, Average, and Great.
properties.metadata.serves_wineboolean(Optional) Indicates whether wine is served.
properties.metadata.serves_beerboolean(Optional) Indicates whether beer is served.

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 parametersTypeDescription
access_tokenstringA Mapbox access token with default permissions.
Optional parametersTypeDescription
attribute_setsstringComa 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= <UserAccessToken /> "

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 parametersTypeDescription
access_tokenstringA Mapbox access token with default permissions.
Optional parametersTypeDescription
worldviewstringThe 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.
languagestringThe 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= <UserAccessToken /> "

Response: Retrieve boundary details

Each feature in the response body contains the following properties:

PropertyTypeDescription
typestringThis field will always contain the value "Feature", adhering to the GeoJSON specification.
properties.mapbox_idstringThe unique ID identifies the related boundary feature. This ID is unique globally across all worldviews.
properties.layer_typestringIdentifies 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_levelintegerIndicates the boundary layer level, ranging from 0 to 5.
properties.layer_namestringA 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.worldviewstringDetermines which set of alternate boundary data is displayed, based on regional map display requirements. The Boundaries reference document explains the possible values.
properties.unit_codestringA country-specific code for the feature, such as a postcode.
properties.unit_code_descriptionstringDescribes the unit_code in detail.
properties.namestringThe local name of the feature.
properties.name_enstringProvides 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_translationsJSONContains additional translations or aliases for the feature name. This may be null.
properties.descriptionstringTextual 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_idstringThe 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_datestringIndicates how recent the boundary data is.
properties.iso_3166_1_alpha_3stringThe ISO 3166-1 alpha-3 code of the feature's parent country or territory.
properties.iso_3166_1stringThe ISO 3166-1 alpha-2 code of the feature's parent country or territory.
properties.relational.grouping_attributesobjectAn object containing properties that link the feature to relevant geographic groups.
properties.relational.join_attributesJSONA JSON object containing properties that link the feature to relevant geographic codes.
properties.relational.parents.parent_0stringIncludes the ID of the level-0 parent feature, if applicable.
properties.relational.parents.parent_1stringThe ID of the level-1 parent of the feature, if present.
properties.relational.parents.parent_2stringThe ID of the level-2 parent of the feature, if present.
properties.relational.parents.parent_3stringThe ID of the level-3 parent of the feature, if present.
properties.relational.parents.parent_4stringThe ID of the level-4 parent of the feature, if present.
properties.tileset.polygon_z_minintegerSpecifies the minimum zoom level at which a polygon feature is visible in a tileset.
properties.tileset.point_z_minintegerSpecifies the minimum zoom level at which a point feature is visible in a tileset.
geometry.centroidarrayProvides an approximate central point of the feature's polygon, formatted as [longitude, latitude].
bboxarrayDefines 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_idstringThe ID of the tileset containing the feature's polygon. Refer to the Tilesets documentation for more details.
properties.tileset.polygon_source_layerstringThe name of the source-layer within the polygon tileset that contains the feature.
properties.tileset.point_tileset_idstringThe ID of the tileset containing the feature's point. Refer to the tilesets documentation for more details.
properties.tileset.point_source_layerstringThe name of the source-layer within the point tileset that contains the feature.
properties.area_sqkmintegerThe area of the boundary feature, expressed in square kilometers.
typestringThis 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 valuesTypeDescription
idsJSONComma delimited list of up to 100 Mapbox IDs
URL parametersTypeDescription
access_tokenstring(Required) A Mapbox access token with default permissions.
worldviewstringThe 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.
languagestringThe 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 typeDescription
countryGenerally 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.
regionTop-level sub-national administrative features, such as states in the United States or provinces in Canada or China.
postcodePostal codes used in country-specific national addressing systems.
districtFeatures 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).
placeTypically 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).
localityOfficial 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.
neighborhoodColloquial 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.
streetThe street, with no house number.
addressIndividual residential or business addresses as a street with house number.

Details API errors

Response body messageHTTP error codeDescription
Not authorized401Check the access token used in the query.
Bad request400Check the request for syntax errors in the endpoint, path parameters, and query parameters.
Forbidden403There 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 Found404The 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.