BETA
Mapbox Search JS
All docschevron-rightMapbox Search JSchevron-rightarrow-leftCore Referencechevron-rightSearch Box

Search Box

lightning
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.

SearchBoxCore

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

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

  1. SearchBoxCore#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. SearchBoxCore#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 SearchBoxCore, and other options may be specified either in the constructor or in the SearchBoxCore#suggest call.

new SearchBoxCore(options: SearchBoxOptions?)

Parameters

options(SearchBoxOptions?)
NameDescription
options.accessToken
string?

Example

const search = new SearchBoxCore({ 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];
const { features } = await search.retrieve(suggestion, { sessionToken });
doSomethingWithCoordinates(features);

Instance Members

SearchBoxOptions

Instance Members

SearchBoxSuggestion

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

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

SearchBoxSuggestion objects do not include geographic coordinates. To get the coordinates of the result, use SearchBoxCore#retrieve.

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-box/#response-get-suggested-results

Example

const search = new SearchBoxCore({ 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];
 
const { features } = await search.retrieve(suggestion, { sessionToken });
doSomethingWithCoordinates(features);

Instance Members

SearchBoxFeatureSuggestion

A SearchBoxFeatureSuggestion object represents a GeoJSON suggestion result from the Mapbox Search Box 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 Box API, this will always be Point.

Legal terms:

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

GeoJSON.Feature<GeoJSON.Point, SearchBoxFeatureProperties>

Example

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

SearchBoxFeatureProperties

Raw GeoJSON feature properties from the Mapbox Search Box API.

Reference: https://docs.mapbox.com/api/search/search-box/#response-retrieve-a-suggested-feature

Extends Omit<SearchBoxSuggestion, 'distance' | 'eta' | 'added_distance' | 'added_time'>.

Instance Members

SearchBoxSuggestionResponse

Instance Members

SearchBoxRetrieveResponse

Instance Members

SearchBoxAdministrativeUnitTypes

Administrative unit types for the Mapbox Search Box API.

Type

("country" | "region" | "postcode" | "district" | "place" | "locality" | "neighborhood" | "street" | "address" | "block")