This page includes reference documentation for the Geocoding feature in the Mapbox Search JS Core framework.
A GeocodingCore object is an application's main entrypoint to the Mapbox Geocoding API.
The Geocoding API allows forward (location to coordinates) and reverse (coordinates to location) queries, enabled by corresponding
methods from the GeocodingCore object.
A Mapbox access token is required to use GeocodingCore, and
other options may be specified either in the constructor or in the GeocodingCore#forward or GeocodingCore#reverse calls.
new GeocodingCore(options: <a href="/mapbox-search-js/api/core/geocoding/#geocodingoptions">GeocodingOptions</a>?)
| Name | Description |
|---|---|
| options GeocodingOptions? | |
| options.accessToken string? |
const geocode = new GeocodingCore({ accessToken: 'pk.my-mapbox-access-token' });
const results = await geocode.forward('Washington D.C.');
if (results.features.length === 0) return;
const feature = results.features[0];
doSomethingWithCoordinates(feature);Any default options (GeocodingOptions) to be merged into options in the following methods:
GeocodingCore#forward allows you to look up a feature by name and returns the feature(s) and corresponding geographic coordinates in GeoJSON format.
Legal terms:
Due to legal terms from our data sources, geographic coordinates should be used ephemerally and not persisted.
If the results are to be cached/stored in a customer database,
calls to GeocodingCore#forward should specify permanent: true within the method options argument.
This permanent policy is consistent with the Mapbox Terms of Service and failure to comply may result in modified or discontinued service.
Additionally, the Mapbox Terms of Service states any rendering of a feature suggestion must be using Mapbox map services (for example, displaying results on Google Maps or MapKit JS is not allowed).
Disclaimer:
The failure of Mapbox to exercise or enforce any right or provision of these Terms will not constitute a waiver of such right or provision.
| Name | Description |
|---|---|
| searchText String | |
| optionsArg GeocodingOptions? | |
| optionsArg.signal AbortSignal? |
const results = await geocode.forward('Washington D.C.');
if (results.features.length === 0) return;
const feature = results.features[0];
doSomethingWithCoordinates(feature);GeocodingCore#reverse allows you to look up a single pair of coordinates and returns the geographic feature or features that exist at that location in GeoJSON format.
Legal terms:
Due to legal terms from our data sources, geographic coordinates should be used ephemerally and not persisted.
If the results are to be cached/stored in a customer database,
calls to GeocodingCore#reverse should specify permanent: true within the method options argument.
This permanent policy is consistent with the Mapbox Terms of Service and failure to comply may result in modified or discontinued service.
Additionally, the Mapbox Terms of Service states any rendering of a feature suggestion must be using Mapbox map services (for example, displaying results on Google Maps or MapKit JS is not allowed).
Disclaimer:
The failure of Mapbox to exercise or enforce any right or provision of these Terms will not constitute a waiver of such right or provision.
| Name | Description |
|---|---|
| lngLat (String | LngLatLike) | |
| optionsArg GeocodingOptions? | |
| optionsArg.signal AbortSignal? |
const results = await geocode.reverse({ lat: 40.7736, lng: -73.9749 });
if (results.features.length === 0) return;
const feature = results.features[0];
doSomethingWithFeature(feature);GeocodingCore#suggest is a managed endpoint for an interactive SearchSession, such as one operated through a web or React component. It accepts a search text string for either a GeocodingCore#forward or GeocodingCore#reverse geocoding query and returns a GeocodingResponse object.
| Name | Description |
|---|---|
| searchText String | |
| optionsArg GeocodingOptions? | |
| optionsArg.signal AbortSignal? |
const result = await geocode.suggest('123 Main St');
if (results.features.length === 0) return;
const feature = results.features[0];
doSomethingWithCoordinates(feature);GeocodingCore#retrieve is a managed endpoint for an interactive SearchSession, such as one operated through a web or React component. It accepts a GeocodingFeature object and returns the same object. It is used in a SearchSession to respond to a user's selection of a feature suggestion. Unlike the Search Box API, the Geocoding API returns all feature data in the initial response, so this method does not perform any further data retrieval.
| Name | Description |
|---|---|
| suggestion GeocodingFeature |
Options object for configuring GeocodingCore, mapped to Geocoding API parameters.
| Name | Description |
|---|---|
| autocomplete boolean | When autocomplete is enabled, results will be included that start with the requested string, rather than just responses that match it exactly.
Defaults to true. |
| bbox (string | LngLatBoundsLike) | Limit results to only those contained within the supplied bounding box. |
| country string | Limit results to one or more countries. Permitted values are ISO 3166 alpha 2 country codes separated by commas. |
| language string | An IETF language tag that controls the language of the text supplied in responses, and also affects result scoring. |
| limit number | The number of results to return, up to
10
.
Defaults to 5. |
| permanent boolean | Permanent geocodes are used for use cases that require storing
data indefinitely. If 'true', requests will be made with permanent enabled.
Separate billing for permanent geocoding will apply.
If undefined or 'false', the geocoder will default to use temporary geocoding. Temporary geocoding results are not allowed to be cached. For questions related to permanent resource usage and billing, contact Mapbox sales. |
| proximity (string | LngLatLike) | 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 |
| types (string | Set<FeatureTypes>) | Filter results to include only a subset (one or more) of the available feature types. Multiple options can be comma-separated. |
| worldview string | Available worldviews are:
cn
,
in
,
jp
,
us
. If a worldview is not set,
us
worldview boundaries will be returned.
|
A GeocodingResponse object represents a returned data object from the Mapbox Geocoding API.
| Name | Description |
|---|---|
| attribution string | Attributes the results of the Mapbox Geocoding API to Mapbox. |
| features Array<GeocodingFeature> | The returned feature objects. |
type "FeatureCollection" | "FeatureCollection"
, a GeoJSON type from the
GeoJSON specification
.
|
A GeocodingFeature object represents a GeoJSON feature result from the Mapbox Geocoding API.
Legal terms:
Due to legal terms from our data sources, results from the Mapbox Geocoding API should use the permanent=true flag
if the results are to be cached/stored in a customer database. Otherwise, results should be used ephemerally and not persisted.
This permanent policy is consistent with the Mapbox Terms of Service and failure to comply may result in modified or discontinued service.
Additionally, the Mapbox Terms of Service states any rendering of a feature suggestion must be using Mapbox map services (for example, displaying results on Google Maps or MapKit JS is not allowed).
Disclaimer:
The failure of Mapbox to exercise or enforce any right or provision of these Terms will not constitute a waiver of such right or provision.
Feature id. This property is named "id" to conform to the GeoJSON specification, but is the same id referred to as mapbox_id within the properties object.
Raw GeoJSON feature properties from the Mapbox Geocoding API.
Reference: https://docs.mapbox.com/api/search/geocoding-v6/#geocoding-response-object
| Name | Description |
|---|---|
| bbox LngLatBoundsLike | A bounding box for the feature. This may be significantly
larger than the geometry.
This property is only provided with features of type
country
,
region
,
postcode
,
district
,
place
,
locality
, or
neighborhood
.
|
| context Partial<GeocodingFeatureContext> | Object representing the hierarchy of encompassing parent features. |
| coordinates Coordinates | Coordinate and accuracy data for a geographic feature. |
| feature_type string | A string describing the geographic type of the feature. See FeatureTypes for supported options. |
| full_address string | The full feature text string, combining
name_preferred
and
place_formatted
.
|
| mapbox_id string | Feature id. The
mapbox_id
uniquely identifies a feature 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.
|
| match_code MatchCode | Match codes for each context component of an address, plus an overall match confidence. Provides an indication of how well each part of the address matched the query. |
| name string | Formatted string of the most granular geographical component of the feature. For example, for an address this will be the address number and street. For features known by multiple aliases, this field will represent the alias, if one is available, matching the queried text. |
| name_preferred string | Similar to
name
, except this will always be the 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_formatted string | Formatted string of the feature context (e.g.
place
+
region
+
country
+
postcode
+
counry
). The part of the full feature name which comes after
name
.
|
Object representing the hierarchy of encompassing parent features for a given GeocodingFeature.
| Name | Description |
|---|---|
| address GeocodingFeatureContextComponent | |
| country GeocodingFeatureContextComponent | |
| district GeocodingFeatureContextComponent | |
| locality GeocodingFeatureContextComponent | |
| neighborhood GeocodingFeatureContextComponent | |
| place GeocodingFeatureContextComponent | |
| postcode GeocodingFeatureContextComponent | |
| region GeocodingFeatureContextComponent | |
| street GeocodingFeatureContextComponent |
Address context component. Includes separate address_number and street_name properties.
Region context component. If available, may include additional region_code and region_code_full properties.
Country context component. Includes additional country_code and country_code_alpha_3 properties.
Object representing one level of hierarcy among encompassing parent features for a given GeocodingFeature.
| Name | Description |
|---|---|
| mapbox_id string | The unique Mapbox ID of the context feature. |
| name string | A string representing the feature in the requested language, if specified. |
| wikidata_id string | The Wikidata identifier for the returned feature. |
Geographic feature data types for the Mapbox Geocoding API.
"country" | "region" | "postcode" | "district" | "place" | "locality" | "neighborhood" | "street" | "block" | "address" | "secondary_address")Coordinate and accuracy data for a geographic feature.
| Name | Description |
|---|---|
| accuracy string | A coordinate accuracy indicator for address features. Can be one of
rooftop
,
parcel
,
point
,
interpolated
,
approximate
.
|
| latitude number | The latitude of the feature. |
| longitude number | The longitude of the feature. |
| routable_points Array<RoutablePoint> | Routable point data for an address feature. |