Beta
Mapbox Search JS

Search

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.

Private beta for Mapbox Search API

The Mapbox Search API is in private beta for worldwide coverage and in public beta for Japan. Unless you are part of the private beta program, the Mapbox Search API is only available for Japanese-language queries for locations in Japan.

Stay tuned for upcoming updates to Mapbox Search JS that will additionally enable use of publicly available Mapbox APIs.

MapboxSearch

A MapboxSearch object is an application's main entrypoint to the Mapbox Search API.

MapboxSearch is focused on the two-step, interactive search experience. These steps are:

  1. MapboxSearch#suggest: The user enters a search term, and a list of suggested results is returned with optional data such as: eta, distance calculations, etc.
  2. MapboxSearch#retrieve: The user selects a result from the list of suggested results, and the corresponding geographic coordinates are returned for displaying on a map or otherwise manipulating.

A Mapbox access token is required to use MapboxSearch, and other options may be specified either in the constructor or in the MapboxSearch#suggest call.

new MapboxSearch(options: Options?)

Parameters

options(Options?)
NameDescription
options.accessToken
string?

Example

const search = new MapboxSearch({ accessToken: 'pk.my-mapbox-access-token' });
const sessionToken = new SessionToken();
const result = await search.suggest('Washington D.C.', { sessionToken });
if (result.suggestions.length === 0) return;
const suggestion = result.suggestions[0];
if (search.canRetrieve(suggestion)) {
const { features } = await search.retrieve(suggestion, { sessionToken });
doSomethingWithCoordinates(features);
} else if (search.canSuggest(suggestion)) {
// .. go through suggest flow again ..
}

Instance Members

Options

Instance Members

Suggestion

A Suggestion object represents a suggestion result from the Mapbox Search API.

Suggestion objects are "part one" of the two-step interactive search experience, and include useful information about the result, such as: Suggestion#feature_name, Suggestion#description, and Suggestion#maki.

Suggestion objects do not include geographic coordinates. To get the coordinates of the result, use MapboxSearch#retrieve. It may be useful to call MapboxSearch#canRetrieve before calling this method, as the suggestion may be a reference to another suggest query. This can also be tested with MapboxSearch#canSuggest, and called with MapboxSearch#suggest.

For tracking purposes, it is useful for any follow-up requests based on this suggestion to include same SessionToken as the original request.

Reference: https://docs.mapbox.com/api/search/search/#response-retrieve-a-suggestion

Example

const search = new MapboxSearch({ accessToken: 'pk.my-mapbox-access-token' });
const sessionToken = new SessionToken();
const result = await search.suggest('Washington D.C.', { sessionToken });
if (result.suggestions.length === 0) return;
const suggestion = result.suggestions[0];
if (search.canRetrieve(suggestion)) {
const { features } = await search.retrieve(suggestion, { sessionToken });
doSomethingWithCoordinates(features);
} else if (search.canSuggest(suggestion)) {
// .. go through suggest flow again ..
}

Instance Members

FeatureSuggestion

A FeatureSuggestion object represents a GeoJSON suggestion result from the Mapbox Search API.

Feature suggestions are "part two" of the two-step interactive search experience and includes geographic coordinates. Multiple feature suggestions may be returned from a single search query, for example in an airport with multiple terminals.

As per the Mapbox Search API, this will always be Point.

Legal terms:

Due to legal terms from our data sources, feature suggestions from the Mapbox Search API should come from the permanentForward & permanentReverse methods 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.

any

Example

const featureSuggestion = {
type: 'Feature',
geometry: {
type: 'Point',
coordinates: [0,0]
},
properties: {
feature_name: 'Washington D.C.',
}
};

Static Members

AdministrativeUnitTypes

Administrative unit types for the Mapbox Search API.

("country" | "region" | "prefecture" | "postcode" | "district" | "place" | "city" | "locality" | "oaza" | "neighborhood" | "chome" | "block" | "street" | "address")