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, 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: The user enters a search term, and a list of suggested results is returned with address data.
  2. AddressAutofillCore#retrieve: The user selects a result from the list of suggested results, and the corresponding geographic coordinates are returned.

A Mapbox access token is required to use AddressAutofillCore, and other options may be specified either in the constructor or in the AddressAutofillCore#suggest call.

new AddressAutofillCore(options: <a href="/mapbox-search-js/api/core/autofill/#addressautofilloptions">AddressAutofillOptions</a>?)

Parameters

NameDescription
options AddressAutofillOptions? 
options.accessToken string? 

Instance Members

The Mapbox access token to use for all requests.

Type
string

Any default options (AddressAutofillOptions) to be merged into options in the following methods:

Type
AddressAutofillOptions

Methods

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.

For tracking purposes, it is useful for any follow-up requests based on this suggestion to include same SessionToken as the original request.

If you'd like session tokens to be handled automatically, see SearchSession.

Parameters
NameDescription
searchText string 
optionsArg AddressAutofillOptions 
optionsArg.sessionToken SessionTokenLike 
optionsArg.signal AbortSignal? 
Returns
Promise<AddressAutofillSuggestionResponse>

AddressAutofillCore#retrieve is "part two" of the two-step autofill experience and includes geographic coordinates in GeoJSON format.

suggestion is usually a AddressAutofillSuggestion returned from "part one," AddressAutofillCore#suggest.

Legal terms:

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

Parameters
NameDescription
suggestion AddressAutofillSuggestion 
optionsArg AddressAutofillOptions 
optionsArg.sessionToken SessionTokenLike 
optionsArg.signal AbortSignal? 
Returns
Promise<AddressAutofillRetrieveResponse>

Returns true if AddressAutofillCore#retrieve can be called on this suggestion, false otherwise.

Parameters
NameDescription
suggestion AddressAutofillSuggestion 
Returns
boolean
Was this section on AddressAutofillCore helpful?YesNo

Options and Type Definitions

AddressAutofillOptions

Options used by AddressAutofillCore and useAddressAutofillCore to control the location, language, country, and limit of results. All properties are optional.

Type

Object

Properties

NameDescription
bbox (string | LngLatBoundsLike) Limit results to only those contained within the supplied bounding box.
country string An ISO 3166 alpha-2 country code to be returned. If not specified, results will not be filtered by country.
language string The IETF language tag to be returned. If not specified, en will be used.
limit (string | number) The number of results to return, up to 10 .
proximity (string | LngLatLike) Bias the response to favor results that are closer to this location. Provide a point coordinate provided as a LngLatLike , or use the string ip to use the requester's IP address.
streets (string | boolean) If enabled, street results may be returned in addition to addresses. Defaults to true .
Was this section on AddressAutofillOptions helpful?YesNo

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.

For tracking purposes, it is useful for any follow-up requests based on this suggestion to include same SessionToken as the original request.

Type

Object

Properties

NameDescription
accuracy string A point accuracy metric for the returned address feature. Can be one of rooftop , parcel , point , interpolated , intersection , street .
action {id: string} Action block of the suggestion result. contains id to execute retrieve
address_level1 string Address level 1 from the WHATWG Autocomplete Specification
address_level2 string Address level 2 from the WHATWG Autocomplete Specification
address_level3 string Address level 3 from the WHATWG Autocomplete Specification
address_line1 string Address line 1 from the WHATWG Autocomplete Specification
address_line2 string Address line 2 from the WHATWG Autocomplete Specification
address_line3 string Address line 3 from the WHATWG Autocomplete Specification
context Array<AddressAutofillFeatureContextComponent> An array of context objects representing the hierarchy of encompassing parent features for a given feature.
country string Long form country name, for example: "United States"
country_code string The short form country name, for example: "us". This follows the ISO 3166 alpha-2 country code specification.
description string Additional details, such as city and state for addresses.
feature_name string The name of the feature.
full_address string The full address of the suggestion.
language string The IETF language tag of the feature.
maki string The name of the Maki icon associated with the feature.
mapbox_id string Feature id. The mapbox_id uniquely identifies a feature in the Mapbox search database.
match_code MatchCode 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.
matching_name string The feature name, as matched by the search algorithm.
metadata {iso_3166_1: string} Address metadata fields of the feature.

Includes the short form country name, for example: "us". This follows the ISO 3166 alpha-2 country code specification.

place_name string A string representing the feature in the requested language, if specified, and its full result hierarchy.
place_type Array<string> An array of strings representing the geographic feature type of the feature. Possible values include "address" and "secondary_address".
postcode string Postal code.

Example

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?YesNo

AddressAutofillFeatureSuggestion

An AddressAutofillFeatureSuggestion object represents GeoJSON suggestion results from the Mapbox Address Autofill API.

As per the Mapbox Address Autofill API, this will always be Point.

Type

any

Example

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

Static Members

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

Type
LngLatBoundsLike
Was this section on AddressAutofillFeatureSuggestion helpful?YesNo

AddressAutofillFeatureContextComponent

Object representing one level of hierarcy among encompassing parent features for a given AddressAutofillSuggestion.

Type

Object

Properties

NameDescription
id string An identifier prefixed with the component type, for example country.123 .
mapbox_id string The unique Mapbox ID of the context feature.
text string A string representing the feature in the requested language, if specified.
wikidata_id string The Wikidata identifier for the returned feature.
Was this section on AddressAutofillFeatureContextComponent helpful?YesNo

AddressAutofillSuggestionResponse

Response object returned when calling the suggest method of AddressAutofillCore

Type

Object

Properties

NameDescription
attribution string The attribution data for results.
suggestions Array<AddressAutofillSuggestion> The returned suggestion objects.
Was this section on AddressAutofillSuggestionResponse helpful?YesNo

AddressAutofillRetrieveResponse

Response object returned when calling the retrieve method of AddressAutofillCore

Type

Object

Properties

NameDescription
attribution string The attribution data for results.
features Array<AddressAutofillFeatureSuggestion> The returned feature objects.
Was this section on AddressAutofillRetrieveResponse helpful?YesNo

MatchCode

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

Type

Object

Properties

NameDescription
address_number MatchCodeType An indication of how well the address_number component of the feature matches the query.
confidence MatchCodeConfidence An overall confidence level for how well the feature matches the query.
country MatchCodeType An indication of how well the country component of the feature matches the query.
locality MatchCodeType An indication of how well the locality component of the feature matches the query.
place MatchCodeType An indication of how well the place component of the feature matches the query.
postcode MatchCodeType An indication of how well the postcode component of the feature matches the query.
region MatchCodeType An indication of how well the region component of the feature matches the query.
secondary_address MatchCodeType An indication of how well the secondary_address component of the feature matches the query.
street MatchCodeType An indication of how well the street component of the feature matches the query.
Was this section on MatchCode helpful?YesNo

MatchCodeType

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

Static Members

The component value matches the user's input.

Type
string

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

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

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

Type
string

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
Was this section on MatchCodeType helpful?YesNo

MatchCodeConfidence

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

Static Members

An exact match.

Type
string

High confidence of a match.

Type
string

Medium confidence of a match.

Type
string

Low confidence of a match.

Type
string
Was this section on MatchCodeConfidence helpful?YesNo