Details API

Ready to get started?

Create a free account to start building with Mapbox.

Sign Up

Additional Developer Resources

Mapbox Developer Discord

Developer Cheatsheet

Mapbox Support

Ask AI

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.

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.

Ready to get started?

Create a free account to start building with Mapbox.

Sign Up

Additional Developer Resources

Mapbox Developer Discord

Developer Cheatsheet

Mapbox Support

Ask AI