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

# Address Autofill

This page includes reference documentation for the Address Autofill feature in the **Mapbox Search JS Core** framework.

## Class

### AddressAutofillCore

A `AddressAutofillCore` object is an application's main entrypoint to the Mapbox Address Autofill API. The Mapbox Address Autofill API is an API similar to [SearchBoxCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search/#searchboxcore), but targeted towards **address** autocomplete.

Only address types are returned by the API.

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

1.  [AddressAutofillCore#suggest](#addressautofillcore#suggest): The user enters a search term, and a list of suggested results is returned with address data.
2.  [AddressAutofillCore#retrieve](#addressautofillcore#retrieve): The user selects a result from the list of suggested results, and the corresponding geographic coordinates are returned.

A [Mapbox access token](https://docs.mapbox.com/help/glossary/access-token/) is required to use `AddressAutofillCore`, and other options may be specified either in the constructor or in the [AddressAutofillCore#suggest](#addressautofillcore#suggest) call.

> new AddressAutofillCore(options: <a href="#addressautofilloptions">AddressAutofillOptions</a>?)

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

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

#### Parameters

| Name | Description |
| --- | --- |
| **options** [AddressAutofillOptions](#addressautofilloptions)?  |  |
| **options.accessToken** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?  |  |

#### Instance Members

##### accessToken

The [Mapbox access token](https://docs.mapbox.com/help/glossary/access-token/) to use for all requests.

###### Type

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

##### defaults

Any default options ([AddressAutofillOptions](#addressautofilloptions)) to be merged into options in the following methods:

-   [AddressAutofillCore#suggest](#addressautofillcore#suggest)

###### Type

[AddressAutofillOptions](#addressautofilloptions)

### Methods

##### suggest()

[AddressAutofillCore#suggest](#addressautofillcore#suggest) is "part one" of the two-step autofill experience, and includes autofill information.

Suggestion objects **do not include geographic coordinates**. To get the coordinates of the result, use [AddressAutofillCore#retrieve](#addressautofillcore#retrieve).

For tracking purposes, it is useful for any follow-up requests based on this suggestion to include same [SessionToken](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#sessiontoken) as the original request.

If you'd like session tokens to be handled automatically, see [SearchSession](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#searchsession).

###### Parameters

| Name | Description |
| --- | --- |
| **searchText** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  |  |
| **optionsArg** [AddressAutofillOptions](#addressautofilloptions)  |  |
| **optionsArg.sessionToken** [SessionTokenLike](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#sessiontokenlike)  |  |
| **optionsArg.signal** AbortSignal?  |  |

###### Returns

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

##### retrieve()

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

[suggestion](suggestion) is usually a [AddressAutofillSuggestion](#addressautofillsuggestion) returned from "part one," [AddressAutofillCore#suggest](#addressautofillcore#suggest).

**Legal terms:**

Geographic coordinates 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** [AddressAutofillSuggestion](#addressautofillsuggestion)  |  |
| **optionsArg** [AddressAutofillOptions](#addressautofilloptions)  |  |
| **optionsArg.sessionToken** [SessionTokenLike](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#sessiontokenlike)  |  |
| **optionsArg.signal** AbortSignal?  |  |

###### Returns

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

##### canRetrieve()

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

###### Parameters

| Name | Description |
| --- | --- |
| **suggestion** [AddressAutofillSuggestion](#addressautofillsuggestion)  |  |

###### Returns

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

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

## Options and Type Definitions

### AddressAutofillOptions

Options used by [AddressAutofillCore](#addressautofillcore) and [useAddressAutofillCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/react/autofill/#useaddressautofillcore) to control the location, language, country, and limit of results. All properties are optional.

#### Type

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

#### Properties

| Name | Description |
| --- | --- |
| **bbox** ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [LngLatBoundsLike](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglatboundslike))  | Limit results to only those contained within the supplied bounding box. |
| **country** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | An [ISO 3166 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) to be returned. If not specified, results will not be filtered by country. |
| **language** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) to be returned. If not specified, `en` will be used. |
| **limit** ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))  | The number of results to return, up to `10` . |
| **proximity** ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [LngLatLike](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglatlike))  | Bias the response to favor results that are closer to this location. Provide a point coordinate provided as a [LngLatLike](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglatlike) , or use the string `ip` to use the requester's IP address. |
| **streets** ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean))  | If enabled, street results may be returned in addition to addresses. Defaults to `true` . |

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

### AddressAutofillSuggestion

An `AddressAutofillSuggestion` object represents a suggestion result from the Mapbox Address Autofill API.

Suggestion objects are "part one" of the two-step interactive autofill experience. Suggestion objects do not include geographic coordinates.

To get the coordinates of the result, use [AddressAutofillCore#retrieve](#addressautofillcore#retrieve).

For tracking purposes, it is useful for any follow-up requests based on this suggestion to include same [SessionToken](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#sessiontoken) as the original request.

#### Type

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

#### Properties

<table class="table table--fixed table--compact" style="width:100%;table-layout:fixed"><colgroup><col width="28%"><col></colgroup><thead><tr class="bg-gray-faint"><th style="border-top-left-radius:4px">Name</th><th style="border-top-right-radius:4px">Description</th></tr></thead><tbody><tr><td><strong>accuracy</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>A point accuracy metric for the returned address feature. Can be one of <code>rooftop</code> , <code>parcel</code> , <code>point</code> , <code>interpolated</code> , <code>intersection</code> , <code>street</code> .</span></td></tr><tr><td><strong>action</strong>&nbsp;<span>{id: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>}</span>&nbsp;</td><td><span>Action block of the suggestion result. contains id to execute retrieve</span></td></tr><tr><td><strong>address_level1</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Address level 1 from the <a href="https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill">WHATWG Autocomplete Specification</a></span></td></tr><tr><td><strong>address_level2</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Address level 2 from the <a href="https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill">WHATWG Autocomplete Specification</a></span></td></tr><tr><td><strong>address_level3</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Address level 3 from the <a href="https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill">WHATWG Autocomplete Specification</a></span></td></tr><tr><td><strong>address_line1</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Address line 1 from the <a href="https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill">WHATWG Autocomplete Specification</a></span></td></tr><tr><td><strong>address_line2</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Address line 2 from the <a href="https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill">WHATWG Autocomplete Specification</a></span></td></tr><tr><td><strong>address_line3</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Address line 3 from the <a href="https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill">WHATWG Autocomplete Specification</a></span></td></tr><tr><td><strong>context</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&lt;<a href="#addressautofillfeaturecontextcomponent">AddressAutofillFeatureContextComponent</a>&gt;</span>&nbsp;</td><td><span>An array of context objects representing the hierarchy of encompassing parent features for a given feature.</span></td></tr><tr><td><strong>country</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Long form country name, for example: "United States"</span></td></tr><tr><td><strong>country_code</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>The short form country name, for example: "us". This follows the <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166 alpha-2 country code</a> specification.</span></td></tr><tr><td><strong>description</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Additional details, such as city and state for addresses.</span></td></tr><tr><td><strong>feature_name</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>The name of the feature.</span></td></tr><tr><td><strong>full_address</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>The full address of the suggestion.</span></td></tr><tr><td><strong>language</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>The <a href="https://en.wikipedia.org/wiki/IETF_language_tag">IETF language tag</a> of the feature.</span></td></tr><tr><td><strong>maki</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>The name of the <a href="https://labs.mapbox.com/maki-icons/">Maki</a> icon associated with the feature.</span></td></tr><tr><td><strong>mapbox_id</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Feature id. The <code>mapbox_id</code> uniquely identifies a feature in the Mapbox search database.</span></td></tr><tr><td><strong>match_code</strong>&nbsp;<span><a href="#matchcode">MatchCode</a></span>&nbsp;</td><td><span>An object describing the level of confidence that the given response feature matches the address intended by the request query. Includes boolean flags denoting matches for each address sub-component.</span></td></tr><tr><td><strong>matching_name</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>The feature name, as matched by the search algorithm.</span></td></tr><tr><td><strong>metadata</strong>&nbsp;<span>{iso_3166_1: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>}</span>&nbsp;</td><td><span>Address metadata fields of the feature.<p>Includes the short form country name, for example: "us". This follows the <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166 alpha-2 country code</a> specification.</p></span></td></tr><tr><td><strong>place_name</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>A string representing the feature in the requested language, if specified, and its full result hierarchy.</span></td></tr><tr><td><strong>place_type</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&lt;<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>&gt;</span>&nbsp;</td><td><span>An array of strings representing the geographic feature type of the feature. Possible values include "address" and "secondary_address".</span></td></tr><tr><td><strong>postcode</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Postal code.</span></td></tr></tbody></table>

#### Example

```js
const autofill = new AddressAutofillCore({ accessToken: 'pk.my-mapbox-access-token' });

const sessionToken = new SessionToken();
const result = await search.autofill('Washington D.C.', { sessionToken });
if (result.suggestions.length === 0) return;

const suggestion = result.suggestions[0];
const { features } = await autofill.retrieve(suggestion, { sessionToken });
doSomethingWithCoordinates(features);
```

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

### AddressAutofillFeatureSuggestion

An `AddressAutofillFeatureSuggestion` object represents [GeoJSON](https://docs.mapbox.com/help/glossary/geojson/) suggestion results from the Mapbox Address Autofill API.

As per the Mapbox Address Autofill API, this will always be [Point](https://geojson.org/geojson-spec.html#point).

#### Type

any

#### Example

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

#### Static Members

##### bbox

A bounding box for the feature. This may be significantly larger than the geometry.

###### Type

[LngLatBoundsLike](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglatboundslike)

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

### AddressAutofillFeatureContextComponent

Object representing one level of hierarcy among encompassing parent features for a given [AddressAutofillSuggestion](#addressautofillsuggestion).

#### Type

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

#### Properties

| Name | Description |
| --- | --- |
| **id** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | An identifier prefixed with the component type, for example `country.123` . |
| **mapbox_id** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The unique Mapbox ID of the context feature. |
| **text** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | A string representing the feature in the requested language, if specified. |
| **wikidata_id** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The [Wikidata](https://wikidata.org/) identifier for the returned feature. |

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

### AddressAutofillSuggestionResponse

Response object returned when calling the `suggest` method of [AddressAutofillCore](#addressautofillcore)

#### Type

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

#### Properties

| Name | Description |
| --- | --- |
| **attribution** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The attribution data for results. |
| **suggestions** [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[AddressAutofillSuggestion](#addressautofillsuggestion)>  | The returned suggestion objects. |

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

### AddressAutofillRetrieveResponse

Response object returned when calling the `retrieve` method of [AddressAutofillCore](#addressautofillcore)

#### Type

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

#### Properties

| Name | Description |
| --- | --- |
| **attribution** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The attribution data for results. |
| **features** [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[AddressAutofillFeatureSuggestion](#addressautofillfeaturesuggestion)>  | The returned feature objects. |

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

### MatchCode

An object describing the level of confidence that the given response feature matches the address intended by the request query.

#### Type

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

#### Properties

| Name | Description |
| --- | --- |
| **address_number** [MatchCodeType](#matchcodetype)  | An indication of how well the `address_number` component of the feature matches the query. |
| **confidence** [MatchCodeConfidence](#matchcodeconfidence)  | An overall confidence level for how well the feature matches the query. |
| **country** [MatchCodeType](#matchcodetype)  | An indication of how well the `country` component of the feature matches the query. |
| **locality** [MatchCodeType](#matchcodetype)  | An indication of how well the `locality` component of the feature matches the query. |
| **place** [MatchCodeType](#matchcodetype)  | An indication of how well the `place` component of the feature matches the query. |
| **postcode** [MatchCodeType](#matchcodetype)  | An indication of how well the `postcode` component of the feature matches the query. |
| **region** [MatchCodeType](#matchcodetype)  | An indication of how well the `region` component of the feature matches the query. |
| **secondary_address** [MatchCodeType](#matchcodetype)  | An indication of how well the `secondary_address` component of the feature matches the query. |
| **street** [MatchCodeType](#matchcodetype)  | An indication of how well the `street` component of the feature matches the query. |

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

### MatchCodeType

An indication of how well a context component of the feature matches the query.

#### Static Members

##### matched

The component value matches the user's input.

###### Type

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

##### unmatched

The component value doesn't match the user's input, or the user didn't submit this component type as part of the query.

###### Type

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

##### plausible

Only relevant for the `address_number` and `secondary_address` components. In the case of `address_number`, this means the address accuracy is interpolated. In the case of `secondary_address`, this means the secondary address was extrapolated, i.e. the primary address is known to have secondary addresses, but the geocoder did not find a specific matching secondary address in our data.

###### Type

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

##### not_applicable

The component is not used in the postal address string representation of the feature.

###### Type

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

##### inferred

The component type wasn't submitted as part of the query, but we were able to confidently fill in the value. Only returned for the `country` component.

###### Type

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

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

### MatchCodeConfidence

An overall confidence level for how well the feature matches the query.

#### Static Members

##### exact

An exact match.

###### Type

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

##### high

High confidence of a match.

###### Type

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

##### medium

Medium confidence of a match.

###### Type

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

##### low

Low confidence of a match.

###### Type

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

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