Search

Documentation for the Search API is also available in Japanese.

The Mapbox Search API can be used to provide an interactive search experience for end users, or can support stand-alone forward and reverse geocoding queries.

Search API endpoints

The Search API includes six different endpoints: /suggest, /retrieve, /forward, /permanent/forward, /reverse, and /permanent/reverse.

Suggest

The /suggest endpoint is used in combination with the /retrieve endpoint to create an interactive search experience for end users. Within your application, send user searches to the /suggest endpoint. When a user selects a result on the application UI, that gets sent to the /retrieve endpoint. For more details, see the Retrieve a suggestion section of this documentation.

Retrieve

If the user selects one of the results from the /suggest endpoint, that gets sent to the /retrieve endpoint, which provides detailed information about that feature including geographic coordinates. Once a /retrieve action is taken, the Search API returns GeoJSON with coordinate information for the selected feature or features. For more details, see the Retrieve a suggested feature section of this documentation.

Forward geocoding

The /forward endpoint allows you to look up a single location by name and returns its geographic coordinates. For more details, see the Forward geocoding section of this documentation.

Permanent forward geocoding

The /permanent/forward endpoint is used for use cases that require storing position data. Like the /forward endpoint, it allows you to look up a single location by name and returns its geographic coordinates. For more details, see the Permanent forward geocoding section of this documentation.

Reverse geocoding

The /reverse endpoint allows you to look up a single pair of coordinates and returns the geographic feature or features that exist at that location. For more details, see the Reverse geocoding section of this documentation.

Permanent reverse geocoding

The /permanent/reverse endpoint is used for use cases that require storing position data. Like the /reverse endpoint, it allows you to look up a single pair of coordinates and returns the geographic feature or features that exist at that location. For more details, see the Permanent reverse geocoding section of this documentation.

Administrative unit types

Various types of administrative units are available via the Search API. Any type might appear as a top-level response, as context in a top-level response, or as a filtering option using the optional types parameter. See the following table for available administrative unit types. Note that /search/v1 allows localized place names as an alternative to the standard administrative unit. In the beta release, this feature has only been enabled for Japan.

Session Phase 1: Request suggestions

Request a suggestion. The suggest endpoint provides place predictions about what an end user is searching for, based on autocomplete of the user query. This endpoint, along with the retrieve endpoint, can be used to add autocomplete functionality to applications that include geographic searches.

You can further refine the results of a query to this endpoint with the following optional parameters:

Category suggestion requires at least one of bbox, origin or proximity to be specified.

Example requests: Request a suggestion

# Search for Empire State Building with limit=1

$ curl "https://api.mapbox.com/search/v1/suggest/Empire%20State%20Building?language=en&limit=1&session_token=[GENERATED-UUID]&proximity=-75.38661,39.82049&country=US&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Search for 新橋一丁十番一号,東京都港区新橋1丁目10番1号 with limit=1

$ curl "https://api.mapbox.com/search/v1/suggest/新橋一丁十番一号,東京都港区新橋1丁目10番1号?language=ja&limit=1&session_token=[GENERATED-UUID]&proximity=13.38333,52.51667&country=JP&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Request a suggestion

The response to a request to the /suggest endpoint is an array of JSON suggestion objects. A suggestion will include a result name, a short description, and additional metadata when available (such as distance to proximity point). It does not include geographic coordinates. To get coordinates, make a call to the /retrieve endpoint with the information provided in the /suggest result's "action" block. The "action" block is opaque and can be used without inspection in your application.

Using the limit parameter, you can increase the maximum number of results up to 10. Pagination is not available, but this feature may be added in a later release. There is not an option to customize the order of search results.

Each result object contains the following properties:

Each suggestion object contains the following properties:

Example responses: Request a suggestion

{
  "suggestions": [
    {
      "feature_name": "Empire State Building",
      "matching_name": "Empire State Building",
      "highlighted_name": "Empire State Building",
      "description": "20 West 34th Street, New York City, New York 10118, United States of America",
      "result_type": [
        "poi"
      ],
      "language": "en",
      "action": {
        "endpoint": "retrieve",
        "method": "POST",
        "body": {
          "id": "abc123"
        },
        "multi_retrievable": true
      },
      "coordinates": "-73.985703,40.748402",
      "maki": "marker",
      "category": [
        "historic site",
        "tourist attraction",
        "monument",
        "viewpoint"
      ],
      "internal_id": "example internal id",
      "external_ids": {
        "mbx_poi": "0ad30d457a8755215c6de72a9f90e2320bb911283a32358b70b1b80ce51da099",
        "foursquare": "43695300f964a5208c291fe3",
        "federated": "poi.0ad30d457a8755215c6de72a9f90e2320bb911283a32358b70b1b80ce51da099",
        "tripadvisor": "104365"
      },
      "mapbox_id": "CkIKQDBhZDMwZDQ1N2E4NzU1MjE1YzZkZTcyYTlmOTBlMjMyMGJiOTExMjgzYTMyMzU4YjcwYjFiODBjZTUxZGEwOTk=",
      "context": [
        {
          "layer": "address",
          "localized_layer": "address",
          "name": "20 West 34th Street, New York City, NY 10001"
        },
        {
          "layer": "street",
          "localized_layer": "street",
          "name": "west 34th street"
        },
        {
          "layer": "postcode",
          "localized_layer": "postcode",
          "name": "10118"
        },
        {
          "layer": "neighborhood",
          "localized_layer": "neighborhood",
          "name": "Koreatown"
        },
        {
          "layer": "place",
          "localized_layer": "place",
          "name": "New York City"
        },
        {
          "layer": "region",
          "localized_layer": "region",
          "name": "New York"
        },
        {
          "layer": "country",
          "localized_layer": "country",
          "name": "United States of America"
        }
      ],
      "metadata": {
        "iso_3166_1": "US",
        "iso_3166_2": "US-NY"
      }
    }
  ],
  "attribution": "© 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
  "version": "4:36ab3a1922e482256ec7ebc7069bb94f805bf5ca",
  "response_uuid": "958dc02c-fb82-4b6c-9732-4d307fb66521"
}

{
  "suggestions": [{
    "feature_name": "〒105-0004 東京都港区新橋1丁目10番1号",
    "matching_name": "〒105-0004 東京都港区新橋1丁目10番1号",
    "description": "",
    "result_type": [
      "address"
    ],
    "language": "ja",
    "action": {
      "endpoint": "retrieve",
      "method": "POST",
      "body": {
        "id": "abc123"
      },
      "multi_retrievable": false
    },
    "maki": "marker",
    "internal_id": "example internal id",
    "external_ids": {
      "service": "2wwRMXwBRYqRl13lTvTP"
    },
    "context": [{
        "layer": "block",
        "localized_layer": "block",
        "name": "10"
      },
      {
        "layer": "neighborhood",
        "localized_layer": "chome",
        "name": "1丁目"
      },
      {
        "layer": "locality",
        "localized_layer": "oaza",
        "name": "新橋"
      },
      {
        "layer": "place",
        "localized_layer": "city",
        "name": "港区"
      },
      {
        "layer": "region",
        "localized_layer": "prefecture",
        "name": "東京都"
      }
    ],
    "metadata": {
      "iso_3166_1": "jp",
      "iso_3166_2": "JP-13",
      "reading": {
        "ja_kana": "ﾄｳｷｮｳﾄﾐﾅﾄｸｼﾝﾊﾞｼ",
        "ja_latin": "toukyouto minatoku shinbashi"
      }
    }
  }],
  "attribution": "© 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
  "version": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "4b659949-c8c7-42d8-a541-6b427e5806cc"
}

  {
    "suggestions": [
        {
            "feature_name": "Coffee",
            "matching_name": "Coffee",
            "highlighted_name": "Coffee",
            "description": "Category",
            "result_type": [
                "category"
            ],
            "language": "en",
            "action": {
                "endpoint": "retrieve",
                "method": "POST",
                "body": {
                    "id": "KpVh_NjD8JvR8gjOV7tdqqycNzrC55xjG3BB7kNILsu3rmturQHGDUEMcGlaQY6Cu5cCcnz8RMVRo0lUnVnfC1CUdqgeSqTkreNyVjIR3hzFb7L62ZasnYQgFvbCi6guXA1Ai1NVyRYPDzLjy-JhOz2YHiwv8Wyk9Fi6q-od7XxXliDzmxAZ0zo7YgRgNKA-zTSo3__i3ogdrYW0uz1sKY4wMTw_0KKcuZ0WQhaNUh9Y3ZrAhaAkj6MvtDj6ArrxRsLm-jzC29pqRz3c5mg3LcODCTyqFU8D0-4zKD-1hTIQIgYkQHo_x_-BQO8J9skJTm67Io0UDUqixmxX1w7VhyqCEw8ezx8d3Rp3-ourQT6ZCmzTaDC11DrGnc4ZQ0ayR4AcrwbdKV0YnTKYh0KdMa2kxLjxcq5OP6mkep1jHlamJTAd7Qka5p5gw4pvkBf5kcT2c7Zkk6HDdJDDqVruSbElBRRyLYhynYvoFGYrDGGjAQELlK7xLnMBETewCEDpUmshnjEXeI-gwK9ZtBm05cYiMi8BEYiYuUrGVu-VRcUqBoh8-rbBNoYxnHgGZnmIeDVX6iRAqqLECuKW1lzIdYFCtEYUc1HtNT8ZftaL96-CtpNHv9mf0STW68J5e3dU_WP_VVIx4lLBZeflVAb2ICVL99zjskbrXO9CYTBx9WOWtc0fvIu1GSIxltpIu3HXlumayk2Y7PEAw1tvExzfdvYqHNboFCLRe4XvP196fcup7_3mZ6ndGECkq0SdAfhiUIScWNSOu3FDM-R7Cpk4KKT2nxibzmwDuzEzwqeam49S2FhU7p3miMAQGcmhhgqwbhDJ6hqO2m3WGtFCtXvdZXX15yoT7hme29UXrIHOFGq9Qs0ZHo9tcnfUHQnET80Hi6otebeFDpp6S6B9qgY442FtX0gzZCM0VuCo4u-SZRgy86YwKjGmgqs1nqrta46hhpajdnXb5AGBiemHmx6URWC__QKflpt4BxiIyRgzkJMLYDhnktczNJakugWQThwrUm1NrmBogTPJFlTl"
                },
                "multi_retrievable": false
            },
            "maki": "cafe",
            "category": [
                "Coffee"
            ],
            "internal_id": "42CAgOTEktT0_KJKAA==.42eAgMSCTN2C_Ezd4tSisszkVAA=.Y2OAgOT8tLTUVAA=",
            "external_ids": {
                "federated": "category.coffee"
            }            
        }
    ],
    "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
    "version": "5:541dd5c3358c4070719c266470cfb8430d72dd24",
    "response_uuid": "da631e7b-75fd-4dc3-9a1e-4915b2c16a29"
}

Session Phase 2: Retrieve a suggested feature

After one or more calls to the /suggest endpoint, you will use the information contained in the response's action block to retrieve detailed information about the feature, including coordinates. Using this endpoint requires no knowledge of what the possible parameters to pass are. Instead, you must pass information in the action block returned from the call to /suggest to this endpoint.

While a retrieve for a place or address will return details for a single result, a retrieve on a category result will return up to limit POI belonging to that category.

Example request: Retrieve a suggested feature

POST /search/v1/retrieve?session_token=[GENERATED-UUID]&access_token=YOUR_MAPBOX_ACCESS_TOKEN

Example request body:

{
  "id": "12345"
}

Response: Retrieve details for a suggestion

The /retrieve endpoint returns a GeoJSON FeatureCollection. In the case of a category selection, /retrieve will return an array of GeoJSON features.

Each feature in the response body contains the following properties:

Example responses: Retrieve a suggested feature

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          5.049746,
          51.650652
        ],
        "type": "Point"
      },
      "properties": {
        "feature_name": "Efteling",
        "matching_name": "Efteling",
        "highlighted_name": "Efteling",
        "description": "Europalaan 1, 5171 RP Kaatsheuvel, Netherlands",
        "place_name": "Efteling, Europalaan 1, 5171 RP Kaatsheuvel, Netherlands",
        "id": "2xAyKYEBLMhwlZV-L0T3",
        "place_type": [
          "poi"
        ],
        "context": [
          {
            "layer": "address",
            "localized_layer": "address",
            "name": "Europalaan 1, 5171 KW Kaatsheuvel The Netherlands"
          },
          {
            "layer": "street",
            "localized_layer": "street",
            "name": "europalaan"
          },
          {
            "layer": "postcode",
            "localized_layer": "postcode",
            "name": "5171 RP"
          },
          {
            "layer": "neighborhood",
            "localized_layer": "neighborhood",
            "name": "De Klinkenpolder"
          },
          {
            "layer": "place",
            "localized_layer": "place",
            "name": "Kaatsheuvel"
          },
          {
            "layer": "country",
            "localized_layer": "country",
            "name": "Netherlands"
          }
        ],
        "maki": "marker",
        "poi_category": [
          "theme park",
          "entertainment"
        ],
        "internal_id": "example internal id",
        "external_ids": {
          "tripadvisor": "262610",
          "foursquare": "4a72b543f964a52041db1fe3",
          "federated": "poi.067e4e1ea55235c67f4601f56d2889ebf6c380220de994e902f33ab59dd988e1",
          "mbx_poi": "067e4e1ea55235c67f4601f56d2889ebf6c380220de994e902f33ab59dd988e1"
        },
        "mapbox_id": "CkIKQDA2N2U0ZTFlYTU1MjM1YzY3ZjQ2MDFmNTZkMjg4OWViZjZjMzgwMjIwZGU5OTRlOTAyZjMzYWI1OWRkOTg4ZTE=",
        "metadata": {
          "review_count": 7787,
          "phone": "+31 416 537 777",
          "website": "http://www.efteling.com/",
          "average_rating": 4.5,
          "detailed_description": "Discover Holland's hidden gem. Efteling is a unique theme park with a fairytale atmosphere, natural surroundings and a wide range of thrilling and enchanting attractions, making it the ideal family short-break destination!",
          "primary_photo": [
            {
              "width": 50,
              "height": 50,
              "url": "https://media-cdn.tripadvisor.com/media/photo-t/12/5b/6f/3c/efteling-the-magic-land.jpg"
            },
            {
              "width": 150,
              "height": 150,
              "url": "https://media-cdn.tripadvisor.com/media/photo-l/12/5b/6f/3c/efteling-the-magic-land.jpg"
            },
            {
              "width": 250,
              "height": 188,
              "url": "https://media-cdn.tripadvisor.com/media/photo-f/12/5b/6f/3c/efteling-the-magic-land.jpg"
            },
            {
              "width": 550,
              "height": 413,
              "url": "https://media-cdn.tripadvisor.com/media/photo-s/12/5b/6f/3c/efteling-the-magic-land.jpg"
            },
            {
              "width": 960,
              "height": 720,
              "url": "https://media-cdn.tripadvisor.com/media/photo-o/12/5b/6f/3c/efteling-the-magic-land.jpg"
            }
          ],
          "open_hours": {
            "open_type": "Scheduled",
            "open_periods": [
              {
                "open": {
                  "day": 0,
                  "time": {
                    "hour": 11,
                    "minute": 0
                  }
                },
                "close": {
                  "day": 0,
                  "time": {
                    "hour": 18,
                    "minute": 0
                  }
                }
              },
              {
                "open": {
                  "day": 1,
                  "time": {
                    "hour": 11,
                    "minute": 0
                  }
                },
                "close": {
                  "day": 1,
                  "time": {
                    "hour": 18,
                    "minute": 0
                  }
                }
              },
              {
                "open": {
                  "day": 2,
                  "time": {
                    "hour": 11,
                    "minute": 0
                  }
                },
                "close": {
                  "day": 2,
                  "time": {
                    "hour": 18,
                    "minute": 0
                  }
                }
              },
              {
                "open": {
                  "day": 3,
                  "time": {
                    "hour": 11,
                    "minute": 0
                  }
                },
                "close": {
                  "day": 3,
                  "time": {
                    "hour": 18,
                    "minute": 0
                  }
                }
              },
              {
                "open": {
                  "day": 4,
                  "time": {
                    "hour": 11,
                    "minute": 0
                  }
                },
                "close": {
                  "day": 4,
                  "time": {
                    "hour": 18,
                    "minute": 0
                  }
                }
              },
              {
                "open": {
                  "day": 5,
                  "time": {
                    "hour": 10,
                    "minute": 0
                  }
                },
                "close": {
                  "day": 5,
                  "time": {
                    "hour": 18,
                    "minute": 0
                  }
                }
              },
              {
                "open": {
                  "day": 6,
                  "time": {
                    "hour": 10,
                    "minute": 0
                  }
                },
                "close": {
                  "day": 6,
                  "time": {
                    "hour": 18,
                    "minute": 0
                  }
                }
              }
            ]
          },
          "iso_3166_1": "NL",
          "iso_3166_2": "NL-NB"
        }
      }
    }
  ],
  "attribution": "© 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
  "version": "4:36ab3a1922e482256ec7ebc7069bb94f805bf5ca",
  "response_uuid": "fcdd5da0-2bb2-48ac-bf73-8da68fffc5ac"
}

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "coordinates": [
        139.7596417,
        35.6675028
      ],
      "type": "Point"
    },
    "properties": {
      "feature_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "matching_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "description": "",
      "place_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "id": "2wwRMXwBRYqRl13lTvTP",
      "place_type": [
        "address"
      ],
      "context": [{
          "layer": "block",
          "localized_layer": "block",
          "name": "10"
        },
        {
          "layer": "chome",
          "localized_layer": "chome",
          "name": "1丁目"
        },
        {
          "layer": "oaza",
          "localized_layer": "oaza",
          "name": "新橋"
        },
        {
          "layer": "city",
          "localized_layer": "city",
          "name": "港区"
        },
        {
          "layer": "prefecture",
          "localized_layer": "prefecture",
          "name": "東京都"
        }
      ],
      "language": "ja",
      "maki": "marker",
      "internal_id": "example internal id",
      "external_ids": {
        "japan_address": "2wwRMXwBRYqRl13lTvTP"
      },
      "accuracy": "rooftop",
      "address": "〒105-0004 東京都港区新橋1丁目10番1号",
      "address_number": "1",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13",
        "reading": {
          "ja_kana": "ﾄｳｷｮｳﾄﾐﾅﾄｸｼﾝﾊﾞｼ",
          "ja_latin": "toukyouto minatoku shinbashi"
        }
      }
    }
  }],
  "attribution": "© 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
  "version": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "55491b50-f5df-4725-aeb1-3e8ed4a07b17"
}

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "coordinates": [
                    -6.6543203,
                    55.204344
                ],
                "type": "Point"
            },
            "properties": {
                "feature_name": "Koko",
                "matching_name": "Koko",
                "highlighted_name": "Koko",
                "description": "10 Castle Erin Road, Portrush, None, United Kingdom",
                "place_name": "Koko, 10 Castle Erin Road, Portrush, None, United Kingdom",
                "id": "zAK63YEBNHearXczfx0E",
                "place_type": [
                    "poi"
                ],
                "context": [
                    {
                        "layer": "address",
                        "localized_layer": "address",
                        "name": "10 Castle Erin Road, Portrush BT56 8DH, United Kingdom"
                    },
                    {
                        "layer": "street",
                        "localized_layer": "street",
                        "name": "Castle Erin Road"
                    },
                    {
                        "layer": "postcode",
                        "localized_layer": "postcode",
                        "name": "None"
                    },
                    {
                        "layer": "neighborhood",
                        "localized_layer": "neighborhood",
                        "name": "None"
                    },
                    {
                        "layer": "place",
                        "localized_layer": "place",
                        "name": "Portrush"
                    },
                    {
                        "layer": "country",
                        "localized_layer": "country",
                        "name": "United Kingdom"
                    }
                ],
                "maki": "restaurant",
                "poi_category": [
                    "food",
                    "food and drink",
                    "coffee shop",
                    "coffee",
                    "cafe"
                ],
                "internal_id": "Y2aAgIL8TAA=.42eAgMSCTN2C_Ezd4tSisszkVAA=.U2aAgLT80qLiwtLEolQ9U-NUy7QkAwsTS4vUNPNUC8tkI5OkZEMzAA==",
                "external_ids": {
                    "mbx_poi": "d290c111831b4b1bb441ca1f9c03775e7e0d787f69c670fdf66d5b036445f5a1",
                    "federated": "poi.d290c111831b4b1bb441ca1f9c03775e7e0d787f69c670fdf66d5b036445f5a1",
                    "foursquare": "53e9fb08498ef7e89c24bc16"
                },
                "mapbox_id": "CkIKQGQyOTBjMTExODMxYjRiMWJiNDQxY2ExZjljMDM3NzVlN2UwZDc4N2Y2OWM2NzBmZGY2NmQ1YjAzNjQ0NWY1YTE=",
                "metadata": {
                    "primary_photo": [],
                    "iso_3166_1": "GB",
                    "iso_3166_2": "GB-NIR"
                }
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "coordinates": [
                    -2.751394,
                    52.708212
                ],
                "type": "Point"
            },
            "properties": {
                "feature_name": "Aroma Tea & Coffee Merchants",
                "matching_name": "Aroma Tea & Coffee Merchants",
                "highlighted_name": "Aroma Tea & Coffee Merchants",
                "description": "8a St Marys Pl, Shrewsbury, SY1 1DZ, United Kingdom",
                "place_name": "Aroma Tea & Coffee Merchants, 8a St Marys Pl, Shrewsbury, SY1 1DZ, United Kingdom",
                "id": "oOgD3YEBNHearXczYB58",
                "place_type": [
                    "poi"
                ],
                "context": [
                    {
                        "layer": "address",
                        "localized_layer": "address",
                        "name": "8a St Marys Pl"
                    },
                    {
                        "layer": "street",
                        "localized_layer": "street",
                        "name": "st marys pl"
                    },
                    {
                        "layer": "postcode",
                        "localized_layer": "postcode",
                        "name": "SY1 1DZ"
                    },
                    {
                        "layer": "place",
                        "localized_layer": "place",
                        "name": "Shrewsbury"
                    },
                    {
                        "layer": "country",
                        "localized_layer": "country",
                        "name": "United Kingdom"
                    }
                ],
                "maki": "cafe",
                "poi_category": [
                    "coffee roaster",
                    "coffee",
                    "food and drink"
                ],
                "internal_id": "Y2aAgIL8TAA=.42eAgMSCTN2C_Ezd4tSisszkVAA=.U2aAgLT80qLiwtLEolQ9MwMTIxNTg1QT8yQL4zSzREPLtJQkkyQDAA==",
                "external_ids": {
                    "federated": "poi.a0d64973784b740fae2b89645e5e36ac818d46a3a58974057bfea54b58d0ff33",
                    "foursquare": "6042450e47b83f6a19fdb4b0",
                    "mbx_poi": "a0d64973784b740fae2b89645e5e36ac818d46a3a58974057bfea54b58d0ff33"
                },
                "mapbox_id": "CkIKQGEwZDY0OTczNzg0Yjc0MGZhZTJiODk2NDVlNWUzNmFjODE4ZDQ2YTNhNTg5NzQwNTdiZmVhNTRiNThkMGZmMzM=",
                "metadata": {
                    "primary_photo": [],
                    "iso_3166_1": "GB",
                    "iso_3166_2": "GB-ENG"
                }
            }
        }
    ],
    "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
    "version": "5:541dd5c3358c4070719c266470cfb8430d72dd24",
    "response_uuid": "26d4c339-91cc-474b-b417-48056ab38220"
}

Forward geocoding

Retrieve detailed information about a specific feature, including geographic coordinates, in response to a user query.

You can further refine the results of a query to this endpoint with the following optional parameters:

Example requests: Forward geocoding

$ curl "https://api.mapbox.com/search/v1/forward/34170%20Gannon%20Terrace?language=en&limit=1&proximity=-121.90662,37.42827&country=US&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

$ curl "https://api.mapbox.com/search/v1/forward/新橋一丁十番一号,東京都港区新橋1丁目10番1号?language=ja&limit=1&proximity=13.38333,52.51667&country=JP&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Permanent forward geocoding

The Mapbox Terms of Service state that all data returned by the /suggest, /retrieve, /forward, or /reverse endpoints is only available for temporary use. If your use case requires storing position data for place or address types, contact Mapbox sales. POI will not be included in permanent geocoding results. This is consistent with the Terms of Service for Mapbox Geocoding API calls made to the mapbox.places-permanent endpoint.

The /permanent/forward endpoint takes the same path and query parameters as the /forward endpoint.

Response: Forward geocoding

The response to a request to the /forward endpoint is a GeoJSON FeatureCollection.

Using the limit parameter, you can increase the maximum number of results up to 10. Pagination is not available, but this feature may be added in a later release. There is not an option to customize the order of search results.

Each feature in the response body contains the following properties:

Example responses: Forward geocoding

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          -122.05963,
          37.56153
        ],
        "type": "Point"
      },
      "properties": {
        "feature_name": "34170 Gannon Terrace",
        "matching_name": "34170 Gannon Terrace",
        "highlighted_name": "34170 Gannon Terrace",
        "description": "Fremont, California 94555, United States",
        "place_name": "34170 Gannon Terrace, Fremont, California 94555, United States",
        "id": "address.1556645983160292",
        "place_type": [
          "address"
        ],
        "context": [
          {
            "layer": "neighborhood.7327715941516860",
            "localized_layer": "neighborhood.7327715941516860",
            "name": "Ardenwood"
          },
          {
            "layer": "postcode.11243426117484610",
            "localized_layer": "postcode.11243426117484610",
            "name": "94555"
          },
          {
            "layer": "place.11532961120628200",
            "localized_layer": "place.11532961120628200",
            "name": "Fremont"
          },
          {
            "layer": "district.11187960009291250",
            "localized_layer": "district.11187960009291250",
            "name": "Alameda County"
          },
          {
            "layer": "region.9803118085738010",
            "localized_layer": "region.9803118085738010",
            "name": "California"
          },
          {
            "layer": "country.14135384517372290",
            "localized_layer": "country.14135384517372290",
            "name": "United States"
          }
        ],
        "language": "en",
        "maki": "marker",
        "internal_id": "example internal id",
        "external_ids": {
          "federated": "carmen.address.1556645983160292",
          "carmen": "address.1556645983160292"
        },
        "accuracy": "rooftop",
        "address_number": "34170",
        "metadata": {
          "iso_3166_1": "us",
          "iso_3166_2": "US-CA"
        },
        "routable_points": [
          {
            "name": "Address",
            "coordinates": [
              -122.059679,
              37.561366
            ]
          }
        ]
      }
    }
  ],
  "attribution": "© 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
  "version": "4:36ab3a1922e482256ec7ebc7069bb94f805bf5ca",
  "response_uuid": "b32870f4-fa52-48f5-98c4-2200bb13ce7c"
}

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "coordinates": [
        139.7596417,
        35.6675028
      ],
      "type": "Point"
    },
    "properties": {
      "feature_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "matching_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "description": "",
      "place_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "id": "2wwRMXwBRYqRl13lTvTP",
      "place_type": [
        "address"
      ],
      "context": [{
          "layer": "block",
          "localized_layer": "block",
          "name": "10"
        },
        {
          "layer": "chome",
          "localized_layer": "chome",
          "name": "1丁目"
        },
        {
          "layer": "oaza",
          "localized_layer": "oaza",
          "name": "新橋"
        },
        {
          "layer": "city",
          "localized_layer": "city",
          "name": "港区"
        },
        {
          "layer": "prefecture",
          "localized_layer": "prefecture",
          "name": "東京都"
        }
      ],
      "language": "ja",
      "maki": "marker",
      "internal_id": "example internal id",
      "external_ids": {
        "japan_address": "2wwRMXwBRYqRl13lTvTP"
      },
      "accuracy": "rooftop",
      "address": "〒105-0004 東京都港区新橋1丁目10番1号",
      "address_number": "1",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13",
        "reading": {
          "ja_kana": "ﾄｳｷｮｳﾄﾐﾅﾄｸｼﾝﾊﾞｼ",
          "ja_latin": "toukyouto minatoku shinbashi"
        }
      }
    }
  }],
  "attribution": "© 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
  "version": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "733725e4-3992-43e5-9cad-bac75698eb59"
}

Reverse geocoding

The /reverse endpoint allows you to look up a single pair of coordinates and returns the geographic feature or features that exist at that location.

You can further refine the results of a query to this endpoint with the following optional parameters:

Example requests: Reverse geocoding

$ curl "https://api.mapbox.com/search/v1/reverse/13.329048,52.51258?language=de&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

$ curl "https://api.mapbox.com/search/v1/reverse/139.58028,35.29556?language=ja&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Permanent reverse geocoding

The Mapbox Terms of Service state that all data returned by the /suggest, /retrieve, /forward, or /reverse endpoints is only available for temporary use. If your use case requires storing position data for address or place types, contact Mapbox sales. POI will not be included in permanent geocoding results. This is consistent with the Terms of Service for Mapbox Geocoding API calls made to the mapbox.places-permanent endpoint.

The /permanent/reverse endpoint takes the same path and query parameters as the /reverse endpoint.

Response: Reverse geocoding

The response to a request to the /reverse endpoint is a GeoJSON FeatureCollection.

Using the limit parameter, you can increase the maximum number of results up to 10. Pagination is not available, but this feature may be added in a later release. There is not an option to customize the order of search results.

Each feature in the response body contains the following properties:

Example responses: Reverse geocoding

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          13.3295589,
          52.5125463
        ],
        "type": "Point"
      },
      "properties": {
        "feature_name": "Straße Des 17. Juni 115",
        "matching_name": "Straße Des 17. Juni 115",
        "highlighted_name": "Straße Des 17. Juni 115",
        "description": "10623 Berlin, Deutschland",
        "place_name": "Straße Des 17. Juni 115, 10623 Berlin, Deutschland",
        "id": "address.3419053976491624",
        "place_type": [
          "address"
        ],
        "context": [
          {
            "layer": "postcode.5398366936640250",
            "localized_layer": "postcode.5398366936640250",
            "name": "10623"
          },
          {
            "layer": "locality.12210531181979940",
            "localized_layer": "locality.12210531181979940",
            "name": "Charlottenburg"
          },
          {
            "layer": "place.14094307404564380",
            "localized_layer": "place.14094307404564380",
            "name": "Berlin"
          },
          {
            "layer": "country.10814856728480410",
            "localized_layer": "country.10814856728480410",
            "name": "Deutschland"
          }
        ],
        "language": "de",
        "maki": "marker",
        "internal_id": "example internal id",
        "external_ids": {
          "federated": "carmen.address.3419053976491624",
          "carmen": "address.3419053976491624"
        },
        "accuracy": "rooftop",
        "address_number": "115",
        "metadata": {
          "iso_3166_1": "de"
        },
        "routable_points": [
          {
            "name": "Address",
            "coordinates": [
              13.32955240836938,
              52.51264818693428
            ]
          }
        ]
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          13.329777,
          52.512344
        ],
        "type": "Point"
      },
      "properties": {
        "feature_name": "Chemiegebäude C TU Berlin",
        "matching_name": "Chemiegebäude C TU Berlin",
        "highlighted_name": "Chemiegebäude C TU Berlin",
        "description": "Straße des 17. Juni 115, 10623 Berlin, Deutschland",
        "place_name": "Chemiegebäude C TU Berlin, Straße des 17. Juni 115, 10623 Berlin, Deutschland",
        "id": "ZHtfKIEBLMhwlZV-fxwF",
        "place_type": [
          "poi"
        ],
        "context": [
          {
            "layer": "address",
            "localized_layer": "address",
            "name": "Straße des 17. Juni 115"
          },
          {
            "layer": "street",
            "localized_layer": "street",
            "name": "straße des 17 juni"
          },
          {
            "layer": "postcode",
            "localized_layer": "postcode",
            "name": "10623"
          },
          {
            "layer": "neighborhood",
            "localized_layer": "neighborhood",
            "name": "Berlin-10623"
          },
          {
            "layer": "place",
            "localized_layer": "place",
            "name": "Berlin"
          },
          {
            "layer": "country",
            "localized_layer": "country",
            "name": "Deutschland"
          }
        ],
        "maki": "marker",
        "poi_category": [
          "universitätsgebäude"
        ],
        "internal_id": "example internal id",
        "external_ids": {
          "federated": "poi.cf57c7f9cb1ef13109b9110018d46716dcfc8b1dc835f541e1aece69f283a8f7",
          "foursquare": "4d3569c6329e54812c70ca1d",
          "mbx_poi": "cf57c7f9cb1ef13109b9110018d46716dcfc8b1dc835f541e1aece69f283a8f7"
        },
        "mapbox_id": "CkIKQGNmNTdjN2Y5Y2IxZWYxMzEwOWI5MTEwMDE4ZDQ2NzE2ZGNmYzhiMWRjODM1ZjU0MWUxYWVjZTY5ZjI4M2E4Zjc=",
        "metadata": {
          "primary_photo": [],
          "iso_3166_1": "DE",
          "iso_3166_2": "DE-BE"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          13.3297794,
          52.5129985
        ],
        "type": "Point"
      },
      "properties": {
        "feature_name": "RWE-Effizienz",
        "matching_name": "RWE-Effizienz",
        "highlighted_name": "RWE-Effizienz",
        "description": "10623, Deutschland",
        "place_name": "RWE-Effizienz, 10623, Deutschland",
        "id": "3-aBKIEBLMhwlZV-ZzLV",
        "place_type": [
          "poi"
        ],
        "context": [
          {
            "layer": "postcode",
            "localized_layer": "postcode",
            "name": "10623"
          },
          {
            "layer": "country",
            "localized_layer": "country",
            "name": "Deutschland"
          }
        ],
        "maki": "marker",
        "poi_category": [
          "ladestation",
          "transport"
        ],
        "internal_id": "example internal id",
        "external_ids": {
          "mbx_poi": "bac9da3a9611cfaf6690c583e67b9d6f0534ff1189171ba4a57e5278284f6f86",
          "osm": "n1272542311",
          "federated": "poi.bac9da3a9611cfaf6690c583e67b9d6f0534ff1189171ba4a57e5278284f6f86"
        },
        "mapbox_id": "CkIKQGJhYzlkYTNhOTYxMWNmYWY2NjkwYzU4M2U2N2I5ZDZmMDUzNGZmMTE4OTE3MWJhNGE1N2U1Mjc4Mjg0ZjZmODY=",
        "metadata": {
          "primary_photo": [],
          "iso_3166_1": "DE",
          "iso_3166_2": "DE-BE"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          13.329943,
          52.512203
        ],
        "type": "Point"
      },
      "properties": {
        "feature_name": "INI Chemie TU Berlin",
        "matching_name": "INI Chemie TU Berlin",
        "highlighted_name": "INI Chemie TU Berlin",
        "description": "Straße des 17. Juni 115, 10623 Berlin, Deutschland",
        "place_name": "INI Chemie TU Berlin, Straße des 17. Juni 115, 10623 Berlin, Deutschland",
        "id": "z_QpKYEBLMhwlZV-Lx1H",
        "place_type": [
          "poi"
        ],
        "context": [
          {
            "layer": "address",
            "localized_layer": "address",
            "name": "Straße des 17. Juni 115"
          },
          {
            "layer": "street",
            "localized_layer": "street",
            "name": "straße des 17 juni"
          },
          {
            "layer": "postcode",
            "localized_layer": "postcode",
            "name": "10623"
          },
          {
            "layer": "neighborhood",
            "localized_layer": "neighborhood",
            "name": "Berlin-10623"
          },
          {
            "layer": "place",
            "localized_layer": "place",
            "name": "Berlin"
          },
          {
            "layer": "country",
            "localized_layer": "country",
            "name": "Deutschland"
          }
        ],
        "maki": "marker",
        "poi_category": [
          "universitätsgebäude"
        ],
        "internal_id": "example internal id",
        "external_ids": {
          "foursquare": "5166e725e4b0532deebdf0b6",
          "federated": "poi.eafb7426dd4209ee679236576265a9b2a1374aa784f2fb8e690f680abbad6a70",
          "mbx_poi": "eafb7426dd4209ee679236576265a9b2a1374aa784f2fb8e690f680abbad6a70"
        },
        "mapbox_id": "CkIKQGVhZmI3NDI2ZGQ0MjA5ZWU2NzkyMzY1NzYyNjVhOWIyYTEzNzRhYTc4NGYyZmI4ZTY5MGY2ODBhYmJhZDZhNzA=",
        "metadata": {
          "primary_photo": [],
          "iso_3166_1": "DE",
          "iso_3166_2": "DE-BE"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          13.327865,
          52.512276
        ],
        "type": "Point"
      },
      "properties": {
        "feature_name": "Fachbereich Logistik",
        "matching_name": "Fachbereich Logistik",
        "highlighted_name": "Fachbereich Logistik",
        "description": "Straße des 17. Juni 135, 10623 Berlin, Deutschland",
        "place_name": "Fachbereich Logistik, Straße des 17. Juni 135, 10623 Berlin, Deutschland",
        "id": "pQnqJ4EBLMhwlZV-Ik2S",
        "place_type": [
          "poi"
        ],
        "context": [
          {
            "layer": "address",
            "localized_layer": "address",
            "name": "Straße des 17. Juni 135"
          },
          {
            "layer": "street",
            "localized_layer": "street",
            "name": "straße des 17 juni"
          },
          {
            "layer": "postcode",
            "localized_layer": "postcode",
            "name": "10623"
          },
          {
            "layer": "neighborhood",
            "localized_layer": "neighborhood",
            "name": "Berlin-10623"
          },
          {
            "layer": "place",
            "localized_layer": "place",
            "name": "Berlin"
          },
          {
            "layer": "country",
            "localized_layer": "country",
            "name": "Deutschland"
          }
        ],
        "maki": "marker",
        "poi_category": [
          "büro"
        ],
        "internal_id": "example internal id",
        "external_ids": {
          "foursquare": "5475a534498e3f576fa1b5d9",
          "federated": "poi.0918e824a5229b4682881bb3383d8f192a059709db2c2659e5b93fa89f50f455",
          "mbx_poi": "0918e824a5229b4682881bb3383d8f192a059709db2c2659e5b93fa89f50f455"
        },
        "mapbox_id": "CkIKQDA5MThlODI0YTUyMjliNDY4Mjg4MWJiMzM4M2Q4ZjE5MmEwNTk3MDlkYjJjMjY1OWU1YjkzZmE4OWY1MGY0NTU=",
        "metadata": {
          "primary_photo": [],
          "iso_3166_1": "DE",
          "iso_3166_2": "DE-BE"
        }
      }
    }
  ],
  "attribution": "© 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
  "version": "4:36ab3a1922e482256ec7ebc7069bb94f805bf5ca",
  "response_uuid": "f728ec84-5599-4ac5-aee3-dda48d970e74"
}

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "coordinates": [
        139.58041388935513,
        35.29559166696336
      ],
      "type": "Point"
    },
    "properties": {
      "feature_name": "逗子5丁目2番",
      "matching_name": "逗子5丁目2番",
      "description": "日本, 神奈川県逗子市逗子5丁目2番16",
      "place_name": "日本, 神奈川県逗子市逗子5丁目2番16",
      "id": "address.141324126",
      "place_type": [
        "address"
      ],
      "context": [{
          "layer": "postcode.15947689941269040",
          "localized_layer": "postcode.15947689941269040",
          "name": "249-0006"
        },
        {
          "layer": "place.9212495244633840",
          "localized_layer": "place.9212495244633840",
          "name": "逗子市"
        },
        {
          "layer": "region.3991212366959510",
          "localized_layer": "region.3991212366959510",
          "name": "神奈川県"
        },
        {
          "layer": "country.9827633378530190",
          "localized_layer": "country.9827633378530190",
          "name": "日本"
        }
      ],
      "language": "ja",
      "maki": "marker",
      "internal_id": "example internal id",
      "external_ids": {
        "carmen": "address.141324126",
        "federated": "carmen.address.141324126"
      },
      "accuracy": "point",
      "address_number": "16",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-14"
      },
      "routable_points": []
    }
  }],
  "attribution": "© 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
  "version": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "29135029-2b4d-477e-bc30-67303b12ddad"
}

Category Hot Button

Retrieve detailed information about a specific feature, including geographic coordinates, in response to a user query.

You can further refine the results of a query to this endpoint with the following optional parameters:

Example requests: Category Hot Button Search

$ curl "https://api.mapbox.com/search/v1/category/coffee?language=en&limit=5&proximity=-78.476678,38.029306&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Category Hot Button search

The response to a request to the /category/{category_id} endpoint is a GeoJSON FeatureCollection.

Using the limit parameter, you can increase the maximum number of results up to 100. Pagination is not available, but this feature may be added in a later release. There is not an option to customize the order of search results.

Each feature in the response body contains the following properties:

Example responses: Category Hot Button

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "coordinates": [
                    -78.478664,
                    38.030008
                ],
                "type": "Point"
            },
            "properties": {
                "feature_name": "Java Java Cafe",
                "matching_name": "Java Java Cafe",
                "highlighted_name": "Java Java Cafe",
                "description": "421 E Main St, Virginia 22902, United States of America",
                "place_name": "Java Java Cafe, 421 E Main St, Virginia 22902, United States of America",
                "id": "s7_YsYEBLMhwlZV-mB3E",
                "place_type": [
                    "poi"
                ],
                "context": [
                    {
                        "layer": "address",
                        "localized_layer": "address",
                        "name": "421 E Main St"
                    },
                    {
                        "layer": "street",
                        "localized_layer": "street",
                        "name": "e main st"
                    },
                    {
                        "layer": "postcode",
                        "localized_layer": "postcode",
                        "name": "22902"
                    },
                    {
                        "layer": "neighborhood",
                        "localized_layer": "neighborhood",
                        "name": "North Downtown"
                    },
                    {
                        "layer": "region",
                        "localized_layer": "region",
                        "name": "Virginia"
                    },
                    {
                        "layer": "country",
                        "localized_layer": "country",
                        "name": "United States of America"
                    }
                ],
                "maki": "restaurant",
                "poi_category": [
                    "food",
                    "food and drink",
                    "coffee shop",
                    "coffee",
                    "cafe"
                ],
                "internal_id": "Y2aAgIL8TAA=.42eAgMSCTN2C_Ezd4tSisszkVAA=.U2aAgLT80qLiwtLEolQ9kyRzc0MTS7M0SzOTRFMjA1ND8ySj1FRjAA==",
                "external_ids": {
                    "federated": "poi.52dc76305c4b719dd2470a6ed92829eecd98ee4d990d2cc5cc486fc13959095b",
                    "safegraph": "233-222@63g-bf8-x5z",
                    "mbx_poi": "52dc76305c4b719dd2470a6ed92829eecd98ee4d990d2cc5cc486fc13959095b",
                    "foursquare": "4b771496f964a520517b2ee3"
                },
                "mapbox_id": "CkIKQDUyZGM3NjMwNWM0YjcxOWRkMjQ3MGE2ZWQ5MjgyOWVlY2Q5OGVlNGQ5OTBkMmNjNWNjNDg2ZmMxMzk1OTA5NWI=",
                "metadata": {
                    "primary_photo": [],
                    "iso_3166_1": "US",
                    "iso_3166_2": "US-VA"
                }
            }
        }
    ],
    "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
    "version": "5:541dd5c3358c4070719c266470cfb8430d72dd24",
    "response_uuid": "00000000-0000-0000-0000-000000000000"
}

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          139.761493,
          35.676906
        ],
        "type": "Point"
      },
      "properties": {
        "feature_name": "Patagonia",
        "matching_name": "Patagonia",
        "highlighted_name": "Patagonia",
        "description": "東京都千代田区丸の内３－１－１",
        "place_name": "Patagonia, 東京都千代田区丸の内３－１－１",
        "id": "z9fWqYEBJNOCvqh5yCj1",
        "place_type": [
          "poi"
        ],
        "context": [
          {
            "layer": "address",
            "localized_layer": "address",
            "name": "東京都千代田区丸の内３－１－１"
          },
          {
            "layer": "street",
            "localized_layer": "street",
            "name": "丸の内３-１-１"
          },
          {
            "layer": "postcode",
            "localized_layer": "postcode",
            "name": "100-0005"
          }
        ],
        "maki": "shop",
        "poi_category": [
          "ショップ>スポーツ用品",
          "ショップ"
        ],
        "brand": [],
        "internal_id": "Y2aAgIL8TAA=.42eAgMSCTN2C_Ezd4tSisszkVAA=.U2aAgLT80qLiwtLEolQ9UyMjU_PkJDNDwxQjg0TLtLRUA0vTpNREAA==",
        "external_ids": {
          "foursquare": "52257cb611d20a9ffe095bea",
          "mbx_poi": "55481c53b3b1d1a32563260c74e9ed3579989c092a840d4b2eeef6236d813af8",
          "federated": "poi.55481c53b3b1d1a32563260c74e9ed3579989c092a840d4b2eeef6236d813af8"
        },
        "mapbox_id": "CkIKQDU1NDgxYzUzYjNiMWQxYTMyNTYzMjYwYzc0ZTllZDM1Nzk5ODljMDkyYTg0MGQ0YjJlZWVmNjIzNmQ4MTNhZjg=",
        "metadata": {
          "iso_3166_1": "JP",
          "iso_3166_2": "JP-13"
        }
      }
    }
  ],
  "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service. (https://www.mapbox.com/about/maps/)",
  "version": "17:20edfdc9a9545e04146c74ba4f0faf9cce5b8b57",
  "response_uuid": "405be5a0-84e8-4b8e-93c2-318c30f74720"
}

List Categories

Retrieve the list of canonical category IDs for category hot button search.

You can further refine the results of a query to this endpoint with the following optional parameters:

Example requests: Category List

$ curl "https://api.mapbox.com/search/v1/list/category?language=en&limit=10000&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Category List

The response to a request to the /list/category/ endpoint is an array of categories..

Using the limit parameter, you can increase the maximum number of results up to 10000. Pagination is not available, but this feature may be added in a later release. There is not an option to customize the order of search results.

Each category in the response body contains the following properties:

Search API errors

Search API restrictions and limits

• The default rate limit for the Mapbox Search API is 600 requests per minute. If you require a higher rate limit, contact Mapbox Sales.
• Calls to the Search API's /suggest and /retrieve endpoints must include a session_token parameter. Each API call in a search session counts individually against the rate limit. For example, 10 sequential calls to /suggest with the same session_token and one call to /retrieve are 11 requests per the rate limit, but are billed as belonging to a single session. See more about how the Search API is billed in the Session-based pricing section of this documentation.

Search API pricing

Usage of the Search API is billed either by search session or by API call, depending on the Search API endpoints that you use. During the beta phase's limited release in Japan, details about the number of requests included in the free tier and the cost per request beyond what is included in the free tier are available on the Japanese-language pricing page.

Session-based pricing

The Search API's /suggest and /retrieve endpoints must include a session_token parameter. The session_token parameter is used to group a series of requests together into one session for billing purposes.

A session ends after the following actions:

• A call is made to /suggest followed by a call to /retrieve with a common session_token.
• 50 successive calls are made to /suggest with a common session_token but are not followed by a call to /retrieve.
• A call is made to /suggest and 60 minutes pass without being followed by a call to /retrieve.

For more specific details on session pricing, contact Mapbox sales.

Per-call pricing

Calls to the Search API's /forward, /permanent/forward, /reverse, and /permanent/reverse endpoints are billed by API calls. For more details on how calls to these endpoints are billed, see the Japanese-language pricing page.