Skip to main content

Search Box

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

Was this section on SearchBoxCore helpful?

SearchBoxOptions

Instance Members

Was this section on SearchBoxOptions helpful?

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

Was this section on SearchBoxSuggestion helpful?

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.

GeoJSON.Feature<GeoJSON.Point, SearchBoxFeatureProperties>

Example

const featureSuggestion = {
type: 'Feature',
geometry: {
type: 'Point',
coordinates: [0,0]
},
properties: {
name: 'Washington D.C.',
}
};
Was this section on SearchBoxFeatureSuggestion helpful?

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

Was this section on SearchBoxFeatureProperties helpful?
Was this section on SearchBoxSuggestionResponse helpful?
Was this section on SearchBoxRetrieveResponse helpful?

SearchBoxAdministrativeUnitTypes

Administrative unit types for the Mapbox Search Box API.

("country" | "region" | "postcode" | "district" | "place" | "locality" | "neighborhood" | "street" | "address" | "block")
Was this section on SearchBoxAdministrativeUnitTypes helpful?
Was this page helpful?