Skip to main content

Places API

Public Preview

The Details endpoint of the Places API is in Public Preview. The API contract and response shape are subject to change without prior notice. Usage limits apply during Public Preview — see Places API restrictions and limits.

The Mapbox Places API gives developers access to a global dataset of over 250 million places. Details returns a complete Place record for one or more POIs identified by their mapbox_id. A Place is a real-world point of interest (POI) joined to its address, building, and, where available, historical activity, entrance, and photo data. Each record includes name, address, coordinates, categories, structured business attributes, and optional building, activity, and photo signals.

Details is designed to complement the Search Box API. Search Box returns a mapbox_id for each result. Pass that ID to Details to retrieve the full record.

Endpoint​

The Places API's Details endpoint is available at /details/retrieve, which supports single-record lookup (GET) and batch lookup (POST).

Retrieve a single Place​

get
https://api.mapbox.com/places/v1/details/retrieve/{mapbox_id}

Returns a single Place record identified by its mapbox_id.

Required parameters​

ParameterTypeDescription
mapbox_id (path)stringThe unique Mapbox ID of the Place to retrieve, for example a mapbox_id of a POI returned by the Search Box API.
access_tokenstringA valid Mapbox access token.

Response​

A successful 200 response returns a single Place record as a JSON object.

PropertyTypeDescription
mapbox_idstringThe unique Mapbox ID for the Place.
namestringThe name of the Place.
full_addressstringThe composed full address, including street, city, region, postcode, and country.
brandstring(Optional) The brand name associated with the Place.
primary_categorystringThe primary POI category.
categoriesarrayAll categories associated with the Place.
opening_hoursstring(Optional) The opening hours of the Place.
permanently_closedbooleanWhether the Place is permanently closed. May be null if the status is unknown.
phonestring(Optional) The phone number for the Place.
photosarray(Optional) A collection of photos associated with the Place. By default, only photos indexed from the POI's official website are included. See Photo properties.
websitestring(Optional) The website URL for the Place.
statusstringThe operational status of the record. Possible values: active, inactive.
created_atstringTimestamp when the record was first added to the dataset.
updated_atstringTimestamp when the record was last updated.
scoreobjectQuality and popularity scores. See Score properties.
coordinatesobjectGeographic coordinates and routable points. See Coordinates properties.
addressobjectStructured address components. See Address properties.
attributesobjectAdditional Place attributes such as cuisine, price level, or accessibility details. The set of keys varies by Place.
buildingobject(Optional) Building information for the structure containing the Place. Includes mapbox_id and tags.
telemetryobject(Optional) Hourly busyness scores by day of the week derived from Mapbox Telemetry data. See Telemetry properties for the full breakdown.

Score properties​

PropertyTypeDescription
score.closednumberLikelihood that the Place is permanently closed, on a scale of 0 to 1. Higher values indicate a higher likelihood. May be null.
score.realitynumberConfidence that the Place exists as a real-world entity, on a scale of 0 to 1. May be null.
score.popularitynumberA 0 to 1 score reflecting the Place's relative popularity based on signals across the web. May be null.

Coordinates properties​

PropertyTypeDescription
coordinates.latitudenumberThe latitude of the Place.
coordinates.longitudenumberThe longitude of the Place.
coordinates.sourcestringWhether the coordinates are as provided by the source (poi) or have been refined through Mapbox's automated pipeline (calculated) — for example, snapped to the building footprint using our geocoding and building data.
coordinates.routable_pointsarrayRoutable points for navigation, distinguishing the best vehicle access point from pedestrian building entrances.
coordinates.routable_points[].namestringThe type of access point. Possible values: driving (the best access point for vehicles, snapped to roads) and walking (a building entrance).
coordinates.routable_points[].latitudenumberThe latitude of the routable point.
coordinates.routable_points[].longitudenumberThe longitude of the routable point.

Address properties​

PropertyTypeDescription
address.mapbox_idstringThe Mapbox ID of the linked address record, if available.
address.address_line_1stringThe street address including house number and street name.
address.address_numberstringThe house or building number.
address.unitstringThe unit, suite, or apartment number.
address.street_namestringThe street name without the house number.
address.building_namestringThe name of the building, if applicable.
address.neighborhoodstring(Optional) The neighborhood of the Place.
address.neighborhood_idstring(Optional) The Mapbox ID for the neighborhood.
address.localitystring(Optional) The locality or sub-city area.
address.locality_idstring(Optional) The Mapbox ID for the locality.
address.citystring(Optional) The city.
address.city_idstring(Optional) The Mapbox ID for the city.
address.postcodestring(Optional) The postal code.
address.postcode_idstring(Optional) The Mapbox ID for the postcode.
address.regionstring(Optional) The state, province, or region.
address.region_code_fullstring(Optional) The ISO 3166-2 region code (for example, "US-CA").
address.countrystring(Optional) The country name.
address.country_codestring(Optional) The ISO 3166-1 alpha-2 country code (for example, "US").
address.country_idstring(Optional) The Mapbox ID for the country.
address.tagsobject(Optional) Additional address tags from the source data.

Telemetry properties​

telemetry is returned only for Places where enough activity data is available. Scores reflect typical historical patterns of visits, not real-time or current occupancy. During Public Preview, coverage includes select categories, including food and drink, retail, consumer services, and entertainment, across the US, Canada, and parts of Western Europe.

PropertyTypeDescription
telemetry.activity_scoreobjectHourly busyness scores by day of the week. Each key is a day (mon through sun); each value is a 24-element array of integers representing busyness at hours 0-23 (midnight to 11 PM) in the Place's local time. Values range from 0 (no activity) to 100 (peak activity for that Place).

Photo properties​

By default, only photos indexed from the POI's official website are available. Developers who need user- and business-contributed photos from our partner photo network can request access by contacting Mapbox sales.

PropertyTypeDescription
photos[].urlstringThe direct URL hosting the image asset.
photos[].widthnumber(Optional) The width of the photo image, in pixels. May be null if not available from the source.
photos[].heightnumber(Optional) The height of the photo image, in pixels. May be null if not available from the source.
photos[].sourcestringThe source or provider of the photo record (for example, "web").

Example request: Retrieve a single Place​

$curl "https://api.mapbox.com/places/v1/details/retrieve/dXJuOm1ieHBvaTpmNTFkZTYzYi1jNWJkLTQ0ZmMtYWU1MC1kZmIyYzE3NWY2Nzg?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Example response: Retrieve a single Place​

{
  "mapbox_id": "dXJuOm1ieHBvaTpmNTFkZTYzYi1jNWJkLTQ0ZmMtYWU1MC1kZmIyYzE3NWY2Nzg",
  "name": "Le Chalet de la Forêt",
  "full_address": "Drève de Lorraine 43, Uccle, 1180, Belgium",
  "brand": null,
  "primary_category": "food",
  "categories": ["food", "food_and_drink", "restaurant"],
  "opening_hours": "Mo 12:00-21:00; Tu 12:00-21:00; We 12:00-14:00; Th 12:00-21:00; Fr 12:00-21:00",
  "permanently_closed": false,
  "phone": "+3223745416",
  "photos": [
    {
      "url": "https://lechaletdelaforet.be/wp-content/gallery/exemple/batisse-jour.JPG",
      "width": null,
      "height": null,
      "source": "web"
    },
    {
      "url": "https://lechaletdelaforet.be/wp-content/gallery/exemple/Batisse-nuit.jpg",
      "width": null,
      "height": null,
      "source": "web"
    },
    {
      "url": "https://lechaletdelaforet.be/wp-content/gallery/exemple/grande-salle1.jpg",
      "width": null,
      "height": null,
      "source": "web"
    },
    {
      "url": "https://lechaletdelaforet.be/wp-content/gallery/exemple/salle-%C3%A0-manger.jpg",
      "width": null,
      "height": null,
      "source": "web"
    },
    {
      "url": "https://lechaletdelaforet.be/wp-content/gallery/exemple/chalet170.jpg",
      "width": null,
      "height": null,
      "source": "web"
    }
  ],
  "website": "http://www.lechaletdelaforet.be/",
  "status": "active",
  "created_at": "2026-07-02T02:56:22.965",
  "updated_at": "2026-07-15T01:45:22.019",
  "score": {
    "closed": 0,
    "popularity": 0.983,
    "reality": 0.9
  },
  "coordinates": {
    "latitude": 50.784679,
    "longitude": 4.386543,
    "source": "calculated",
    "routable_points": [
      {
        "name": "driving",
        "latitude": 50.78460525690568,
        "longitude": 4.386692888535319
      }
    ]
  },
  "address": {
    "mapbox_id": "dXJuOm1ieGFkcjphZWRlNGM1Yi0xM2MxLTQ1NjMtODc3OC1jZjFiZTViZGI5ZWE",
    "address_line_1": "Drève de Lorraine 43",
    "address_number": "43",
    "unit": null,
    "street_name": "Drève De Lorraine - Lorrainedreef",
    "building_name": null,
    "locality": "Ukkel",
    "locality_id": "dXJuOm1ieHBsYzo3Y29W",
    "city": "Uccle",
    "city_id": "dXJuOm1ieHBsYzpRSWdW",
    "postcode": "1180",
    "postcode_id": "dXJuOm1ieHBsYzpBbTRW",
    "region_code_full": "BE-BRU",
    "country": "Belgium",
    "country_id": "dXJuOm1ieHBsYzpJaFU",
    "country_code": "BE"
  },
  "attributes": {
    "accommodation_wheelchair_accessible_entrance": true,
    "accommodation_wheelchair_accessible_parking": true,
    "accommodation_wheelchair_accessible_restroom": true,
    "accommodation_wheelchair_accessible_seating": true,
    "environment_cozy": true,
    "environment_quiet": true,
    "environment_romantic": true,
    "environment_upscale": true,
    "feature_fireplace": true,
    "feature_outdoor_seating": true,
    "feature_restroom": true,
    "feature_wi_fi": true,
    "group_friendly": true,
    "known_for_cocktails": true,
    "known_for_coffee": true,
    "known_for_dessert": true,
    "known_for_tea": true,
    "known_for_wine": true,
    "offering_alcohol": true,
    "offering_beer": true,
    "offering_cocktails": true,
    "offering_coffee": true,
    "offering_dessert": true,
    "offering_dinner": true,
    "offering_liquor": true,
    "offering_lunch": true,
    "offering_popular_dinner": true,
    "offering_popular_lunch": true,
    "offering_vegetarian_options": true,
    "offering_wine": true,
    "payment_type_credit_card": true,
    "payment_type_debit_card": true,
    "payment_type_mobile_nfc": true,
    "price_level": "Expensive",
    "reservations_dinner_recommended": true,
    "reservations_lunch_recommended": true,
    "reservations_required": true,
    "service_catering": true,
    "service_curbside_pickup": true,
    "service_delivery": false,
    "service_dine_in": true,
    "service_takeout": false,
    "solo_dining_friendly": true,
    "tourist_friendly": true
  },
  "telemetry": {
    "activity_score": {
      "mon": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 62, 72, 78, 86, 92, 98, 97, 91, 83, 0, 0, 0],
      "tue": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 94, 99, 94, 81, 0, 0, 0],
      "wed": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 48, 47, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      "thu": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 73, 78, 81, 73, 69, 63, 52, 49, 0, 0, 0, 0],
      "fri": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 46, 50, 60, 72, 84, 96, 100, 98, 88, 0, 0, 0],
      "sat": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      "sun": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    },
    "tags": {
      "names": "Le Chalet de la Forêt",
      "timezone": "Europe/Brussels"
    }
  }
}

Retrieve multiple Places​

post
https://api.mapbox.com/places/v1/details/retrieve

Returns Place records for a batch of up to 100 mapbox_id values in a single request.

Request body​

{
  "ids": ["mapbox_id_1", "mapbox_id_2"]
}
FieldTypeDescription
idsarrayRequired. An array of mapbox_id strings. Maximum 100 IDs per request.

URL parameters​

ParameterTypeDescription
access_tokenstringA valid Mapbox access token.

Response​

PropertyTypeDescription
resultsarrayPlace records for each ID that was successfully resolved.
missingarray (Optional) IDs that could not be found.
unprocessedarray(Optional) IDs that could not be processed.

The response status is 200 if all IDs are resolved, or 206 Partial Content if any IDs are missing or unprocessed.

Example request: Retrieve multiple Places​

$curl -X POST "https://api.mapbox.com/places/v1/details/retrieve?access_token=YOUR_MAPBOX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["dXJuOm1ieHBvaTozNWJkODZlOS01NTk0LTQ4MGUtYjhhNC0zYzk2YjY0ZDVhNjg", "dXJuOm1ieHBvaTo2MTg4OGFiMC1lYTliLTRjMWEtYWVkYy03ODE3ZmY0YmMwYWE", "dXJuOm1ieHBvaTpub3RfZm91bmQ"]}'

Example response: Retrieve multiple Places​

{
  "results": [
    {
      "mapbox_id": "dXJuOm1ieHBvaTozNWJkODZlOS01NTk0LTQ4MGUtYjhhNC0zYzk2YjY0ZDVhNjg",
      "name": "Raising Cane's",
      "full_address": "3820 South Hamilton Rd, Groveport, Ohio, 43125, United States",
      "brand": "Raising Cane's Chicken Fingers",
      "primary_category": "food",
      "categories": ["fast_food", "food", "food_and_drink"],
      "opening_hours": "Mo 10:00-02:00; Tu 10:00-02:00; We 10:00-02:00; Th 10:00-02:00; Fr 10:00-03:00; Sa 10:00-03:00; Su 10:00-02:00",
      "permanently_closed": false,
      "phone": "+16146268101",
      "website": "https://locations.raisingcanes.com/oh/groveport/3820-south-hamilton-rd",
      "status": "active",
      "created_at": "2026-07-02T02:56:22.965",
      "updated_at": "2026-07-15T02:05:53.312",
      "score": {
        "closed": 0,
        "popularity": 0.989,
        "reality": 0.9
      },
      "coordinates": {
        "latitude": 39.896531,
        "longitude": -82.881561,
        "source": "calculated",
        "routable_points": [
          {
            "name": "driving",
            "latitude": 39.89657201037505,
            "longitude": -82.88180465043895
          },
          {
            "name": "walking",
            "latitude": 39.8966,
            "longitude": -82.881701
          }
        ]
      },
      "address": {
        "mapbox_id": "dXJuOm1ieGFkcjpkZDliZDU4MS1mMjMxLTQzNTktOTMxNC04MGU2NDQxYzAzZWU",
        "address_line_1": "3820 South Hamilton Rd",
        "address_number": "3820",
        "unit": null,
        "street_name": "South Hamilton Road",
        "building_name": null,
        "neighborhood": "Winchester",
        "neighborhood_id": "dXJuOm1ieHBsYzpLejFzN0E",
        "city": "Groveport",
        "city_id": "dXJuOm1ieHBsYzpHY3BJN0E",
        "postcode": "43125",
        "postcode_id": "dXJuOm1ieHBsYzpDSTZ1N0E",
        "region": "Ohio",
        "region_code_full": "US-OH",
        "country": "United States",
        "country_id": "dXJuOm1ieHBsYzpJdXc",
        "country_code": "US"
      },
      "attributes": {
        "accommodation_high_chairs": true,
        "accommodation_wheelchair_accessible_entrance": true,
        "accommodation_wheelchair_accessible_parking": true,
        "accommodation_wheelchair_accessible_restroom": true,
        "accommodation_wheelchair_accessible_seating": true,
        "children_friendly": true,
        "environment_casual": true,
        "family_friendly": true,
        "feature_counter_service": true,
        "feature_drive_through": true,
        "feature_restroom": true,
        "feature_seating": true,
        "feature_wi_fi": true,
        "geocoded:building_id": "0e48343c-7d6d-589a-9ba1-6ab729615e5e",
        "group_friendly": true,
        "known_for_tea": true,
        "offering_active_military_discount": true,
        "offering_childrens_menu": true,
        "offering_comfort_food": true,
        "offering_dinner": true,
        "offering_late_night_food": true,
        "offering_lunch": true,
        "offering_popular_dinner": true,
        "offering_popular_lunch": true,
        "offering_salad_bar": true,
        "payment_type_check": true,
        "payment_type_credit_card": true,
        "payment_type_debit_card": true,
        "payment_type_mobile_nfc": true,
        "price_level": "Cheap",
        "service_catering": true,
        "service_curbside_pickup": true,
        "service_delivery": false,
        "service_dine_in": true,
        "service_fast_service": true,
        "service_quick_bite": true,
        "service_takeout": true,
        "solo_dining_friendly": true,
        "student_friendly": true,
        "tourist_friendly": true
      },
      "building": {
        "mapbox_id": "0e48343c-7d6d-589a-9ba1-6ab729615e5e",
        "tags": {}
      },
      "telemetry": {
        "activity_score": {
          "mon": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 42, 51, 58, 62, 63, 65, 68, 70, 75, 77, 77, 70, 58, 47],
          "tue": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 40, 49, 53, 56, 58, 61, 68, 75, 81, 85, 85, 77, 65, 50],
          "wed": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 42, 53, 59, 64, 65, 69, 73, 77, 82, 84, 84, 77, 64, 52],
          "thu": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 41, 51, 57, 63, 67, 71, 77, 84, 90, 95, 95, 88, 75, 61],
          "fri": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 52, 63, 70, 74, 75, 78, 84, 90, 94, 98, 100, 93, 81, 66],
          "sat": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 40, 53, 64, 72, 78, 83, 88, 91, 92, 92, 92, 84, 72, 58],
          "sun": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 41, 54, 66, 74, 78, 81, 81, 80, 80, 78, 79, 72, 63, 52]
        },
        "tags": {
          "names": "Raising Cane's",
          "timezone": "America/New_York"
        }
      },
      "photos": [
        {
          "url": "https://a.mktgcdn.com/p/VvhMLbI2GFfXRH0LLngDtXAfMoWG2elDVglpeZsYI5A/1500x2100.webp",
          "width": 1500,
          "height": 2100,
          "source": "web"
        },
        {
          "url": "https://a.mktgcdn.com/p/Mv_zGf0Uc43jHUX3-v5tW8YS-YM-eSLXlsTLpQxrJ2o/1080x1080.jpg",
          "width": 1080,
          "height": 1080,
          "source": "web"
        }
      ]
    },
    {
      "mapbox_id": "dXJuOm1ieHBvaTo2MTg4OGFiMC1lYTliLTRjMWEtYWVkYy03ODE3ZmY0YmMwYWE",
      "name": "Raising Cane's",
      "full_address": "3661 E. Main Street, Columbus, Ohio, 43213, United States",
      "brand": "Raising Cane's Chicken Fingers",
      "primary_category": "food",
      "categories": ["fast_food", "food", "food_and_drink"],
      "opening_hours": "Mo 10:00-01:00; Tu 10:00-01:00; We 10:00-01:00; Th 10:00-01:00; Fr 10:00-02:00; Sa 10:00-02:00; Su 10:00-01:00",
      "permanently_closed": false,
      "phone": "+16149643265",
      "website": "https://locations.raisingcanes.com/oh/whitehall/3661-e.-main-street",
      "status": "active",
      "created_at": "2026-07-02T02:56:22.965",
      "updated_at": "2026-07-15T01:45:22.019",
      "score": {
        "closed": 0,
        "popularity": 0.946,
        "reality": 0.9
      },
      "coordinates": {
        "latitude": 39.955763,
        "longitude": -82.900172,
        "source": "calculated",
        "routable_points": [
          {
            "name": "driving",
            "latitude": 39.95599938711479,
            "longitude": -82.90012835534041
          }
        ]
      },
      "address": {
        "mapbox_id": "dXJuOm1ieGFkcjpmYzdjM2E4ZC1iMjZmLTQ0MzMtOTA4Zi0yZTBjNjg4NzEzOGQ",
        "address_line_1": "3661 E. Main Street",
        "address_number": "3661",
        "unit": null,
        "street_name": "East Main Street",
        "building_name": null,
        "locality": "Whitehall",
        "locality_id": "dXJuOm1ieHBsYzpJL3BxN0E",
        "city": "Columbus",
        "city_id": "dXJuOm1ieHBsYzpCQmRvN0E",
        "postcode": "43213",
        "postcode_id": "dXJuOm1ieHBsYzpDSlFPN0E",
        "region": "Ohio",
        "region_code_full": "US-OH",
        "country": "United States",
        "country_id": "dXJuOm1ieHBsYzpJdXc",
        "country_code": "US"
      },
      "attributes": {
        "accommodation_high_chairs": true,
        "accommodation_wheelchair_accessible_entrance": true,
        "accommodation_wheelchair_accessible_parking": true,
        "accommodation_wheelchair_accessible_restroom": true,
        "accommodation_wheelchair_accessible_seating": true,
        "children_friendly": true,
        "environment_casual": true,
        "family_friendly": true,
        "feature_counter_service": true,
        "feature_drive_through": true,
        "feature_outdoor_seating": true,
        "feature_restroom": true,
        "feature_seating": true,
        "feature_wi_fi": true,
        "group_friendly": true,
        "offering_active_military_discount": true,
        "offering_childrens_menu": true,
        "offering_dinner": true,
        "offering_late_night_food": true,
        "offering_lunch": true,
        "offering_popular_dinner": true,
        "offering_popular_lunch": true,
        "payment_type_check": true,
        "payment_type_credit_card": true,
        "payment_type_debit_card": true,
        "payment_type_mobile_nfc": true,
        "price_level": "Cheap",
        "service_catering": true,
        "service_curbside_pickup": true,
        "service_delivery": false,
        "service_dine_in": true,
        "service_fast_service": true,
        "service_quick_bite": true,
        "service_takeout": true,
        "solo_dining_friendly": true
      },
      "telemetry": {
        "activity_score": {
          "mon": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 27, 35, 41, 46, 49, 50, 51, 55, 59, 63, 63, 58, 51, 40],
          "tue": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 29, 36, 43, 48, 51, 54, 59, 65, 72, 77, 77, 71, 60, 46],
          "wed": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 29, 36, 42, 47, 50, 53, 57, 65, 71, 76, 77, 73, 63, 50],
          "thu": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 30, 39, 48, 56, 61, 66, 71, 76, 83, 85, 84, 78, 66, 52],
          "fri": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 35, 43, 52, 61, 67, 73, 81, 90, 96, 99, 100, 93, 81, 64],
          "sat": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 26, 38, 50, 59, 67, 73, 78, 81, 84, 85, 88, 82, 72, 58],
          "sun": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 30, 42, 53, 60, 67, 69, 71, 71, 73, 74, 76, 69, 60, 48]
        },
        "tags": {
          "names": "Raising Cane's",
          "timezone": "America/New_York"
        }
      },
      "photos": [
        {
          "url": "https://a.mktgcdn.com/p/VvhMLbI2GFfXRH0LLngDtXAfMoWG2elDVglpeZsYI5A/1500x2100.webp",
          "width": 1500,
          "height": 2100,
          "source": "web"
        },
        {
          "url": "https://a.mktgcdn.com/p/uE3gjfKzgyqmC3vaK_ACiKpH5Uez5FGa7c_AVh9cedA/1500x2000.webp",
          "width": 1500,
          "height": 2000,
          "source": "web"
        }
      ]
    }
  ],
  "missing": ["dXJuOm1ieHBvaTpub3RfZm91bmQ"]
}

Places API errors​

HTTP statusmessageDescription
400Bad requestThe request is malformed. For batch requests, verify that ids is a non-empty array with no more than 100 entries.
401Not authorizedThe access token is missing or invalid. Check the access token used in the request.
403ForbiddenThe access token does not have the places:read scope, or the account does not have access to the Places API. Check your Account page for more details.
404Not foundThe requested mapbox_id does not exist.
422Unprocessable EntityOne or more mapbox_id values have an invalid format.
429Too Many Requests / Quota ExceededThe request exceeds the rate limit or monthly quota. See Places API restrictions and limits.

Places API restrictions and limits​

  • Data returned by the Places API is for temporary display and use only. Storage of location data from this API requires a separate agreement. Contact Mapbox sales for storage licensing.
  • The default rate limit for the Places API is 100 records per second. Both single-record (GET) and batch (POST) requests count against this limit; a batch request is charged by the number of IDs submitted. If you require a higher rate limit, contact us.
  • The default monthly quota during Public Preview is 1,000 records per account. A record is counted when it is successfully returned in a response. If you require an expanded quota, contact us.
  • If you exceed the rate limit or monthly quota, you will receive an HTTP 429 response. For information on rate limit headers, see the Rate limit headers section.
Was this page helpful?