Geocoding
This page includes reference documentation for the Geocoding feature in the Mapbox Search JS Core framework.
Class
GeocodingCore
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.
Parameters
Example
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);
Instance Members
Programmatic search
Interactive search
Options and Type Definitions
GeocodingOptions
ObjectProperties
(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.
((string | LngLatBoundsLike)): Limit results to only those contained within the supplied bounding box.
(string): Limit results to one or more countries. Permitted values are
ISO 3166 alpha 2
country codes separated by commas.
(string): An
IETF language tag
that controls the language of the text supplied in responses, and also affects result scoring.
(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.
((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 ip to bias based on reverse IP lookup.
((string | Set<FeatureTypes>)): Filter results to include only a subset (one or more) of the available feature types. Multiple options can be comma-separated.
(string): Available worldviews are:
cn
,
in
,
jp
,
us
. If a worldview is not set,
us
worldview boundaries will be returned.
GeocodingResponse
A GeocodingResponse object represents a returned data object from the Mapbox Geocoding API.
Properties
GeocodingFeature
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.
anyStatic Members
Related
GeocodingFeatureProperties
Raw GeoJSON feature properties from the Mapbox Geocoding API.
Reference: https://docs.mapbox.com/api/search/geocoding-v6/#geocoding-response-object
ObjectProperties
(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
.
(Partial<GeocodingFeatureContext>): Object representing the hierarchy of encompassing parent features.
(string): A string describing the geographic type of the feature. See
FeatureTypes
for supported options.
(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.
(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.
(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.
(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.
(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
.
GeocodingFeatureContext
Object representing the hierarchy of encompassing parent features for a given GeocodingFeature.
{address: GeocodingFeatureContextComponent, street: GeocodingFeatureContextComponent, neighborhood: GeocodingFeatureContextComponent, postcode: GeocodingFeatureContextComponent, locality: GeocodingFeatureContextComponent, place: GeocodingFeatureContextComponent, district: GeocodingFeatureContextComponent, region: GeocodingFeatureContextComponent, country: GeocodingFeatureContextComponent}Properties
(GeocodingFeatureContextComponent)(GeocodingFeatureContextComponent)(GeocodingFeatureContextComponent)(GeocodingFeatureContextComponent)(GeocodingFeatureContextComponent)(GeocodingFeatureContextComponent)(GeocodingFeatureContextComponent)(GeocodingFeatureContextComponent)Static Members
GeocodingFeatureContextComponent
Object representing one level of hierarcy among encompassing parent features for a given GeocodingFeature.
ObjectProperties
FeatureTypes
Geographic feature data types for the Mapbox Geocoding API.
("country" | "region" | "postcode" | "district" | "place" | "locality" | "neighborhood" | "street" | "block" | "address" | "secondary_address")Related
Coordinates
Coordinate and accuracy data for a geographic feature.
ObjectProperties
(string): A coordinate accuracy indicator for address features. Can be one of
rooftop
,
parcel
,
point
,
interpolated
,
approximate
.