Beta
Mapbox Search JS

Search session

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.

SearchSession

A SearchSession object is a managed entrypoint to the Mapbox Search API or Mapbox Autocomplete API.

SearchSession abstracts the suggest/retrieve flow of the two-step interactive search experience.

Compared to using these APIs directly, you can use a SearchSession to:

  1. Automatically manage the session token lifecycle.
  2. Debounce calls to SearchSession#suggest.
  3. Abort in-flight requests with an imperative API.
new SearchSession(search: (MapboxSearch | MapboxAutofill), wait: number)

Parameters

search((MapboxSearch | MapboxAutofill))The search interface to wrap.
wait(number)The time in milliseconds to wait before sending a new request to the SearchSession#suggest call.

Example

const search = new MapboxSearch({ accessToken: 'pk.my-mapbox-access-token' });
const session = new SearchSession(search);
session.addEventListener('suggest', (res) => {
presentResultsToUser(res.suggestions);
});
session.addEventListener('retrieve', (res) => {
doSomethingWithFeatureCollection(res);
});
document.querySelector('button').addEventListener('click', (event) => {
const suggestions = session.suggestions?.suggestions;
if (!suggestions || !suggestions.length) {
return;
}
const suggestion = suggestions[0];
if (session.canRetrieve(suggestion)) {
session.retrieve(suggestion);
} else if (session.canSuggest(suggestion)) {
// .. go through suggest flow again ..
session.suggest(suggestion.text);
}
});
session.suggest('Washington D.C.');

Instance Members

Methods

SessionToken

A SessionToken object is a unique identifier that groups together suggest / retrieve calls as part of the Mapbox Search API.

Session tokens are used for billing and customer-accessible analytics.

A UUIDv4 value is recommended, and is generated if an id is not provided.

Note that any method that accepts a SessionToken object as an argument or option can also accept a unique string and will perform an implicit conversion. This flexible type is documented as SessionTokenLike.

Example

const token = new SessionToken();
console.log(token.id); // = I am a UUIDv4 value!

Static Members

Instance Members

SessionTokenLike

A SessionToken object or string representing a Mapbox Search API session token.

It's recommended this value is a UUIDv4 value.

(SessionToken | string)

Example

const v1 = new SessionToken();
const v2 = new SessionToken('f06e7531-6373-4d5a-8614-b6f313488050');
const v3 = 'f06e7531-6373-4d5a-8614-b6f313488050';

Evented

Evented mixes methods into other classes for event capabilities.

If you are an end-user, you will most likely use these methods through classes like SearchSession.

For lists of events you can listen for, see API documentation for specific classes.

new Evented()

Instance Members