Search service

The Mapbox Search service is composed of the following APIs:

    Geocoding

    The Mapbox Geocoding API does two things: forward geocoding and reverse geocoding.

    Forward geocoding converts location text into geographic coordinates, turning 2 Lincoln Memorial Circle NW into -77.050,38.889.

    Reverse geocoding turns geographic coordinates into place names, turning -77.050, 38.889 into 2 Lincoln Memorial Circle NW. These location names can vary in specificity, from individual addresses to states and countries that contain the given coordinates.

    For more background information on the Mapbox Geocoding API and how it works, see the How geocoding works guide.

    Endpoints

    The geocoding API includes two different endpoints: mapbox.places and mapbox.places-permanent.

    mapbox.places

    The mapbox-places endpoint is accessible to all geocoding customers. Requests to this endpoint must be triggered by user activity. Any results must be displayed on a Mapbox map and cannot be stored permanently, as described in Mapbox’s terms of service.

    mapbox.places-permanent

    The mapbox.places-permanent endpoint is accessible to Enterprise customers with a license for permanent geocodes. This endpoint allows for permanent storage of results and for batch geocoding.

    Note that the mapbox.places-permanent endpoint does not include POI (point-of-interest) features. The data available for other feature types may vary slightly compared to the data available in the mapbox.places endpoint.

    Data types

    Various types of geographic features are available in the Mapbox geocoder. Any type might appear as a top-level response, as context in a top-level response, or as a filtering option using the types parameter. Not all features are available or relevant in all parts of the world. New types are occasionally added as necessary to correctly capture global administrative hierarchies.

    The data types available in the geocoder, listed from the largest to the most granular, are:

    Data typeDescription
    countryGenerally recognized countries or, in some cases like Hong Kong, an area of quasi-national administrative status that has been given a designated country code under ISO 3166-1.
    regionTop-level sub-national administrative features, such as states in the United States or provinces in Canada or China.
    postcodePostal codes used in country-specific national addressing systems.
    districtFeatures that are smaller than top-level administrative features but typically larger than cities, in countries that use such an additional layer in postal addressing (for example, prefectures in China).
    placeTypically these are cities, villages, municipalities, etc. They’re usually features used in postal addressing, and are suitable for display in ambient end-user applications where current-location context is needed (for example, in weather displays).
    localityOfficial sub-city features present in countries where such an additional administrative layer is used in postal addressing, or where such features are commonly referred to in local parlance. Examples include city districts in Brazil and Chile and arrondissements in France.
    neighborhoodColloquial sub-city features often referred to in local parlance. Unlike locality features, these typically lack official status and may lack universally agreed-upon boundaries.
    addressIndividual residential or business addresses.
    poiPoints of interest. These include restaurants, stores, concert venues, parks, museums, etc.

    Forward geocoding

    get
    /geocoding/v5/{endpoint}/{search_text}.json

    The forward geocoding query type allows you to look up a single location by name and returns its geographic coordinates.

    Try forward geocoding in the Search Playground.

    Required parametersDescription
    endpointOne of mapbox.places or mapbox.places-permanent, as described in the Endpoints section.
    search_textThe feature you’re trying to look up. This could be an address, a point of interest name, a city name, etc. When searching for points if interest, it can also be a category name (for example, “coffee shop”). For information on categories, see the Point of interest category coverage section. The search text should be expressed as a URL-encoded UTF-8 string, and must not contain the semicolon character (either raw or URL-encoded). Your search text, once decoded, must consist of at most 20 words and numbers separated by spacing and punctuation, and at most 256 characters.

    You can further refine the results of a forward geocoding query with the following optional parameters:

    Optional parametersDescription
    autocompleteSpecify whether to return autocomplete results (true, default) or not (false). When autocomplete is enabled, results will be included that start with the requested string, rather than just responses that match it exactly. For example, a query for India might return both India and Indiana with autocomplete enabled, but only India if it’s disabled.
    bboxLimit results to only those contained within the supplied bounding box. Bounding boxes should be supplied as four numbers separated by commas, in minLon,minLat,maxLon,maxLat order. The bounding box cannot cross the 180th meridian.
    countryLimit results to one or more countries. Permitted values are ISO 3166 alpha 2 country codes separated by commas.
    fuzzyMatchSpecify whether the Geocoding API should attempt approximate, as well as exact, matching when performing searches (true, default), or whether it should opt out of this behavior and only attempt exact matching (false). For example, the default setting might return Washington, DC for a query of wahsington, even though the query was misspelled.
    languageSpecify the user’s language. This parameter controls the language of the text supplied in responses, and also affects result scoring, with results matching the user’s query in the requested language being preferred over results that match in another language. For example, an autocomplete query for things that start with Frank might return Frankfurt as the first result with an English (en) language parameter, but Frankreich (“France”) with a German (de) language parameter.

    Options are IETF language tags comprised of a mandatory ISO 639-1 language code and, optionally, one or more IETF subtags for country or script.

    More than one value can also be specified, separated by commas, for applications that need to display labels in multiple languages.

    For more information on which specific languages are supported, see the language coverage section.
    limitSpecify the maximum number of results to return. The default is 5 and the maximum supported is 10.
    proximityBias the response to favor results that are closer to this location, provided as two comma-separated coordinates in longitude,latitude order.
    routingSpecify whether to request additional metadata about the recommended navigation destination corresponding to the feature (true) or not (false, default). Only applicable for address features.

    For example, if routing=true the response could include data about a point on the road the feature fronts. Response features may include an array containing one or more routable points. Routable points cannot always be determined. Consuming applications should fall back to using the feature’s normal geometry for routing if a separate routable point is not returned.
    typesFilter results to include only a subset (one or more) of the available feature types. Options are country, region, postcode, district, place, locality, neighborhood, address, and poi. Multiple options can be comma-separated. Note that poi.landmark is a deprecated type that, while still supported, returns the same data as is returned using the poi type.

    For more information on the available types, see the data types section.

    Example request: Forward geocoding

    # A basic forward geocoding request
    # Find Los Angeles
    
    $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/Los%20Angeles.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Find a town called 'Chester' in a specific region
    # Add the proximity parameter with local coordinates
    # This ensures the town of Chester, New Jersey is in the results
    
    $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/chester.json?proximity=-74.70850,40.78375&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Specify types=country to search only for countries named Georgia
    # Results will exclude the American state of Georgia
    
    $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/georgia.json?types=country&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Search for "Starbucks" in Washington, D.C.
    # Use a bounding box to limit results to within the district
    
    $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/starbucks.json?bbox=-77.083056,38.908611,-76.997778,38.959167&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Limit the results to 2 results using the limit option
    # Even though there are many possible matches
    # for "Washington", this query will only return 2 results.
    
    $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/Washington.json?limit=2&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application seamlessly. The following SDKs are available for this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Forward geocoding

    The API response for a forward geocoding query returns a GeoJSON feature collection in Mapbox Geocoding Response format. For more details on how a response from the Geocoding API is formatted, see the Geocoding API response object section.

    Reverse geocoding

    get
    /geocoding/v5/{endpoint}/{longitude},{latitude}.json

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

    Batch geocoding is only available with an Enterprise plan. For other plan levels, one geocode is permitted per request.

    Try reverse geocoding in the Search Playground.

    Required parametersDescription
    endpointOne of mapbox.places or mapbox.places-permanent, as described in the Endpoints section.
    longitude,latitudeA longitude,latitude pair that specifies the location being queried.

    You can further refine the results of a reverse geocoding query with the following optional parameters:

    Optional parametersDescription
    countryLimit results to one or more countries. Permitted values are ISO 3166 alpha 2 country codes separated by commas.
    languageSpecify the user’s language. This parameter controls the language of the text supplied in responses.

    Options are IETF language tags comprised of a mandatory ISO 639-1 language code and, optionally, one or more IETF subtags for country or script.

    More than one value can also be specified, separated by commas, for applications that need to display labels in multiple languages.

    For more information on which specific languages are supported, see the language coverage section.
    limitSpecify the maximum number of results to return. The default is 1 and the maximum supported is 10.

    The default behavior in reverse geocoding is to return at most one feature at each of the multiple levels of the administrative hierarchy (for example, one address, one region, one country). Increasing the limit allows returning multiple features of the same type, but only for one type (for example, multiple address results). Consequently, setting limit to a higher-than-default value requires specifying exactly one types parameter.
    reverseModeDecides how results are sorted in a reverse geocoding query if multiple results are requested using a limit other than 1. Options are distance (default), which causes the closest feature to always be returned first, and score, which allows high-prominence features to be sorted higher than nearer, lower-prominence features.
    routingSpecify whether to request additional metadata about the recommended navigation destination corresponding to the feature (true) or not (false, default). Only applicable for address features.

    For example, if routing=true the response could include data about a point on the road the feature fronts. Response features may include an array containing one or more routable points. Routable points cannot always be determined. Consuming applications should fall back to using the feature’s normal geometry for routing if a separate routable point is not returned.
    typesFilter results to include only a subset (one or more) of the available feature types. Options are country, region, postcode, district, place, locality, neighborhood, address, and poi. Multiple options can be comma-separated. Note that poi.landmark is a deprecated type that, while still supported, returns the same data as is returned using the poi type.

    For more information on the available types, see the data types section.

    Example request: Reverse geocoding

    # A basic reverse geocoding request
    # Retrieve places near a specific location
    
    $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/-73.989,40.733.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Filter results to only include points of interest
    
    $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/-73.989,40.733.json?types=poi&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application seamlessly. The following SDKs are available for this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Reverse geocoding

    The API response for a reverse geocoding query returns a GeoJSON feature collection in Mapbox Geocoding Response format. For more details on how a response from the Geocoding API is formatted, see the Geocoding API response object section.

    Batch geocoding

    get
    /geocoding/v5/{endpoint}/{search_text_1};{search_text_2};{search_text_N}.json

    The batch geocoding query type allows you to have multiple forward or reverse geocoding queries in a single request. You must have an Enterprise plan to use batch geocoding, and it is only available using the mapbox.places-permanent endpoint. On all other plan levels, one geocode is permitted per request.

    Batch geocoding requests are formatted similarly to ordinary forward or reverse geocoding requests, but with multiple search queries one after another, separated by semicolons. Each query should be URL encoded, but the ; character should not be encoded and should be included verbatim.

    A batch forward geocoding request can be made using an HTTP GET request:

    https://api.mapbox.com/geocoding/v5/mapbox.places-permanent/{search_text_1};{search_text_2}[;{search_text_N};...].json?parameters
    

    A batch reverse geocoding request can be made using an HTTP GET request:

    https://api.mapbox.com/geocoding/v5/mapbox.places-permanent/{lon_1},{lat_1};{lon_2},{lat_2}[;{lon_N},{lat_N};...].json?parameters
    
    Required parametersDescription
    search_text_NFor batch forward queries. The features to look up (addresses, point of interest names, city names, etc.). They should be expressed as URL-encoded UTF-8 strings, and must not contain the semicolon character (either raw or URL-encoded), as this is the delimiter between search items. Each search text, once decoded, must consist of at most 20 words and numbers separated by spacing and punctuation, and at most 256 characters. You may supply at most 50 search texts within one request.
    {lon_N},{lat_N}For batch reverse queries. The longitude and latitude, respectively, of the locations being queried. You may supply at most 50 longitude-latitude coordinate pairs within one request.
    access_tokenAll geocoding requests must include an access token.

    For batch forward queries, you may use any optional parameters that are available for single forward queries, and they will apply to all search texts. Likewise, for reverse queries, you may use any optional parameters that apply to single reverse queries.

    Example request: Batch geocoding

    $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places-permanent/20001;20009;22209.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    

    Response: Batch geocoding

    The response from batch geocoding query is an array of results in GeoJSON feature collection format.

    [
      <response for 1st query> { }
      <response for 2nd query> { }
      ...
    ]
    

    Details on the format and properties of Geocoding API responses can be found in the response object section.

    Geocoding response object

    The response to a Geocoding API request is an object that contains the following properties:

    PropertyDescription
    type"FeatureCollection", a GeoJSON type from the GeoJSON specification.
    queryForward geocodes: An array of space and punctuation-separated strings from the original query.
    Reverse geocodes: An array containing the coordinates being queried.
    featuresAn array of feature objects.
    Forward geocodes: Returned features are ordered by relevance.
    Reverse geocodes: Returned features are ordered by index hierarchy, from most specific features to least specific features that overlap the queried coordinates.
    attributionA string that attributes the results of the Mapbox Geocoding API to Mapbox.

    Mapbox's geocoding data is constantly being updated and improved. This means that the values of properties in the response object are not guaranteed and may change within the same version of the API. Properties may be added to, but will not be removed from, the response within the same API version.

    Each feature object in the features array may have the properties described below:

    PropertyDescription
    idA feature ID in the format {type}.{id} where {type} is the lowest hierarchy feature in the place_type field. The {id} suffix of the feature ID is unstable and may change within versions.
    type"Feature", a GeoJSON type from the GeoJSON specification.
    place_typeAn array of feature types describing the feature. Options are country, region, postcode, district, place, locality, neighborhood, address, and poi. Most features have only one type, but if the feature has multiple types, all applicable types will be listed in the array. (For example, Vatican City is a country, region, and place.)
    relevanceA score from 0 (least relevant) to 1 (most relevant) that measures the textual match of each returned feature to the query. You can use the relevance property to remove results that don’t fully match the query.
    address
    (optional)
    A string of the house number for the returned address feature. Note that unlike the address property for poi features, this property is outside the properties object.
    propertiesAn object describing the feature. The properties object may change with data improvements. Your implementation should check for the presence of these values in a response before it attempts to use them.
    properties.accuracy
    (optional)
    A point accuracy metric for the returned address feature. Can be one of rooftop, parcel, point, interpolated, intersection, street. Note that this list is subject to change. See below for details
    properties.address
    (optional)
    A string of the full street address for the returned poi feature. Note that unlike the address property for address features, this property is inside the properties object.
    properties.category
    (optional)
    A string of comma-separated categories for the returned poi feature.
    properties.maki
    (optional)
    The name of a suggested Maki icon to visualize a poi feature based on its category.
    properties.landmark
    (optional)
    Describes whether or not the feature is in the poi.landmark data type. This data type is deprecated, and this property will be present on all poi features for backwards compatibility reasons but will always be true.
    properties.wikidata
    (optional)
    The Wikidata identifier for the returned feature.
    properties.short_code
    (optional)
    The ISO 3166-1 country and ISO 3166-2 region code for the returned feature.
    properties.tel
    (deprecated)
    A formatted string of the telephone number for the returned poi feature.
    textA string representing the feature in the requested language, if specified.
    place_nameA string representing the feature in the requested language, if specified, and its full result hierarchy.
    matching_text
    (optional)
    A string analogous to the text field that more closely matches the query than results in the specified language. For example, querying Köln, Germany with language set to English (en) might return a feature with the text Cologne and the matching_text Köln.
    matching_place_name
    (optional)
    A string analogous to the place_name field that more closely matches the query than results in the specified language. For example, querying Köln, Germany with language set to English (en) might return a feature with the place_name Cologne, Germany and a matching_place_name of Köln, North Rhine-Westphalia, Germany.
    text_{language}
    (optional)
    A string analogous to the text field that matches the query in the requested language. This field is only returned when multiple languages are requested using the language parameter, and will be present for each requested language.
    place_name_{language}
    (optional)
    A string analogous to the place_name field that matches the query in the requested language. This field is only returned when multiple languages are requested using the language parameter, and will be present for each requested language.
    language
    (optional)
    A string of the IETF language tag of the query’s primary language.
    language_{language}
    (optional)
    A string of the IETF language tag of the query’s fallback language. This field is only returned when multiple languages are requested using the language parameter, and will be present for each requested language.
    bboxA bounding box array in the form [minX,minY,maxX,maxY].
    centerThe coordinates of the feature’s center in the form [longitude,latitude]. This may be the literal centroid of the feature’s geometry, or the center of human activity within the feature (for example, the downtown area of a city).
    geometryAn object describing the spatial geometry of the returned feature.
    geometry.type"Point", a GeoJSON type from the GeoJSON specification.
    geometry.coordinatesAn array in the format [longitude,latitude] at the center of the specified bbox.
    geometry.interpolated
    (optional)
    If present, indicates that an address is interpolated along a road network. The geocoder can usually return exact address points, but if an address is not present the geocoder can use interpolated data as a fallback. In edge cases, interpolation may not be possible if surrounding address data is not present, in which case the next fallback will be the center point of the street feature itself.
    geometry.omitted
    (optional)
    If present, indicates an out-of-parity match. This occurs when an interpolated address is not in the expected range for the indicated side of the street.
    contextAn array representing the hierarchy of encompassing parent features. Each parent feature may include any of the above properties.
    routable_points
    (optional)
    An object with the routable points for the feature.
    routable_points.points
    (optional)
    An array of points in the form of [{ coordinates: [lon, lat] }], or null if no points were found.

    properties.accuracy

    AccuracyDescription
    rooftopResult is for a specific building/entrance
    parcelResult is derived from a parcel centroid
    point (default)Result is a known address point but has no specific accuracy
    interpolatedResult has been interpolated from an address range
    intersectionResult is for a block or intersection
    streetResult is a street centroid

    Example response: Forward geocoding

    {
        "type": "FeatureCollection",
        "query": [
            "825",
            "s",
            "milwaukee",
            "ave",
            "deerfield",
            "il",
            "60015"
        ],
        "features": [{
                "id": "address.4356035406756260",
                "type": "Feature",
                "place_type": [
                    "address"
                ],
                "relevance": 1,
                "properties": {},
                "text": "Milwaukee Ave",
                "place_name": "825 Milwaukee Ave, Deerfield, Illinois 60015, United States",
                "matching_text": "South Milwaukee Avenue",
                "matching_place_name": "825 South Milwaukee Avenue, Deerfield, Illinois 60015, United States",
                "center": [
                    -87.921434,
                    42.166602
                ],
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -87.921434,
                        42.166602
                    ],
                    "interpolated": true,
                    "omitted": true
                },
                "address": "825",
                "context": [{
                        "id": "neighborhood.287187",
                        "text": "Lake Cook Road"
                    },
                    {
                        "id": "postcode.13903677306297990",
                        "text": "60015"
                    },
                    {
                        "id": "place.5958304312090910",
                        "wikidata": "Q287895",
                        "text": "Deerfield"
                    },
                    {
                        "id": "region.3290978600358810",
                        "short_code": "US-IL",
                        "wikidata": "Q1204",
                        "text": "Illinois"
                    },
                    {
                        "id": "country.9053006287256050",
                        "short_code": "us",
                        "wikidata": "Q30",
                        "text": "United States"
                    }
                ]
            },
            {
                "id": "address.7464624790403620",
                "type": "Feature",
                "place_type": [
                    "address"
                ],
                "relevance": 0.5,
                "properties": {},
                "text": "Milwaukee Ave",
                "place_name": "825 Milwaukee Ave, Wheeling, Illinois 60090, United States",
                "matching_text": "South Milwaukee Avenue",
                "matching_place_name": "825 South Milwaukee Avenue, Wheeling, Illinois 60090, United States",
                "center": [
                    -87.910299,
                    42.144504
                ],
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -87.910299,
                        42.144504
                    ],
                    "interpolated": true
                },
                "address": "825",
                "context": [{
                        "id": "neighborhood.287187",
                        "text": "Lake Cook Road"
                    },
                    {
                        "id": "postcode.9418633295906190",
                        "text": "60090"
                    },
                    {
                        "id": "place.9902190947082220",
                        "wikidata": "Q935043",
                        "text": "Wheeling"
                    },
                    {
                        "id": "region.3290978600358810",
                        "short_code": "US-IL",
                        "wikidata": "Q1204",
                        "text": "Illinois"
                    },
                    {
                        "id": "country.9053006287256050",
                        "short_code": "us",
                        "wikidata": "Q30",
                        "text": "United States"
                    }
                ]
            },
            {
                "id": "address.6472754353404224",
                "type": "Feature",
                "place_type": [
                    "address"
                ],
                "relevance": 0.5,
                "properties": {},
                "text": "Milwaukee Avenue",
                "place_name": "825 Milwaukee Avenue, Glenview, Illinois 60025, United States",
                "matching_text": "South Milwaukee Avenue",
                "matching_place_name": "825 South Milwaukee Avenue, Glenview, Illinois 60025, United States",
                "center": [
                    -87.852677,
                    42.071152
                ],
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -87.852677,
                        42.071152
                    ]
                },
                "address": "825",
                "context": [{
                        "id": "neighborhood.275266",
                        "text": "Northfield Woods"
                    },
                    {
                        "id": "postcode.3787740186211610",
                        "text": "60025"
                    },
                    {
                        "id": "place.10211845459386970",
                        "wikidata": null,
                        "text": "Glenview"
                    },
                    {
                        "id": "region.3290978600358810",
                        "short_code": "US-IL",
                        "wikidata": "Q1204",
                        "text": "Illinois"
                    },
                    {
                        "id": "country.9053006287256050",
                        "short_code": "us",
                        "wikidata": "Q30",
                        "text": "United States"
                    }
                ]
            },
            {
                "id": "address.1225436500189372",
                "type": "Feature",
                "place_type": [
                    "address"
                ],
                "relevance": 0.5,
                "properties": {},
                "text": "Milwaukee Ave",
                "place_name": "825 Milwaukee Ave, Buffalo Grove, Illinois 60089, United States",
                "matching_text": "South Milwaukee Avenue",
                "matching_place_name": "825 South Milwaukee Avenue, Buffalo Grove, Illinois 60089, United States",
                "center": [
                    -87.917484,
                    42.158084
                ],
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -87.917484,
                        42.158084
                    ],
                    "interpolated": true
                },
                "address": "825",
                "context": [{
                        "id": "neighborhood.287187",
                        "text": "Lake Cook Road"
                    },
                    {
                        "id": "postcode.11727721238210580",
                        "text": "60089"
                    },
                    {
                        "id": "place.8589721255665070",
                        "wikidata": "Q967086",
                        "text": "Buffalo Grove"
                    },
                    {
                        "id": "region.3290978600358810",
                        "short_code": "US-IL",
                        "wikidata": "Q1204",
                        "text": "Illinois"
                    },
                    {
                        "id": "country.9053006287256050",
                        "short_code": "us",
                        "wikidata": "Q30",
                        "text": "United States"
                    }
                ]
            },
            {
                "id": "address.240107872738130",
                "type": "Feature",
                "place_type": [
                    "address"
                ],
                "relevance": 0.5,
                "properties": {},
                "text": "Milwaukee Avenue",
                "place_name": "825 Milwaukee Avenue, Wheeling, Illinois 60090, United States",
                "matching_text": "South Milwaukee Avenue",
                "matching_place_name": "825 South Milwaukee Avenue, Wheeling, Illinois 60090, United States",
                "center": [
                    -87.898319,
                    42.126289
                ],
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -87.898319,
                        42.126289
                    ],
                    "interpolated": true,
                    "omitted": true
                },
                "address": "825",
                "context": [{
                        "id": "neighborhood.287189",
                        "text": "Milwaukee Avenue"
                    },
                    {
                        "id": "postcode.9418633295906190",
                        "text": "60090"
                    },
                    {
                        "id": "place.9902190947082220",
                        "wikidata": "Q935043",
                        "text": "Wheeling"
                    },
                    {
                        "id": "region.3290978600358810",
                        "short_code": "US-IL",
                        "wikidata": "Q1204",
                        "text": "Illinois"
                    },
                    {
                        "id": "country.9053006287256050",
                        "short_code": "us",
                        "wikidata": "Q30",
                        "text": "United States"
                    }
                ]
            }
        ],
        "attribution": "NOTICE: © 2018 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/). This response and the information it contains may not be retained. POI(s) provided by Foursquare."
    }
    

    Language coverage

    Translation availability also varies by language and region. We provide the following tiers of language support:

    Global coverage

    These languages are almost always present for country, region, and prominent place features.

    Language
    de Germanen Englishfr French
    it Italiannl Dutch

    Local coverage

    These languages may lack global coverage but are almost always present for country, region, and prominent place features where they are widely used.

    Language
    ca Catalancs Czechfi Finnish
    he Hebrewhu Hungarianis Icelandic
    fi Finnishka Georgianja Japanese
    ko Koreanlv Latviannb Norwegian Bokmål
    pl Polishpt Portuguesesk Slovak
    sl Sloveniansr Serbianth Thai
    tl Tagalogzh-Hans Simplified Chinesezh-Hant Traditional Chinese

    Limited coverage

    These languages are sometimes present but coverage tends to be inconsistent or geographically constrained.

    Language
    ar Arabicbg (Bulgarian)bs (Bosnian)
    da (Danish)es Spanishid (Indonesian)
    kk Kazakhmn (Mongolian)sq Albanian
    ro (Romanian)sv (Swedish)tr Turkish
    zh (Chinese)

    Point of interest category coverage

    This feature is in preview.

    The Geocoding API's POI category search feature is constantly being updated, and the current list of POI categories is subject to change. Since this is the case, data may change and should not be considered canonical.

    POI category search supports forward geocoding requests of poi feature types in a queried category. Using the proximity query parameter with POI category search returns points of interest local to a provided location (for example, restaurants near a user). Any category that is returned in the properties.category property of the response object is supported.

    Expand to see a list of the most common POI categories:
    • advertising, marketing
    • airport
    • amusement park, theme park
    • assisted living service, assisted, assisted living, home
    • athletic field, sports field
    • bagel, donut
    • bar, alcohol
    • base, military
    • beach
    • beauty, hair, salon, barber
    • beer, wine, spirit, alcohol, booze
    • bicycle, bike, cycle
    • boating
    • bookstore, book shop
    • bowling, bowl, bowling alley
    • brewery, beer
    • bus station, bus stop, bus
    • campground, rv park
    • candy store, candy, candies, confectionary, chocolatier, chocolate
    • car rental, truck rental
    • car wash, detail, car detail, car wax
    • casinos, gaming
    • cemetery, graveyard, mausoleum
    • clothing, accessories, apparel
    • college, university
    • combat sports, boxing, martial arts, fighting
    • computer, electronic
    • contractor, repair
    • dance
    • day care, preschool, daycare, child care
    • department store, big box store, department
    • dog park
    • drug services, alcohol services, clinic
    • dry cleaning, laundry, dry cleaner, laundry service, laundromat
    • education, school
    • embassy, foreign
    • er, emergency room
    • fast food
    • fire stations, fire house, fire department
    • florist, flowers, flower shop
    • forest, woods
    • funeral service, funeral home
    • furniture, decor
    • garden
    • gas station, fuel, gas
    • gift, novelty
    • glasses, optical
    • government agency
    • gun range
    • home improvement, repairman, handyman, repair
    • hospital, clinic, medical center
    • hotel, motel
    • houseware, home goods
    • ice cream parlor, ice cream
    • insurance
    • jewelry, watches, accessories
    • juice bar, smoothie, juice
    • lake
    • landmark
    • legal, lawyer, law, law office
    • lodging
    • massage, masseuse
    • meat, seafood, butcher, deli
    • miniature golf, minigolf
    • mountain
    • museum
    • music, show venue, concert, concert hall
    • natural park
    • newsstand, newspaper, news, magazine
    • night club, disco
    • notary, notary public
    • nursery, garden, garden center
    • outdoors
    • painting, art
    • park
    • parking, parking lot
    • pet, petshop, dog, cat
    • pharmacy
    • photo, frame, framing
    • photography, photo service
    • physical therapy, rehabilitation
    • pizza, restaurant
    • police station, law enforcement
    • port, ferry
    • post office, mail
    • professional cleaning, cleaning
    • rail station, train station
    • real estate agent, realtor, real estate agency
    • rest area, rest stop, pitstop
    • restaurant
    • scuba diving, pool
    • shoes, apparel
    • shopping center, mall, shopping mall
    • spa
    • sporting good, sports store
    • storage, storage facility, storage lot
    • supermarket, groceries, grocery, market, super
    • swimming pool, pool, swim club
    • tailor
    • tattoo, tattooing
    • theater, movie theater, cinema
    • tour, travel agent
    • tourist information, services, tourism, information
    • toy, toy shop
    • utility companies, utilities, utility, public utility, electricity, natural gas, water, sewage, power company
    • vehicle maintenance, car maintenance, vehicle repair, car repair
    • winery, vineyard, wine tasting
    • zoo, aquarium, wildlife sanctuary

    Geocoding restrictions and limits

    Rate limits vary by plan level and are enforced per account. Each plan includes up to:

    Plan levelRate limitBatch geocodingStore results
    Pay-as-you-go600 requests per minute
    Commercial600 requests per minute
    Enterprise2,400+ requests per minute

    Exceeding the limits above will result in an HTTP 429 response. For information, see the rate limit headers section.