All docschevron-rightAPI Docschevron-rightarrow-leftSearchchevron-rightGeocoding V6 API

Geocoding V6 API

lightning
Geocoding v6 Public Preview

The Geocoding v6 endpoints are in Public Preview, and may be subject to minor, non-breaking changes.

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 SW into -77.050,38.889.

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

book
What's new in v6?
  • Structured Input allows queries to be separated into component parts for greater accuracy.
  • Smart Address Match makes the match_code object available in all responses for address-type features, and indicates how well a result corresponds to the submitted query.
  • Improved Batch geocoding sends up to 1000 queries of mixed-type in a single request. API rate limits still apply and each query will be counted as 1 request.
  • Expanded Japan coverage gives access to robust Japanese address search.
  • Features returned have a mapbox_id, a stable ID which can be used to retrieve the same feature in the future via a forward geocoding request.
book
Migrating from Geocoding v5
  • Permanent and temporary geocoding are no longer different endpoints, and are now set via an optional parameter. The default behavior for all endpoints is temporary geocoding.
  • Forward and reverse geocoding now have their own separate endpoints.
  • Batch geocoding now has it's own endpoint.
  • The geocoding v6 API no longer provides POI data (use the Search Box API for POI search).
  • Streets can now be returned as a feature type and be filtered for via the types parameter.
book
Geocoding from Snowflake

Snowflake users can do batch geocoding operations on data stored in their data warehouse. The Mapbox Snowflake Native App is available in the Snowflake Marketplace.

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

You may also use one of several wrapper libraries to integrate the Mapbox Geocoding API into an application instead of using it directly.

playground
Geocoding API playground

Try forward, reverse, and batch geocoding queries and see the results on a map.

chevron-right

Geographic Feature 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 geographic feature types listed from the largest to the most granular, are:

Feature TypeDescription
countryGenerally recognized countries or, in some cases like Hong Kong, an area of quasi-national administrative status that has 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.
streetStreet features which host one or more addresses
blockSpecial feature type reserved for Japanese addresses.
addressIndividual residential or business addresses.

Storing Geocoding Results

The Mapbox Geocoding API offers two types of result storage: Permanent and Temporary.

Temporary results are not allowed to be cached, while Permanent results are allowed to be cached and stored indefinitely.

Using Permanent storage with the Geocoding API requires that you have a valid credit card on file or an active enterprise contract.

By default, the geocoder will use Temporary geocoding. To use Permanent geocoding, set the optional permanent parameter to true.

Forward geocoding with search text input

get
https://api.mapbox.com/search/geocode/v6/forward?q={search_text}

The forward geocoding query type allows you to look up a location using a string of search text and returns its standardized address, geographic context, and coordinates.

Required parametersTypeDescription
qstringThe feature you’re trying to look up. This could be an address, a city name, etc. 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.

The accuracy of coordinates returned by a forward geocoding request can be affected by how the addresses in the query are formatted. Learn more about address formatting best practices in the Address geocoding format guide.
access_tokenstringAll geocoding requests must include an access token.

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

Optional parametersTypeDescription
permanentbooleanSpecify whether you intend to store the results of the query (true) or not (false, default).
autocompletebooleanSpecify 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 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.

When autocomplete is enabled, each user keystroke counts as one request to the Geocoding API. For example, a search for "Cali" would be reflected as four separate Geocoding API requests. To reduce the total requests sent, you can configure your application to only call the Geocoding API after a specific number of characters are typed.
bboxnumberLimit 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.
You can use the Location Helper to find a bounding box for use with this API.
countrystringLimit results to one or more countries. Permitted values are ISO 3166 alpha 2 country codes separated by commas.
formatstringSpecify the desired response format of results (geojson, default) or for backwards compatibility (v5).
languagestringSet the language of the text supplied in responses. 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. The first language in the list will be considered as the primary language and a response will be generated for it. For other languages, translations will be provided, see the translations section.

For more information on which specific languages are supported, see the language coverage section.
limitintegerSpecify the maximum number of results to return. The default is 5 and the maximum supported is 10.
proximitystringBias the response to favor results that are closer to this location. Provided as two comma-separated coordinates in longitude,latitude order, or the string ip to bias based on reverse IP lookup.
typesstringFilter results to include only a subset (one or more) of the available feature types. Options are country, region, postcode, district, place, locality, neighborhood, street, and address. Multiple options can be comma-separated.

For more information on the available types, see the data types section.
worldviewstringReturns features that are defined differently by audiences that belong to various regional, cultural, or political groups. Available worldviews are: ar,cn,in,jp,ma,ru,tr,us. If worldview is not set, the us worldview boundaries are returned by default.

For more information about using the worldview parameter, see the worldviews section.

Example requests: Forward geocoding with search text input

# A basic forward geocoding request
# Find Los Angeles

$ curl "https://api.mapbox.com/search/geocode/v6/forward?q=Los%20Angeles&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/search/geocode/v6/forward?q=chester&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/search/geocode/v6/forward?q=georgia&types=country&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Limit the results to two results using the limit option
# Even though there are many possible matches
# for "Washington", this query will only return two results.

$ curl "https://api.mapbox.com/search/geocode/v6/forward?q=Washington&limit=2&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Search for the Place feature "Kaaleng" in the Ilemi Triangle. Specifying the cn worldview will return the country value South Sudan. Not including leaving the worldview parameter would default to the us worldview and return the country value Kenya.

$ curl "https://api.mapbox.com/search/geocode/v6/forward?q=Kaaleng&worldview=cn&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Forward geocoding with search text input

See the Geocoding API response object section.

Forward geocoding with structured input

New in v6
get
https://api.mapbox.com/search/geocode/v6/forward?address_number={address_number}&street={street}&...

Structured Input is a type of forward geocoding search that allows you to define the feature type of each element of the search query by type. This can increase the accuracy of results for well-formed datasets. To use Structured Input, the q parameter is dropped in favor of separate parameters for each feature type.

For best results, each element of the query must be assigned a feature type, and set autocomplete to false.

Required parametersTypeDescription
access_tokenstringAll geocoding requests must include an access token.

The following feature types can be defined in a Structured Input query:

Optional parametersTypeDescription
address_line1stringA string including address_number and street. These values can be provided as separate parameters address_number and street listed below.
address_numberstringThe number associated with the house.
streetstringThe name of the street in the address
blockstringIn some countries like Japan, the block is a component in the address
placestringTypically 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).
regionstringTop-level sub-national administrative features, such as states in the United States or provinces in Canada or China.
postcodestringPostal codes used in country-specific national addressing systems.
localitystringOfficial 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.
neighborhoodstringColloquial sub-city features often referred to in local parlance. Unlike locality features, these typically lack official status and may lack universally agreed-upon boundaries. Not available for reverse geocoding requests.
countrystringGenerally recognized countries or, in some cases like Hong Kong, an area of quasi-national administrative status that has a designated country code under ISO 3166-1.

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

Optional parametersTypeDescription
permanentbooleanSpecify whether you intend to store the results of the query (true) or not (false, default).
autocompletebooleanSpecify 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 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.

When autocomplete is enabled, each user keystroke counts as one request to the Geocoding API. For example, a search for "Cali" would be reflected as four separate Geocoding API requests. To reduce the total requests sent, you can configure your application to only call the Geocoding API after a specific number of characters are typed.
bboxnumberLimit 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.
You can use the Location Helper to find a bounding box for use with this API.
countrystringLimit results to one or more countries. Permitted values are ISO 3166 alpha 2 country codes separated by commas.
formatstringSpecify the desired response format of results (geojson, default) or for backwards compatibility (v5).
languagestringSet the language of the text supplied in responses. 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. The first language in the list will be considered as the primary language and a response will be generated for it. For other languages, translations will be provided, see the translations section.

For more information on which specific languages are supported, see the language coverage section.
limitintegerSpecify the maximum number of results to return. The default is 5 and the maximum supported is 10.
proximitystringBias the response to favor results that are closer to this location. Provided as two comma-separated coordinates in longitude,latitude order, or the string ip to bias based on reverse IP lookup.
typesstringFilter results to include only a subset (one or more) of the available feature types. Options are country, region, postcode, district, place, locality, neighborhood, street, and address. Multiple options can be comma-separated.

For more information on the available types, see the data types section.
worldviewstringReturns features that are defined differently by audiences that belong to various regional, cultural, or political groups. Available worldviews are: ar,cn,in,jp,ma,ru,tr,us. If worldview is not set, the us worldview boundaries are returned by default.

For more information about using the worldview parameter, see the worldviews section.

Example request: Forward geocoding with structured input

$ curl --location --request GET "https://api.mapbox.com/search/geocode/v6/forward?country=us&address_number=1600&street=pennsylvania%20ave%20nw&postcode=20500&place=Washington%20dc&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Forward geocoding with structured input

See the Geocoding API response object section.

Reverse geocoding

get
https://api.mapbox.com/search/geocode/v6/reverse?longitude={longitude}&latitude={latitude}

The reverse geocoding query type allows you to look up a pair of coordinates and returns the geographic features there, including a standardized address or place and full geographic context.

Required parametersTypeDescription
longitudenumberThe longitude decimal value from the geographic coordinate for the location being queried.
latitudenumberThe latitude decimal value from the geographic coordinate for the location being queried.
access_tokenstringAll geocoding requests must include an access token.

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

Optional parametersTypeDescription
permanentbooleanSpecify whether you intend to store the results of the query (true) or not (false, default).
countrystringLimit results to one or more countries. Permitted values are ISO 3166 alpha 2 country codes separated by commas.
languagestringSpecify 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.

Only one value can also be specified.

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

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). So, setting limit to a higher-than-default value requires specifying exactly one types parameter.
typesstringFilter results to include only a subset (one or more) of the available feature types. Options are country, region, postcode, district, place, locality, neighborhood, street, and address. Multiple options can be comma-separated.

For more information on the available types, see the data types section.
worldviewstringReturns features that are defined differently by audiences that belong to various regional, cultural, or political groups. Available worldviews are: ar,cn,in,jp,ma,ru,tr,us. If worldview is not set, the us worldview boundaries are returned by default.

For more information about using the worldview parameter, see the worldviews section.

Example request: Reverse geocoding

# A basic reverse geocoding request
# Retrieve places near a specific location

$ curl "https://api.mapbox.com/search/geocode/v6/reverse?longitude=-73.989&latitude=40.733&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Filter results to only include addresses

$ curl "https://api.mapbox.com/search/geocode/v6/reverse?longitude=-73.989&latitude=40.733&types=address&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Query within the Ilemi Triangle to return features for the US worldview

$ curl "https://api.mapbox.com/search/geocode/v6/reverse?longitude=35.4628&latitude=4.8975&worldview=us&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

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

Improved in v6
book
Geocoding from Snowflake

Snowflake users can do batch geocoding operations on data stored in their data warehouse. The Mapbox Snowflake Native App is available in the Snowflake Marketplace.

post
https://api.mapbox.com/search/geocode/v6/batch

The batch geocoding query type allows you to request up to 1000 forward or reverse geocoding queries in a single request.

Batch geocoding requests are formatted as a JSON object passed as the BODY of the request, but with multiple search queries one after another. Fields which were defined as query parameters in the URL string will become fields in the JSON object. Fields specifying multiple values (for example types, country, bbox, proximity) can be passed either as a comma-separated strings or as JSON-formatted arrays (for example a types filter value could be represented as "address,street,place" or ["address", "street", "place"]).

In a single batch geocoding request, you can bundle queries of different types, including forward queries, forward Structure Input queries, and reverse queries. Each query can also has parameters defined individually -- for example one query could have IP proximity set to on while the rest have it off.

book
Billing for batch geocoding requests

Each individual search in a batch geocoding request counts as one request.

A batch geocoding request can be made using an HTTP POST request with the following body structure:

https://api.mapbox.com/search/geocode/v6/batch

Request Body

[
    {
        "types": ["address"],
        "q": "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States",
        "bbox": [-80, 35, -70, 40],
        "limit": 1
    },
    {
        "types": ["address"],
        "longitude": -73.986136,
        "latitude": 40.748895
    }
]
Required parametersTypeDescription
access_tokenstringAll geocoding requests must include an access token.
Optional parametersTypeDescription
permanentbooleanSpecify if you intend to store the results of the query (true) or not (false, default).

Example request: Batch geocoding

$ curl --location --request POST "https://api.mapbox.com/search/geocode/v6/batch?access_token=YOUR_MAPBOX_ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '[
    {/**** FORWARD GEOCODING REQUEST ****/
        "types": ["address"],
        "q": "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States",
        "bbox": [-80, 35, -70, 40],
        "limit": 1
    },
    { /**** FORWARD GEOCODING REQUEST USING STRUCTURED INPUT ****/
        "country": "us",
        "address_number": "1600",
        "street": "Pennsylvania Avenue NW",
        "postcode": "20500",
        "place": "Washington, DC"
    },
    {/**** REVERSE GEOCODING REQUEST ****/
        "types": ["address"],
        "longitude": -73.986136,
        "latitude": 40.748895
    }
]'

Response: Batch geocoding

The response from a batch geocoding query is an object with a batch property. The batch property is an array of Geocoding response objects. The order of queries in the request determines the order of corresponding objects in the batch array. If there are no results returned for a particular query within the batch, the features array for that query is empty ( "features": [] ).

Here's an example request in which there is a list of three queries. The first two requests are for forward geocoding, and the last one is for reverse.

$ curl --location --request POST 'https://api.mapbox.com/search/geocode/v6/batch?access_token=YOUR_MAPBOX_ACCESS_TOKEN&permanent=true' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "types": ["address"],
        "q": "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States",
        "bbox": [-80, 35, -70, 40],
        "limit": 1
    },
    {
        "types": ["address"],
        "q": "aslkdjf",
        "bbox": [-80, 35, -70, 40]
    },
    {
        "types": ["address"],
        "longitude": -73.986136,
        "latitude": 40.748895
    }
]'

Notice that in the response, the results are in same the order as the queries in the request, where the second query aslkdjf doesn't return a result but still exists in the second position of the array:

{
    "batch": [
        {
            "type": "FeatureCollection",
            "features": [
                {
                    "type": "Feature",
                    "id": "dXJuOm1ieGFkcjo2YzdhYjM4Yi05YzM4LTQ3ZDItODFkMS1jYzZlYjg5YzliMWM",
                    "geometry": {
                        "type": "Point",
                        "coordinates": [
                            -77.03655,
                            38.89768
                        ]
                    },
                    "properties": {
                        "mapbox_id": "dXJuOm1ieGFkcjo2YzdhYjM4Yi05YzM4LTQ3ZDItODFkMS1jYzZlYjg5YzliMWM",
                        "feature_type": "address",
                        "name": "1600 Pennsylvania Avenue Northwest",
                        "coordinates": {
                            "longitude": -77.03655,
                            "latitude": 38.89768,
                            "accuracy": "rooftop"
                        },
                        "place_formatted": "Washington, District of Columbia 20500, United States",
                        "match_code": {
                            "address_number": "matched",
                            "street": "matched",
                            "postcode": "matched",
                            "place": "matched",
                            "region": "matched",
                            "locality": "not_applicable",
                            "country": "inferred",
                            "confidence": "exact"
                        },
                        "context": {
                            "address": {
                                "mapbox_id": "dXJuOm1ieGFkcjo2YzdhYjM4Yi05YzM4LTQ3ZDItODFkMS1jYzZlYjg5YzliMWM",
                                "address_number": "1600",
                                "street_name": "Pennsylvania Avenue Northwest",
                                "name": "1600 Pennsylvania Avenue Northwest"
                            },
                            "street": {
                                "mapbox_id": "dXJuOm1ieGFkcjo2YzdhYjM4Yi05YzM4LTQ3ZDItODFkMS1jYzZlYjg5YzliMWM",
                                "name": "Pennsylvania Avenue Northwest"
                            },
                            "neighborhood": {
                                "mapbox_id": "dXJuOm1ieHBsYzpHYUVzN0E",
                                "name": "National Mall",
                                "alternate": {
                                    "mapbox_id": "dXJuOm1ieHBsYzpEY1ZNN0E",
                                    "name": "Franklin Mcpherson Square"
                                }
                            },
                            "postcode": {
                                "mapbox_id": "dXJuOm1ieHBsYzpBOEZPN0E",
                                "name": "20500"
                            },
                            "place": {
                                "mapbox_id": "dXJuOm1ieHBsYzpGSmlvN0E",
                                "name": "Washington",
                                "wikidata_id": "Q61"
                            },
                            "region": {
                                "mapbox_id": "dXJuOm1ieHBsYzpCUVRz",
                                "name": "District of Columbia",
                                "wikidata_id": "Q3551781",
                                "region_code": "DC",
                                "region_code_full": "US-DC"
                            },
                            "country": {
                                "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
                                "name": "United States",
                                "wikidata_id": "Q30",
                                "country_code": "US",
                                "country_code_alpha_3": "USA"
                            }
                        }
                    }
                }
            ],
            "attribution": "NOTICE: © 2023 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."
        },
        {
            "type": "FeatureCollection",
            "features": [],
            "attribution": "NOTICE: © 2023 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."
        },
        {
            "type": "FeatureCollection",
            "features": [
                {
                    "type": "Feature",
                    "id": "dXJuOm1ieGFkcjplMzVmMzZiOC1kYjRmLTQyOWItOWE4ZC0yZGQ3ZmQ1OTUzMTY",
                    "geometry": {
                        "type": "Point",
                        "coordinates": [
                            -73.9861365,
                            40.7488949
                        ]
                    },
                    "properties": {
                        "mapbox_id": "dXJuOm1ieGFkcjplMzVmMzZiOC1kYjRmLTQyOWItOWE4ZC0yZGQ3ZmQ1OTUzMTY",
                        "feature_type": "address",
                        "name": "20 West 34th Street",
                        "coordinates": {
                            "longitude": -73.9861365,
                            "latitude": 40.7488949,
                            "accuracy": "rooftop"
                        },
                        "place_formatted": "New York, New York 10118, United States",
                        "context": {
                            "address": {
                                "mapbox_id": "dXJuOm1ieGFkcjplMzVmMzZiOC1kYjRmLTQyOWItOWE4ZC0yZGQ3ZmQ1OTUzMTY",
                                "address_number": "20",
                                "street_name": "West 34th Street",
                                "name": "20 West 34th Street"
                            },
                            "street": {
                                "mapbox_id": "dXJuOm1ieGFkcjplMzVmMzZiOC1kYjRmLTQyOWItOWE4ZC0yZGQ3ZmQ1OTUzMTY",
                                "name": "West 34th Street"
                            },
                            "neighborhood": {
                                "mapbox_id": "dXJuOm1ieHBsYzpGQ2VNN0E",
                                "name": "Koreatown"
                            },
                            "postcode": {
                                "mapbox_id": "dXJuOm1ieHBsYzpBWUFPN0E",
                                "name": "10118"
                            },
                            "locality": {
                                "mapbox_id": "dXJuOm1ieHBsYzpGREtLN0E",
                                "name": "Manhattan",
                                "wikidata_id": "Q11299"
                            },
                            "place": {
                                "mapbox_id": "dXJuOm1ieHBsYzpEZTVJN0E",
                                "name": "New York",
                                "wikidata_id": "Q60"
                            },
                            "district": {
                                "mapbox_id": "dXJuOm1ieHBsYzpBUU5tN0E",
                                "name": "New York County",
                                "wikidata_id": "Q500416"
                            },
                            "region": {
                                "mapbox_id": "dXJuOm1ieHBsYzpBYVRz",
                                "name": "New York",
                                "wikidata_id": "Q1384",
                                "region_code": "NY",
                                "region_code_full": "US-NY"
                            },
                            "country": {
                                "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
                                "name": "United States",
                                "wikidata_id": "Q30",
                                "country_code": "US",
                                "country_code_alpha_3": "USA"
                            }
                        }
                    }
                }
            ],
            "attribution": "NOTICE: © 2023 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."
        }
    ]
}

Geocoding response object

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

PropertyTypeDescription
typestring"FeatureCollection", a GeoJSON type from the GeoJSON specification.
featuresarrayAn 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.

Read the Search result prioritization guide to learn more about how returned features are organized in the Geocoding API response.
attributionstringAttributes the results of the Mapbox Geocoding API to Mapbox.

The data powering the Mapbox Geocoding API 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:

PropertyTypeDescription
idstringFeature id. This property is named "id" to conform to the GeoJSON specification, but is the same id referred to as mapbox_id elsewhere in the response.
typestring"Feature", a GeoJSON type from the GeoJSON specification.
geometryobjectAn object describing the spatial geometry of the returned feature.
geometry.typestring"Point", a GeoJSON type from the GeoJSON specification.
geometry.coordinatesarrayAn array in the format [longitude,latitude] at the center of the specified bbox.
propertiesobjectAn object containing the resulting feature's details.

Each properties object in a feature may have the attributes described below:

PropertyTypeDescription
mapbox_idstringFeature id. The mapbox_id uniquely identifies a place in the Mapbox search database. Mapbox ID’s are accepted in requests to the Geocoding API as a forward search, and will return the feature corresponding to that id.
feature_typestringA string describing the type of the feature. Options are country, region, postcode, district, place, locality, neighborhood, street, address.
Formerly place_type in v5.
namestringFormatted string of address_number and street.
name_preferredstringPresent when there is a canonical or otherwise more common alias for the feature name. For example, searching for "America" will return "America" as the name, and "United States" as name_preferred.
place_formattedstringFormatted string of result context: place region country postcode. The part of the result which comes after name.
contextobjectAn object representing the hierarchy of encompassing parent features. This may include a sub-object for any of the following properties: country, region, postcode, district, place, locality, neighborhood, street.
Which sub-objects are included is dependent upon the data coverage available and applicable to a given country or area.
coordinatesobject
coordinates.longitudenumberLongitude of result
coordinates.latitudenumberLatitude of result
coordinates.accuracynumberAccuracy metric for a returned address-type result. See "Point accuracy for address features" below.
bboxnumberThe bounding box of the feature in minLon,minLat,maxLon,maxLat order. This property is only provided with features of type country, region, postcode, district, place, locality, or neighborhood.
match_codeobjectAdditional metadata indicating how the result components match to the input query. See "Smart Address Match" below.

The Context Object

The context object within properties is a powerful piece of data which breaks out the complete geographical hierarchy for a given address or place. It is both a reliable way to access the named values of each component part of an address, plus contains feature-specific data such as the Wikidata id and 3-letter alpha country code.

Each sub-object in the context always has a mapbox_id and name associated with it. The id can be queried directly via a forward geocoding search to traverse into a different geographical layer. Address features will also include an address sub-object, which additionally contains street_name and address_number properties.

Example Context Object

The following is an example of the context object returned for the address 2595 Lucky John Drive, Park City, Utah 84060, United States:

"context": {
    "address": {
        "mapbox_id": "dXJuOm1ieGFkcjozOGY3OTg1OC1jNzY0LTQ4ZGUtYTFmMC04NjJjOTM1ZWViMjc",
        "address_number": "2595",
        "street_name": "Lucky John Drive",
        "name": "2595 Lucky John Drive"
    },
    "street": {
        "mapbox_id": "dXJuOm1ieGFkcjozOGY3OTg1OC1jNzY0LTQ4ZGUtYTFmMC04NjJjOTM1ZWViMjc",
        "name": "Lucky John Drive"
    },
    "neighborhood": {
        "mapbox_id": "dXJuOm1ieHBsYzpITktzN0E",
        "name": "Park Meadows"
    },
    "postcode": {
        "mapbox_id": "dXJuOm1ieHBsYzpFUjNPN0E",
        "name": "84060"
    },
    "place": {
        "mapbox_id": "dXJuOm1ieHBsYzpEdjlvN0E",
        "name": "Park City",
        "wikidata_id": "Q482993"
    },
    "district": {
        "mapbox_id": "dXJuOm1ieHBsYzpBVlRHN0E",
        "name": "Summit County",
        "wikidata_id": "Q484563"
    },
    "region": {
        "mapbox_id": "dXJuOm1ieHBsYzpCa1Rz",
        "name": "Utah",
        "wikidata_id": "Q829",
        "region_code": "UT",
        "region_code_full": "US-UT"
    },
    "country": {
        "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
        "name": "United States",
        "wikidata_id": "Q30",
        "country_code": "US",
        "country_code_alpha_3": "USA"
    }
}

Translations

When providing more than one language in the context object for the country, region, district, place, neighborhood properties will appear the translations property. This is an object where the key is the language code and the value is an object with language and name properties.

Translations Example

Example of the context object when passing the parameter language=en,es.

{
    "context": {
        "address": {
            "mapbox_id": "dXJuOm1ieGFkcjowYzNhM2QzZi03ODIyLTQ3YzItODRlNC04YzA3ZDIxMTE2MmE",
            "address_number": "100",
            "street_name": "Jefferson Street Northwest",
            "name": "100 Jefferson Street Northwest"
        },
        "street": {
            "mapbox_id": "dXJuOm1ieGFkcjowYzNhM2QzZi03ODIyLTQ3YzItODRlNC04YzA3ZDIxMTE2MmE",
            "name": "Jefferson Street Northwest"
        },
        "neighborhood": {
            "mapbox_id": "dXJuOm1ieHBsYzpCQTRzN0E",
            "name": "Brightwood Park",
            "translations": {
                "en": {
                    "language": "en",
                    "name": "Brightwood Park"
                },
                "es": {
                    "language": "es",
                    "name": "Brightwood Park"
                }
            }
        },
        "postcode": {
            "mapbox_id": "dXJuOm1ieHBsYzpBNSt1N0E",
            "name": "20011"
        },
        "place": {
            "mapbox_id": "dXJuOm1ieHBsYzpGSmlvN0E",
            "name": "Washington",
            "wikidata_id": "Q61",
            "translations": {
                "en": {
                    "language": "en",
                    "name": "Washington"
                },
                "es": {
                    "language": "es",
                    "name": "Washington"
                }
            }
        },
        "region": {
            "mapbox_id": "dXJuOm1ieHBsYzpCUVRz",
            "name": "District of Columbia",
            "wikidata_id": "Q3551781",
            "region_code": "DC",
            "region_code_full": "US-DC",
            "translations": {
                "en": {
                    "language": "en",
                    "name": "District of Columbia"
                },
                "es": {
                    "language": "es",
                    "name": "Distrito de Columbia"
                }
            }
        },
        "country": {
            "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA",
            "translations": {
                "en": {
                    "language": "en",
                    "name": "United States"
                },
                "es": {
                    "language": "es",
                    "name": "Estados Unidos"
                }
            }
        }
    }
}

Point accuracy for address features

The coordinates.accuracy property in a Geocoding API response object is a point accuracy metric for the returned address feature. This list is subject to change.

AccuracyDescription
rooftopResult intersects a known building/entrance.
parcelResult falls within a known parcel boundary of the same address.
proximateResult is a known address point but does not intersect a known rooftop/parcel. In some cases, it may also be an interpolated result (as in its position and existence are estimated based on nearby known addresses), which can be confirmed by checking if the match_code value for address_number is plausible.

Smart Address Match

New in v6

The match_code object in the Geocoding API helps you understand how the resulting address feature aligns with the query submitted. Available only for address-type features, the match_code provides a breakdown of how each element of the result matches with the query, plus a confidence score, based on how well it matches. This can help you make decisions about what results to keep or throw out based on your application's tolerance for fuzzy matching on the query.

Smart Address Match is available for all forward geocoding requests that return an address type feature. It works best when using Structured Input forward queries, as the request components must be typed explicitly.

Confidence ScoreDescription
exactNo components are unmatched (up to 2 may be inferred) and no there are no extraneous query tokens.
highOne component (excluding house_number or region) may have been corrected. Additionally, if only house_number, street, and postcode are provided and match, high confidence is returned.
mediumTwo components (excluding house_number or region) may have changed. Allows for minor misspellings. If house_number, street, place, and postcode are matched the region may be corrected.
lowHouse Number, Region, or more than 2 other components have been corrected.
Match CodeDescription
matchedThe component value matches the user's input.
unmatchedThe component value doesn't match the user's input, or the user didn't submit this component type as part of the query.
not_applicableThe component is not used in the postal address string for example locality.
inferredThe component type wasn't submitted as part of the query, but we were able to confidently fill in the value. only returned for the country component.
plausibleOnly relevant for the address_number component. The value matches the user's input, but it was interpolated. This means that the geocoder found the street and, based on the surrounding known addresses, was able to confidently estimate the location of the building with that address_number.

Example match_code

This forward geocoding request with structured input includes a valid street address in Park City Utah, USA.

https://api.mapbox.com/search/geocode/v6/forward?&address_number=2595&street=lucky john dr&place=park city&region=CO

Note that the region parameter value is CO, and will yield an unmatched status in the match_code in the resulting feature's properties as the matched address is not in the US state of Colorado.

{
  name:"2595 Lucky John Drive",
  place_formatted:"Park City, Utah 84060, United States",
  match_code:{
    address_number:"matched",
    street:"matched",
    postcode:"unmatched",
    place:"matched",
    region:"unmatched",
    locality:"not_applicable",
    country:"inferred",
    confidence:"medium",
  }
}

Example response: Forward geocoding

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "id": "dXJuOm1ieGFkcjo5ZDQzNzM1Mi0xZGZiLTRkNTItYWMxNC01MzllZjY5ODIwMmI",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -111.86313,
                    40.725163
                ]
            },
            "properties": {
                "mapbox_id": "dXJuOm1ieGFkcjo5ZDQzNzM1Mi0xZGZiLTRkNTItYWMxNC01MzllZjY5ODIwMmI",
                "feature_type": "address",
                "name": "974 2100 South",
                "coordinates": {
                    "longitude": -111.86313,
                    "latitude": 40.725163,
                    "accuracy": "rooftop"
                },
                "place_formatted": "Salt Lake City, Utah 84106, United States",
                "match_code": {
                    "address_number": "matched",
                    "street": "matched",
                    "postcode": "unmatched",
                    "place": "unmatched",
                    "region": "unmatched",
                    "locality": "not_applicable",
                    "country": "inferred",
                    "confidence": "low"
                },
                "context": {
                    "address": {
                        "mapbox_id": "dXJuOm1ieGFkcjo5ZDQzNzM1Mi0xZGZiLTRkNTItYWMxNC01MzllZjY5ODIwMmI",
                        "address_number": "974",
                        "street_name": "2100 South",
                        "name": "974 2100 South"
                    },
                    "street": {
                        "mapbox_id": "dXJuOm1ieGFkcjo5ZDQzNzM1Mi0xZGZiLTRkNTItYWMxNC01MzllZjY5ODIwMmI",
                        "name": "2100 South"
                    },
                    "neighborhood": {
                        "mapbox_id": "dXJuOm1ieHBsYzpERWdNN0E",
                        "name": "Fairmont",
                        "alternate": {
                            "mapbox_id": "dXJuOm1ieHBsYzpLMmRzN0E",
                            "name": "Winfield"
                        }
                    },
                    "postcode": {
                        "mapbox_id": "dXJuOm1ieHBsYzpFU011N0E",
                        "name": "84106"
                    },
                    "place": {
                        "mapbox_id": "dXJuOm1ieHBsYzpFVmhvN0E",
                        "name": "Salt Lake City",
                        "wikidata_id": "Q23337",
                        "alternate": {
                            "mapbox_id": "dXJuOm1ieHBsYzpETE5vN0E",
                            "name": "Millcreek"
                        }
                    },
                    "district": {
                        "mapbox_id": "dXJuOm1ieHBsYzpBVGdtN0E",
                        "name": "Salt Lake County",
                        "wikidata_id": "Q484556"
                    },
                    "region": {
                        "mapbox_id": "dXJuOm1ieHBsYzpCa1Rz",
                        "name": "Utah",
                        "wikidata_id": "Q829",
                        "region_code": "UT",
                        "region_code_full": "US-UT"
                    },
                    "country": {
                        "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
                        "name": "United States",
                        "wikidata_id": "Q30",
                        "country_code": "US",
                        "country_code_alpha_3": "USA"
                    }
                }
            }
        },
        {
            "type": "Feature",
            "id": "dXJuOm1ieGFkcjpkNjZkM2M0Zi1hNTA0LTQ3NTQtYTZjMS1iNjYwMGU2NWY4NmI",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -111.919654,
                    40.725872
                ]
            },
            "properties": {
                "mapbox_id": "dXJuOm1ieGFkcjpkNjZkM2M0Zi1hNTA0LTQ3NTQtYTZjMS1iNjYwMGU2NWY4NmI",
                "feature_type": "address",
                "name": "974 2100 South",
                "coordinates": {
                    "longitude": -111.919654,
                    "latitude": 40.725872,
                    "accuracy": "proximate"
                },
                "place_formatted": "South Salt Lake, Utah 84119, United States",
                "match_code": {
                    "address_number": "plausible",
                    "street": "matched",
                    "postcode": "unmatched",
                    "place": "unmatched",
                    "region": "unmatched",
                    "locality": "not_applicable",
                    "country": "inferred",
                    "confidence": "low"
                },
                "context": {
                    "address": {
                        "mapbox_id": "dXJuOm1ieGFkcjpkNjZkM2M0Zi1hNTA0LTQ3NTQtYTZjMS1iNjYwMGU2NWY4NmI",
                        "address_number": "974",
                        "street_name": "2100 South",
                        "name": "974 2100 South"
                    },
                    "street": {
                        "mapbox_id": "dXJuOm1ieGFkcjpkNjZkM2M0Zi1hNTA0LTQ3NTQtYTZjMS1iNjYwMGU2NWY4NmI",
                        "name": "2100 South"
                    },
                    "neighborhood": {
                        "mapbox_id": "dXJuOm1ieHBsYzpCVG5NN0E",
                        "name": "Cannon",
                        "alternate": {
                            "mapbox_id": "dXJuOm1ieHBsYzpGYU5zN0E",
                            "name": "Lincoln Park"
                        }
                    },
                    "postcode": {
                        "mapbox_id": "dXJuOm1ieHBsYzpFU1RPN0E",
                        "name": "84119"
                    },
                    "place": {
                        "mapbox_id": "dXJuOm1ieHBsYzpFbStJN0E",
                        "name": "South Salt Lake",
                        "alternate": {
                            "mapbox_id": "dXJuOm1ieHBsYzpFMHRJN0E",
                            "name": "Taylorsville"
                        }
                    },
                    "district": {
                        "mapbox_id": "dXJuOm1ieHBsYzpBVGdtN0E",
                        "name": "Salt Lake County",
                        "wikidata_id": "Q484556"
                    },
                    "region": {
                        "mapbox_id": "dXJuOm1ieHBsYzpCa1Rz",
                        "name": "Utah",
                        "wikidata_id": "Q829",
                        "region_code": "UT",
                        "region_code_full": "US-UT"
                    },
                    "country": {
                        "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
                        "name": "United States",
                        "wikidata_id": "Q30",
                        "country_code": "US",
                        "country_code_alpha_3": "USA"
                    }
                }
            }
        }
    ],
    "attribution": "NOTICE: © 2023 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."
}

Worldviews

Use the optional worldview parameter to identify geographic features whose characteristics are defined differently by audiences belonging to various regional, cultural, or political groups. The Geocoding API only supports worldviews for the country and region data types, but may expand to additional data types in the future.

Available worldviews

The Geocoding API supports the following values for the worldview parameter:

ValueDescription
arFeatures for an Argentinian audience
cnFeatures for a mainland Chinese audience
inFeatures for an Indian audience
jpFeatures for a Japanese audience
maFeatures for a Moroccan audience
ruFeatures for a Russian audience
trFeatures for a Turkish audience
usFeatures for an American audience

Returned features are not officially approved for use by the above countries' respective governments.

Each query supports a maximum of one worldview. Attempting to query for multiple worldviews in one search will result in an error message. When no worldview is selected, the Geocoding API returns features for the us worldview.

Using the worldview parameter

In Mapbox services, the worldview data field is used to identify geographic features whose characteristics are defined differently by audiences belonging to various regional, cultural, or political groups. Setting a worldview affects the place values returned for an address that is located in an area of non-unanimous ownership or definition.

For example, consider an address in the Ilemi Triangle, which borders Eastern Equatoria (South Sudan) and Turkana (Kenya). Depending on the worldview selected, an address in this location will be returned in different country contexts:

  • If worldview=cn, Kaaleng, Eastern Equatoria, or South Sudan will be returned.
  • If worldview=us, Kaaleng, Turkana, or Kenya will be returned.

This means that if you use wordlview=cn worldview with the Kenya (ke) country filter, a search for an address in this area will not be successful. Instead, you would need to use worldview=cn in combination with the South Sudan (ss) country filter.

Be cautious when combining worldview with the country parameter, since these indices are only loosely coupled.

For a visual example of how changing the worldview value impacts the boundaries on a map, see the companion Maps boundary service.

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 Englishes Spanish
fr Frenchit Italiannl Dutch
pl Polish

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
az Azerbaijanibn Bengalica Catalan
cs Czechda Danishel Modern Greek
fa Persianfi Finnishga Irish
hu Hungarianid Indonesianis Icelandic
ja Japaneseka Georgiankm Central Khmer
ko Koreanlt Lithuanianlv Latvian
mn Mongolianpt Portuguesero Romanian
sk Slovaksq Albaniansv Swedish
th Thaitl Tagaloguk Ukrainian
vi Vietnamesezh Chinesezh_Hans Simplified Chinese
zh_TW Taiwanese Mandarin

Limited coverage

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

Language
ar Arabicbs Bosniangu Gujarati
he Hebrewhi Hindikk Kazakh
lo Laomy Burmesenb Norwegian Bokmål
ru Russiansr Serbiante Telugu
tk Turkmentr Turkishzh_Hant Traditional Chinese

Find more details about the format and properties of Geocoding API responses in the response object section.

Geocoding API errors

Response body messageHTTP error codeDescription
Not Authorized - No Token401No token was used in the query.
Not Authorized - Invalid Token401Check the access token you used in the query.
Forbidden403There may be an issue with your account. Check your Account page for more details.

In some cases, using an access tokens with URL restrictions can also result in a 403 error. For more information, see our Token management guide.
Not Found404Check the endpoint you used in the query.
Not Found404No search text or structured input parameters were provided in the query.
BBox is not valid. Must be an array of format [minX, minY, maxX, maxY]422Check the format for bbox, where the first coordinate pair should refer to the southwestern corner of the box and the second pair should refer to the northeastern corner of the box.
BBox {minX/maxX} value must be a number between -180 and 180422Check the format of minX and maxX for bbox.
BBox {minY/maxY} value must be a number between -90 and 90422Check the format of minY and maxY for bbox.
BBox {minX/minY} value cannot be greater than {maxX/maxY} value422Check the values of the coordinate pairs used in bbox.
Type "{input}" is not a known type. Must be one of: country, region, place, district, postcode, locality, neighborhood, and address422Check the type you used in the query.
Stack "{input}" is not a known stack. Must be one of: …422The country parameter must be a valid ISO 3166 alpha 2 country code.
Batch queries must include 50 queries or less422Your batch geocode request cannot contain more than 50 queries.
Query too long {query length}/256 characters422Your query cannot contain more than 256 characters.
Query too long - {query tokens length}/20 tokens422Your query cannot contain more than 20 word boundary-delimited strings (also known as tokens).
Proximity must be an array in the form [lon, lat]422The proximity parameter must contain two comma-separated values.
Proximity lon value must be a number between -180 and 180422Check the proximity parameter's longitude value.
Proximity lat value must be a number between -90 and 90422Check the proximity parameter's latitude value.
"{input}" is not a valid language code422The language parameter must be a valid IETF language tag comprised of a mandatory ISO 639-1 language code and, optionally, one or more IETF subtags for country or script.
options.language should be a list of no more than 20 languages422Your query's language parameter cannot contain more than 20 language codes.
options.language should be a list of unique language codes422The comma-separated values in language must be unique.
limit must be combined with a single type parameter when reverse geocoding422If you make a reverse geocoding request with the limit parameter, you must also use the type parameter.
Rate limit exceeded429You have exceeded your set rate limit. Check your Account page for more details.

Geocoding restrictions and limits

To protect the Geocoding API and maximize service stability, Mapbox rate limits Geocoding API requests.

  • The default Geocoding API rate limit is 1000 requests per minute, but can be adjusted on a per-account basis. Mapbox may automatically adjust customer rate limits to accommodate high traffic applications, or prevent abuse, if deemed appropriate.
  • An HTTP error code of 429 will be returned if the rate limit is reached.
  • If you require a higher rate limit, contact us.

Geocoding API pricing

  • Billed by requests
  • See rates and discounts per Geocoding API request in the pricing page's Search section

Usage of the Geocoding API is measured in API requests. 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 pricing page. You may only use responses from the Geocoding API in conjunction with a Mapbox map.

Autocomplete and pricing

The Geocoding API's autocomplete parameter is enabled by default. If you are using the API with autocomplete enabled, you will likely accumulate one API request per keystroke. For example, if you have autocomplete turned on and you set up your application to make a Geocoding API request every time a user types a character into a search bar, then a user typing "Cali" looking for "California" will be making four Geocoding API requests, one for each letter.

To reduce the number of requests made while autocomplete is enabled, you can wait to begin making API requests until a specific number of characters are entered. The Geocoding API doesn't have a parameter for limiting requests built in, but you can use the Mapbox GL Geocoder, which does have that option, or you can write it into your application directly.

Batch geocoding and pricing

Batch geocoding allows you to have multiple geocoding queries in a single request. Each individual search in a batch geocoding request counts as one request. For example, a request that contains three searches would count as three requests and be billed as such. These three requests would be reflected on your statistics graph and your bill.

Japan Geocoding

The Geocoding API includes a robust Japan address and place search. In order to access the new, high-accuracy and high-coverage Japan search, you must set both the language and country parameters:

  • language=ja
  • country=jp

Japan geocoding responses use the same geographic feature types as other countries to define a feature's context components (with the addition of a block component, where applicable). These feature types represent the following equivalents of a Japanese address structure:

Geographic feature typeJapan address equivalent
blockblock
neighborhoodchome
localityoaza
placecity
regionprefecture

Japan geocoding responses also contain a unique feature.properties.reading object for Japanese reading equivalents by script type, for example:

{
  ja-Kana:"ヤマグチケンシモノセキシシンアカダニシマチ"
  ja-Latn:"yamaguchiken shimonosekishi shinakadanishimachi"
}
Was this page helpful?