This page includes reference documentation for the SearchSession class in the Mapbox Search JS Core framework.
A SearchSession object is a managed entrypoint to the Mapbox Search Box API
or Mapbox Address Autofill 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:
new SearchSession(search: (<a href="/mapbox-search-js/api/core/search/#searchboxcore">SearchBoxCore</a> | <a href="/mapbox-search-js/api/core/autofill/#addressautofillcore">AddressAutofillCore</a>), wait: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)
| Name | Description |
|---|---|
| search (SearchBoxCore | AddressAutofillCore) | The search interface to wrap. |
| wait number | The time in milliseconds to wait before sending a new request to the SearchSession#suggest call. |
const search = new SearchBoxCore({ 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.');The time in milliseconds to wait before sending a new request to the SearchSession#suggest call.
The session token is an SKU (billing token) used to identify the current search session and provide analytics to the customer.
As per SessionToken, this is a UUIDv4 value.
The suggestions from the last successful suggest call, if any.
SearchSession#suggest is "part one" of the two-step interactive search experience, and each suggestion includes metadata to present to the user.
Suggestion objects do not include geographic coordinates. To get the coordinates of the result, use SearchSession#retrieve.
It may be useful to call SearchSession#canRetrieve before calling this method, as the suggestion may be a reference to another suggest query. This can also be tested with SearchSession#canSuggest, and further calls to SearchSession#suggest.
Results can be retrieved with the "suggest" event.
| Name | Description |
|---|---|
| searchText string | |
| options Partial<Options>? |
const search = new SearchBoxCore({ accessToken: 'pk.my-mapbox-access-token' });
const session = new SearchSession(search);
session.addEventListener('suggest', (res) => {
presentResultsToUser(res.suggestions);
});
session.suggest('Washington D.C.');Clears the current suggestions.
SearchSession#retrieve is "part two" of the two-step interactive search experience and includes geographic coordinates in GeoJSON format.
suggestion is usually a Suggestion returned from "part one," SearchSession#suggest.
Multiple feature suggestions may be returned from a single search query, for example in an airport with multiple terminals.
Legal terms:
Due to legal terms from our data sources, results should not be stored in a customer database. 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.
| Name | Description |
|---|---|
| suggestion Suggestion | |
| options Partial<Options>? |
Returns true if SearchSession#retrieve can be called on this suggestion, false otherwise.
This indicates the Mapbox Search Box API has geographic coordinates for this suggestion.
This method is mutually exclusive with SearchSession#canSuggest.
| Name | Description |
|---|---|
| suggestion Suggestion |
Returns true if SearchSession#suggest can be called on this suggestion, false otherwise.
This indicates the Mapbox Search Box API wants to do another suggestion search on this result, and does not have geographic coordinates.
This method is mutually exclusive with SearchSession#canRetrieve.
| Name | Description |
|---|---|
| suggestion Suggestion |
Increments the session counter.
A SessionToken object is a unique identifier that groups together suggest / retrieve calls as part of the
Mapbox Search Box API.
Session tokens are used for billing and customer-accessible analytics.
Calling SessionToken will return an id with a UUIDv4 value. If you want to manage the token id yourself, you
can pass your value into SessionToken (a UUIDv4 value is recommended).
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.
Note that when using the SearchSession class, the SessionToken is automatically managed by SearchSession.
const token = new SessionToken();
console.log(token.id); // = I am a UUIDv4 value!Converts a string to a SessionToken object.
If a SessionToken object is passed in, the function returns a copy.
| Name | Description |
|---|---|
| token (SessionToken | string) |
Returns the session token in string format.
This is the same as calling token.id, and is okay to be used for serialization.
A SessionToken object or string representing a Mapbox Search Box API session token.
It's recommended this value is a UUIDv4 value.
const v1 = new SessionToken();
const v2 = new SessionToken('f06e7531-6373-4d5a-8614-b6f313488050');
const v3 = 'f06e7531-6373-4d5a-8614-b6f313488050';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()
Adds a listener to a specified event type.
| Name | Description |
|---|---|
| type K | The event type to add a listen for. |
| listener function (arg0: any): void | The function to be called when the event is fired. |
Removes a previously registered event listener.
| Name | Description |
|---|---|
| type K | The event type to remove listeners for. |
| listener function (arg0: any): void | The listener function to remove. |