> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/mapbox-search-js/llms.txt)

# Search session

This page includes reference documentation for the SearchSession class in the **Mapbox Search JS Core** framework.

### SearchSession

A `SearchSession` object is a managed entrypoint to the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/) 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:

1.  Automatically manage the session token lifecycle.
2.  Debounce calls to [SearchSession#suggest](#searchsession#suggest).
3.  Abort in-flight requests with an imperative API.

> 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>)

#### Import[​](#import)

```javascript
import { SearchSession } from '@mapbox/search-js-core'
```

#### Parameters

| Name | Description |
| --- | --- |
| **search** ([SearchBoxCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search/#searchboxcore) \| [AddressAutofillCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/autofill/#addressautofillcore))  | The search interface to wrap. |
| **wait** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | The time in milliseconds to wait before sending a new request to the [SearchSession#suggest](#searchsession#suggest) call. |

#### Example

```js
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.');
```

#### Instance Members

##### debounce

The time in milliseconds to wait before sending a new request to the [SearchSession#suggest](#searchsession#suggest) call.

###### Type

[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)

##### sessionToken

The session token is an SKU (billing token) used to identify the current search session and provide analytics to the customer.

As per [SessionToken](#sessiontoken), this is a UUIDv4 value.

###### Type

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

###### Returns

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

##### suggestions

The suggestions from the last successful suggest call, if any.

###### Type

(SuggestionResponse \| null)

###### Returns

(SuggestionResponse \| null)

### Methods

##### suggest()

[SearchSession#suggest](#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](#searchsession#retrieve).

It may be useful to call [SearchSession#canRetrieve](#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](#searchsession#cansuggest), and further calls to [SearchSession#suggest](#searchsession#suggest).

Results can be retrieved with the "suggest" event.

###### Parameters

| Name | Description |
| --- | --- |
| **searchText** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  |  |
| **options** Partial<Options>?  |  |

###### Returns

[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<SuggestionResponse>

#### Import[​](#import)

```javascript
import { suggest } from '@mapbox/search-js-core'
```

###### Example

```js
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.');
```

##### clear()

Clears the current suggestions.

###### Returns

void

##### retrieve()

[SearchSession#retrieve](#searchsession#retrieve) is "part two" of the two-step interactive search experience and includes geographic coordinates in [GeoJSON](https://docs.mapbox.com/help/glossary/geojson/) format.

[suggestion](suggestion) is usually a [Suggestion](Suggestion) returned from "part one," [SearchSession#suggest](#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](https://www.mapbox.com/tos/) and failure to comply may result in modified or discontinued service.

Additionally, the [Mapbox Terms of Service](https://www.mapbox.com/tos/) 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.

###### Parameters

| Name | Description |
| --- | --- |
| **suggestion** Suggestion  |  |
| **options** Partial<Options>?  |  |

###### Returns

[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<RetrieveResponse>

##### canRetrieve()

Returns true if [SearchSession#retrieve](#searchsession#retrieve) can be called on this suggestion, false otherwise.

This indicates the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/) has geographic coordinates for this suggestion.

This method is mutually exclusive with [SearchSession#canSuggest](#searchsession#cansuggest).

###### Parameters

| Name | Description |
| --- | --- |
| **suggestion** Suggestion  |  |

###### Returns

[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)

##### canSuggest()

Returns true if [SearchSession#suggest](#searchsession#suggest) can be called on this suggestion, false otherwise.

This indicates the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/) wants to do another suggestion search on this result, and does not have geographic coordinates.

This method is mutually exclusive with [SearchSession#canRetrieve](#searchsession#canretrieve).

###### Parameters

| Name | Description |
| --- | --- |
| **suggestion** Suggestion  |  |

###### Returns

[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)

##### abort()

Aborts the current [SearchSession#suggest](#searchsession#suggest) request.

###### Returns

void

##### incrementSession()

Increments the session counter.

###### Returns

void

Was this section on SearchSession helpful?[Yes](null)[No](null)

### SessionToken

A `SessionToken` object is a unique identifier that groups together `suggest` / `retrieve` calls as part of the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/#retrieve-a-suggested-feature).

Session tokens are used for [billing](https://docs.mapbox.com/api/search/search-box/#search-box-api-pricing) and customer-accessible analytics.

Calling `SessionToken` will return an `id` with a [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) 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](#sessiontokenlike).

Note that when using the `SearchSession` class, the `SessionToken` is automatically managed by `SearchSession`.

#### Example

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

#### Static Members

##### convert()

Converts a string to a `SessionToken` object.

If a `SessionToken` object is passed in, the function returns a copy.

###### Parameters

| Name | Description |
| --- | --- |
| **token** ([SessionToken](#sessiontoken) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))  |  |

###### Returns

[SessionToken](#sessiontoken)

#### Instance Members

##### id

The session token in string format.

###### Type

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

##### toString()

Returns the session token in string format.

This is the same as calling `token.id`, and is okay to be used for serialization.

###### Returns

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

Was this section on SessionToken helpful?[Yes](null)[No](null)

### SessionTokenLike

A [SessionToken](#sessiontoken) object or string representing a Mapbox Search Box API session token.

It's recommended this value is a [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) value.

#### Type

([SessionToken](#sessiontoken) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))

#### Example

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

Was this section on SessionTokenLike helpful?[Yes](null)[No](null)

### 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](#searchsession).

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

> new Evented()

#### Import[​](#import)

```javascript
import { Evented } from '@mapbox/search-js-core'
```

#### Instance Members

##### addEventListener()

Adds a listener to a specified event type.

###### Parameters

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

###### Returns

void

##### removeEventListener()

Removes a previously registered event listener.

###### Parameters

| Name | Description |
| --- | --- |
| **type** K  | The event type to remove listeners for. |
| **listener** function (arg0: any): void  | The listener function to remove. |

###### Returns

void

Was this section on Evented helpful?[Yes](null)[No](null)