> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/api/ja/llms.txt) # Geocoding v5 API The **Mapbox Geocoding API** does two things: *forward geocoding* and *reverse geocoding*. > **Note (warning): Geocoding v5 POI Deprecation** > > Points of Interest (POI) data has been removed from the Geocoding v5 API. If your application relies on searching for POIs like restaurants, gas stations, and landmarks, we recommend transitioning to the [Search Box API](https://docs.mapbox.com/api/search/search-box/). If your use case is primarily address and place search, you can continue using Geocoding v5 without interruption. To enjoy new features like unit-level geocoding, structured input, Smart Address Match, and improved batch geocoding, consider upgrading to the new [Geocoding v6](https://docs.mapbox.com/api/ja/search/geocoding/), which has the same per request price as v5. > **Note (new): Geocoding v6 API** > > Enhanced features and expanded coverage are available in v6 of the Geocoding API. [Learn more about Geocoding v6](https://docs.mapbox.com/api/ja/search/geocoding/) > **Note (beta): Building entrance locations in public preview** > > The `entrances` parameter is in public preview. This parameter allows you to access building entrances in the responses of your geocoding queries - both with permanent and temporary geocoding. To learn more about this parameter, see the [Forward geocoding optional parameters table](https://docs.mapbox.com/api/search/geocoding/#forward-geocoding-with-search-text-input) in the Geocoding API documentation. 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](https://docs.mapbox.com/help/getting-started/geocoding/#how-geocoding-works). You may also use one of several [wrapper libraries](https://docs.mapbox.com/help/getting-started/geocoding/#libraries-and-plugins) to integrate the Mapbox Geocoding API into an application instead of using it directly. > **Related content (playground): [Geocoding API playground](https://docs.mapbox.com/playground/geocoding-v5/)** > > Try forward and reverse geocoding queries and see the results on a map. ## Endpoints The Geocoding API includes two different endpoints: `mapbox.places` and `mapbox.places-permanent`. ### mapbox.places Requests to the `mapbox.places` endpoint must be triggered by user activity, as described in Mapbox's [terms of service](https://www.mapbox.com/legal/tos) and included [product terms](https://www.mapbox.com/legal/service-terms). ### mapbox.places-permanent The `mapbox.places-permanent` endpoint gives you access to two services: permanent geocoding and batch geocoding. If you're interested in using the `mapbox.places-permanent` endpoint for these use cases, contact [Mapbox sales](https://www.mapbox.com/contact/sales/). > **Note (warning): Unsuccessful requests may still be billed** > > It's important to speak with an Account Manager on the Sales team before making requests to the `mapbox.places-permanent` endpoint. Unsuccessful requests made by an account that does not have access to the endpoint may be billable. The data available for other feature types may vary slightly compared to the data available in the `mapbox.places` endpoint. ## Geographical 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. > **Note: POI in the Geocoding API** > > - If you need POI results in your search besides addresses, use [Search Box API](https://docs.mapbox.com/api/ja/search/search-box/) The data types available in the geocoder, listed from the largest to the most granular, are: | Data type | Description | | --- | --- | | `country` | Generally 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](https://www.iso.org/iso-3166-country-codes.html). | | `region` | Top-level sub-national administrative features, such as states in the United States or provinces in Canada or China. | | `postcode` | Postal codes used in country-specific national addressing systems. | | `district` | Features that are smaller than top-level administrative features but typically larger than cities, in countries that use such an additional layer in postal addressing (for example, prefectures in China). | | `place` | Typically these are cities, villages, municipalities, etc. They're usually features used in postal addressing, and are suitable for display in ambient end-user applications where current-location context is needed (for example, in weather displays). | | `locality` | Official sub-city features present in countries where such an additional administrative layer is used in postal addressing, or where such features are commonly referred to in local parlance. Examples include city districts in Brazil and Chile and arrondissements in France. | | `neighborhood` | Colloquial sub-city features often referred to in local parlance. Unlike `locality` features, these typically lack official status and may lack universally agreed-upon boundaries. | | `address` | Individual residential or business addresses. | *A note about multi-typing: A small number of geographic features have multiple data types assigned to them. This mainly occurs between the `country` and `region` data types, as well as the `region` and `place` data types, to match duplicate [ISO-3166-1 codes](https://www.iso.org/iso-3166-country-codes.html). Approximately 26 subdivisions have their own ISO 3166-1 codes. For example, the island of Puerto Rico is multi-typed as `country,region`, meaning that it could be returned as a standalone `country` data type, or as a `region` data type.* ## Forward geocoding **GET** : `https://api.mapbox.com/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.
Required parametersTypeDescription
endpointstringOne of mapbox.places or mapbox.places-permanent, as described in the Endpoints section.
search_textstringThe 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_tokenstringA valid Mapbox access token.
You can further refine the results of a forward geocoding query with the following optional parameters:
Optional parametersTypeDescription
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 "coff" 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.
countrystringLimit results to one or more countries. Permitted values are ISO 3166 alpha 2 country codes separated by commas.
fuzzyMatchbooleanSpecify whether the Geocoding API should try approximate, as well as exact, matching when performing searches (true, default), or whether it should opt out of this behavior and only try exact matching (false). For example, the default setting might return Washington, DC for a query of wahsington, even though the query was misspelled.
languagestringSpecify 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.
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.
routingbooleanSpecify 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.
typesstringFilter results to include only a subset (one or more) of the available feature types. Options are country, region, postcode, district, place, locality, neighborhood, and address. Multiple options can be comma-separated.

For more information on the available types, see the geographical feature 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,rs,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.
entrancesbooleanSpecify whether to return building entrance data (true) or not (false, default). When set to true, building entrances associated with address features will be included in the response. This includes both permanent and temporary geocoding. This parameter is in Public Preview.
### Example request: Forward geocoding ```bash # 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 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/geocoding/v5/mapbox.places/Washington.json?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/geocoding/v5/mapbox.places/Kaaleng.json?worldview=cn&access_token=YOUR_MAPBOX_ACCESS_TOKEN" ``` ### 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 response object section](#geocoding-response-object). ## Reverse geocoding **GET** : `https://api.mapbox.com/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. | Required parameters | Type | Description | | --- | --- | --- | | `endpoint` | `string` | One of `mapbox.places` or `mapbox.places-permanent`, as described in the [Endpoints section](#endpoints). | | `longitude,latitude` | `number` | A `longitude,latitude` pair that specifies the location being queried. | | `access_token` | `string` | A valid Mapbox [access token](https://docs.mapbox.com/api/ja/guides/#access-tokens-and-token-scopes). | You can further refine the results of a reverse geocoding query with the following optional parameters:
Optional parametersTypeDescription
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.

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

For more information on the available types, see the geographical feature 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,rs,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.
entrancesbooleanSpecify whether to return building entrance data (true) or not (false, default). When set to true, building entrances associated with address features will be included in the response. This includes both permanent and temporary geocoding. This parameter is in Public Preview.
### Example request: Reverse geocoding ```bash # 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" # Query within the Ilemi Triangle to return features for the us worldview $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/35.4628,4.8975.json&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 response object section](#geocoding-response-object). ## Batch geocoding **GET** : `https://api.mapbox.com/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. Batch geocoding is only available using the [`mapbox.places-permanent` endpoint](#endpoints). If you are interested in using `mapbox.places-permanent` to do batch geocodes, contact [Mapbox sales](https://www.mapbox.com/contact/sales/). 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. > **Note: Billing for batch geocoding requests** > > **Each individual semicolon-separated search in a batch geocoding request counts as one request.** A batch forward geocoding request with three search strings, for example `Juneau,Alaska;Fresno,CA;Phoenix,Arizona`, would count as three requests. These three requests would count against your [rate limit](#geocoding-restrictions-and-rate-limits). They would also be billed as three individual requests, which would be reflected on your [statistics graph](https://console.mapbox.com/account/statistics/) and your bill. You can make a *batch forward geocoding request* by using an `HTTP GET` request: ```bash https://api.mapbox.com/geocoding/v5/mapbox.places-permanent/{search_text_1};{search_text_2}[;{search_text_N};...].json?parameters ``` You can make a *reverse geocoding request* by using an `HTTP GET` request: ```bash https://api.mapbox.com/geocoding/v5/mapbox.places-permanent/{lon_1},{lat_1};{lon_2},{lat_2}[;{lon_N},{lat_N};...].json?parameters ``` | Required parameters | Type | Description | | --- | --- | --- | | `search_text_N` | `string` | *For batch forward queries.* The features to look up (addresses, 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}` | `number` | *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_token` | `string` | A valid Mapbox [access token](https://docs.mapbox.com/api/ja/guides/#access-tokens-and-token-scopes). | For batch forward queries, you may use any optional parameters that are available for single [forward geocoding queries](#forward-geocoding), and they will apply to all search texts. Likewise, for reverse queries, you may use any optional parameters that apply to single [reverse geocoding queries](#reverse-geocoding). ### Example request: Batch geocoding ```bash $ 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 a batch geocoding query is an array of results in [GeoJSON feature collection](https://tools.ietf.org/html/rfc7946) format. The order of the semi-colon separated list of queries in the request determines the order of corresponding objects in the returned 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 the list of three queries is `fairbanks,alaska;aslkdjf;juno,alaska`. ``` https://api.mapbox.com/geocoding/v5/mapbox.places-permanent/fairbanks,alaska;aslkdjf;juno,alaska.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN&limit=1 ``` In the request above, the value of parameter `limit` is `1`, so each query returns a maximum of one result in the response. 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: ```json [ { "type": "FeatureCollection", "query": ["fairbanks", "alaska"], "features": [ { "id": "place.16619084287168120", "type": "Feature", "place_type": ["place"], "relevance": 1, "properties": { "wikidata": "Q79638" }, "text": "Fairbanks", "place_name": "Fairbanks, Alaska, United States", "bbox": [ -152.082261679596, 63.9388459884296, -143.884791986593, 68.0041310199992 ], "center": [-147.7164, 64.8378], "geometry": { "type": "Point", "coordinates": [-147.7164, 64.8378] }, "context": [ { "id": "region.9053016009778630", "short_code": "US-AK", "wikidata": "Q797", "text": "Alaska" }, { "id": "country.9053006287256050", "short_code": "us", "wikidata": "Q30", "text": "United States" } ] } ], "attribution": "© 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/)" }, { "type": "FeatureCollection", "query": ["aslkdjf"], "features": [], "attribution": "© 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/)" }, { "type": "FeatureCollection", "query": ["juno", "alaska"], "features": [ { "id": "region.9053016009778630", "type": "Feature", "place_type": ["region"], "relevance": 0.5, "properties": { "short_code": "US-AK", "wikidata": "Q797" }, "text": "Alaska", "place_name": "Alaska, United States", "bbox": [-179.9, 51.075286, -129.974167, 71.540724], "center": [-150, 64], "geometry": { "type": "Point", "coordinates": [-150, 64] }, "context": [ { "id": "country.9053006287256050", "short_code": "us", "wikidata": "Q30", "text": "United States" } ] } ], "attribution": "© 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/)" } ] ``` ### Recommended testing method for entrance data > **Note (beta)** > > The `entrances` parameter is in public preview. Run an offline comparison of entrance data to test it quickly at scale: 1. Run existing geocoder locations and Mapbox entrance points against the same set of addresses. 2. Compare each result to a known reference point (for example, a past delivery location or other ground-truth coordinate) and measure which point is closer to the reference. 3. The resulting distance-to-reference metric quantifies how often Mapbox entrance data places drivers closer to the correct entrance. The metric can be directly correlated to the efficiency gains, reduced dwell time, and lower support volume that would result from deploying Mapbox entrance locations in a production environment. ## 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.
queryarrayForward geocodes: An array of space and punctuation-separated strings from the original query.
Reverse geocodes: An array containing the coordinates being queried.
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.
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:
PropertyTypeDescription
idstringA 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.
typestring"Feature", a GeoJSON type from the GeoJSON specification.
place_typestringAn array of feature types describing the feature. Options are country, region, postcode, district, place, locality, neighborhood, and address. 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.)
relevancenumberIndicates how well the returned feature matches the user's query on a scale from 0 to 1. 0 means the result does not match the query text at all, while 1 means the result fully matches the query text. You can use the relevance property to remove results that don’t fully match the query. Learn more about textual relevance in the Search result prioritization guide.
addressstringOptional. The house number for the returned address feature. Note that this property is outside the properties object.
propertiesobjectAn 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.accuracystringOptional. 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. For details on these options, see the Point accuracy for address features section.
properties.wikidatastringOptional. The Wikidata identifier for the returned feature.
properties.short_codestringOptional. The ISO 3166-1 country and ISO 3166-2 region code for the returned feature.
properties.landmark
LEGACY
booleanDescribes whether 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.tel
LEGACY
stringA formatted string of the telephone number for the returned poi feature.
textstringA string representing the feature in the requested language, if specified.
place_namestringA string representing the feature in the requested language, if specified, and its full result hierarchy.
matching_textstringOptional. 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.

Category matches will not appear as matching_text. For example, a query for coffee, Köln with language set to English (en) would return a poi Café Reichard, but this feature will not include a matching_text field.
matching_place_namestringOptional. 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.

Category matches will not appear in the matching_place_name field. For example, a query for coffee, Köln with language set to English (en) would return a matching_place_name of Café Reichard, Unter Fettenhennen 11, Köln, North Rhine-Westphalia 50667, Germany instead of a matching_place_name of coffee, Unter Fettenhennen 11, Köln, North Rhine-Westphalia 50667, Germany.
text_{language}stringOptional. 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}stringOptional. 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.
languagestringOptional. A string of the IETF language tag of the query’s primary language.
language_{language}stringOptional. 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.
bboxarrayA bounding box array in the form [minX,minY,maxX,maxY].
centerarrayThe 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).
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.
geometry.interpolatedbooleanOptional. 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.omittedbooleanOptional. 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.
contextarrayAn array representing the hierarchy of encompassing parent features. Each parent feature may include any of the above properties.
routable_pointsobjectOptional. An object with the routable points for the feature.
routable_points.pointsarray or nullOptional. An array of points in the form of [{ coordinates: [lon, lat] }], or if no points are provided this value is null.
### The `routable_points` property `routable_points` is an array that contains auxiliary geographic points associated with an address, each optimized for a specific access or navigation use case. The array contains the following: - `default` is the standard, always-included routable point. This is the best navigable vehicle stopping location for accessing the address. This is algorithmically generated and has coverage across all address results. - `entrance` is the physical entrance location of the address, when available. This is distinct from the vehicle stop point and is intended for locating the door/entrance to access the building at that address. > **Note (beta)** > > The entrance routable point is in public preview. ### Point accuracy for `address` features The `properties.accuracy` property in a Geocoding response object is a point accuracy metric for the returned `address` feature. This list is subject to change. | Accuracy | Description | | --- | --- | | `rooftop` | Result is for a specific building/entrance | | `parcel` | Result is associated with one or more address within a specified polygonal boundary | | `point` (default) | Result is a known address point but has no specific accuracy | | `interpolated` | Result has been interpolated from an address range | | `intersection` | Result is for a block or intersection | | `approximate` | Result is an approximate location | | `street` | Result is a street centroid | ### Example response: Forward geocoding ```json { "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." } ``` ## 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: | Value | Description | | --- | --- | | `ar` | Features for an Argentinian audience | | `cn` | Features for a mainland Chinese audience | | `in` | Features for an Indian audience | | `jp` | Features for a Japanese audience | | `ma` | Features for a Moroccan audience | | `rs` | Features for a Serbian audience | | `ru` | Features for a Russian audience | | `tr` | Features for a Turkish audience | | `us` | Features 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 Be cautious when combining `worldview` with the `country` parameter, since these indices are only loosely coupled. For example, consider the Ilemi Triangle, which borders Eastern Equatoria (South Sudan) and Turkana (Kenya). While the Geocoding API returns several `place` features inside this disputed region, if you search for Kaaleng in our [Geocoding API Playground example](https://docs.mapbox.com/playground/geocoding/?search_text=Kaaleng), depending on the `worldview` selected, this location will be returned in different country contexts: - If `worldview=cn`, `Kaaleng, Eastern Equatoria, South Sudan` will be returned. - If `worldview=us`, `Kaaleng, Turkana, Kenya` will be returned. This means that if you use `wordlview=cn` worldview with the Kenya (`ke`) country filter, a search for `Kaaleng, Kenya` will not be successful. Instead, you would need to use `worldview=cn` in combination with the South Sudan (`ss`) country filter. For a visual example of how changing the `worldview` value impacts the boundaries shown on a map, see the [companion Maps boundary service](https://docs.mapbox.com/mapbox-gl-js/example/toggle-worldviews/). ## 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` German | `en` English | `es` Spanish | | `fr` French | `it` Italian | `nl` 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` Azerbaijani | `bn` Bengali | `ca` Catalan | | `cs` Czech | `da` Danish | `el` Modern Greek | | `et` Estonian | `fa` Persian | `fi` Finnish | | `ga` Irish | `hu` Hungarian | `id` Indonesian | | `is` Icelandic | `ja` Japanese | `ka` Georgian | | `km` Central Khmer | `ko` Korean | `lt` Lithuanian | | `lv` Latvian | `mk` Macedonian | `mn` Mongolian | | `ms` Malay macrolanguage | `nb` Norwegian Bokmål | `pt` Portuguese | | `ro` Romanian | `sk` Slovak | `sl` Slovenian | | `sq` Albanian | `th` Thai | `tl` Tagalog | | `uk` Ukrainian | `vi` Vietnamese | `zh` Chinese | | `zh_Hans` Simplified Chinese | `zh_Hant` Traditional Chinese | `zh_TW` Taiwanese Mandarin | ### Limited coverage These languages are sometimes present but coverage tends to be inconsistent or geographically constrained. | Language | | | | --- | --- | --- | | `ar` Arabic | `bs` Bosnian | `he` Hebrew | | `hi` Hindi | `kk` Kazakh | `lo` Lao | | `my` Burmese | `ru` Russian | `sr` Serbian | | `sv` Swedish | `te` Telugu | `tk` Turkmen | | `tr` Turkish | — | — | ## Intersection search support **GET** : `https://api.mapbox.com/geocoding/v5/{endpoint}/{street_1}%20and%20{street_2}.json` Intersection search allows users to search for a point where two streets intersect, without a precise address. Make an intersection search request by inserting an `and` or `&` between the two street names. | Required parameters | Type | Description | | --- | --- | --- | | `street_1` | `string` | The first street name in the intersection of two streets, expressed as a URL-encoded UTF-8 string. The street name should include the street abbreviation (for example "ave", "st", "rd"), and the ordinal, if applicable. | | `street_2` | `string` | The second street name in the intersection of two streets, expressed as a URL-encoded UTF-8 string. The street name should include the street abbreviation (for example "ave", "st", "rd"), and the ordinal, if applicable. | | `endpoint` | `string` | One of `mapbox.places` or `mapbox.places-permanent`, as described in the [Endpoints section](#endpoints). | | `types` | `string` | For intersection search, the value of `types` must be `addresses`. | | `proximity` | `string` | Bias 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. | | `access_token` | `string` | A valid Mapbox [access token](https://docs.mapbox.com/api/ja/guides/#access-tokens-and-token-scopes). | ### Example request: Intersection search Intersection search requests made by inserting `and`: ```bash $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/Market%20Street%20and%20Fremont%20Street.json?types=address&proximity=-122.39738575285674,37.7925147111369453&access_token=YOUR_MAPBOX_ACCESS_TOKEN" ``` Intersection search requests made by inserting `&`: ```bash $ curl "https://api.mapbox.com/geocoding/v5/mapbox.places/Market%20Street%20&%20Fremont%20Street.json?types=address&proximity=-122.39738575285674,37.7925147111369453&access_token=YOUR_MAPBOX_ACCESS_TOKEN" ``` ### Response: Intersection search The response from an intersection search query is a GeoJSON feature collection with the `accuracy` property set to `intersection`. For example, a search for the intersection `Market Street and Fremont Street` in San Francisco would look like: ```bash https://api.mapbox.com/geocoding/v5/mapbox.places/Market%20Street%20and%20Fremont%20Street.json?types=address&proximity=-122.39738575285674,37.792514711136945&access_token=YOUR_MAPBOX_ACCESS_TOKEN ``` The corresponding GeoJSON response would be: ```json { "type": "FeatureCollection", "query": ["market", "street", "and", "fremont", "street"], "features": [ { "id": "address.8797576262039554", "type": "Feature", "place_type": ["address"], "relevance": 1, "properties": { "accuracy": "intersection" }, "text": "Fremont Street", "place_name": "Market Street and Fremont Street, San Francisco, California 94105, United States", "center": [-122.3982976, 37.791734], "geometry": { "type": "Point", "coordinates": [-122.3982976, 37.791734] }, "context": [ { "id": "neighborhood.293324", "text": "South Beach" }, { "id": "postcode.17577055718678700", "text": "94105" }, { "id": "place.15734669613361910", "wikidata": "Q62", "text": "San Francisco" }, { "id": "region.11319063928738010", "short_code": "US-CA", "wikidata": "Q99", "text": "California" }, { "id": "country.9053006287256050", "short_code": "us", "wikidata": "Q30", "text": "United States" } ] } ] } ``` Find more details about the format and properties of Geocoding API responses in the [response object section](#geocoding-response-object). ## 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 the URL Restrictions in the Token management guide.
Not Found404Check the endpoint you used in the query.
Not Found404No search_text was 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, address, poi, poi.landmark422Check 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 rate limits To protect the Geocoding API and maximize service stability, Mapbox rate limits Geocoding API requests. - The default Geocoding API rate limit is 600 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. - もし、レート制限をの数を高くしたい場合は、 [お問い合わせください。](https://www.mapbox.com/contact/sales/). ## Geocoding API pricing - **requests** ごとに請求されます - 料金ページの **[Search](https://www.mapbox.com/pricing/#search)** セクションで、Geocoding API request ごとの料金と割引をご確認ください。 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](https://www.mapbox.com/pricing/#search). ### Autocomplete and pricing The Geocoding API's [`autocomplete`](#forward-geocoding) 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 "coff" looking for "coffee shops" 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](https://github.com/mapbox/mapbox-gl-geocoder), which does have that option, or you can write it into your application directly. ### Batch geocoding and pricing [Batch geocoding](#batch-geocoding) allows you to have multiple geocoding queries in a single request. Each individual semicolon-separated search in a batch geocoding request counts as one request. For example, a request that contains three semicolon-separated search strings would count as three requests and be billed as such. These three requests would be reflected on your [statistics graph](https://console.mapbox.com/account/statistics/) and your bill. Batch geocoding is only available using the [`mapbox.places-permanent` endpoint](#endpoints), which is not available by default for all accounts. Requests from accounts without access to the `mapbox.places-permanent` endpoint may still be billable requests, so contact [Mapbox sales](https://www.mapbox.com/contact/sales/) to discuss your use case before testing with this endpoint.../../components/rate-limit-request.js../../components/pricing-product-overview.js