Geocoding | Mapbox Search JS

Public beta for Mapbox Search JS

Mapbox Search JS is in public beta. During the public beta phase, frameworks may be subject to potential changes as they stabilize.

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: GeocodingOptions?)

Parameters

options(GeocodingOptions?)

Name	Description
options.accessToken `string?`

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

Was this section on GeocodingCore helpful?

Options and Type Definitions

GeocodingOptions

Type

Object

Properties

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 ip to bias based on reverse IP lookup.

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.

Was this section on GeocodingOptions helpful?

GeocodingResponse

A GeocodingResponse object represents a returned data object from the Mapbox Geocoding API.

Type

Object

Properties

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 .

Was this section on GeocodingResponse helpful?

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.

Type

any

Static Members

Geocoding response object

Was this section on GeocodingFeature helpful?

GeocodingFeatureProperties

Raw GeoJSON feature properties from the Mapbox Geocoding API.

Reference: https://docs.mapbox.com/api/search/geocoding-v6/#geocoding-response-object

Type

Object

Properties

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 .

Was this section on GeocodingFeatureProperties helpful?