Search Box

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.

This page includes reference documentation for Search Box in the Mapbox Search JS Core framework.

Class

SearchBoxCore

A SearchBoxCore object is an application's main entrypoint to the Mapbox Search Box API.

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

SearchBoxCore#suggest: The user enters a search term, and a list of suggested results is returned with optional data such as: eta, distance calculations, etc.
SearchBoxCore#retrieve: The user selects a result from the list of suggested results, and the corresponding geographic coordinates are returned for displaying on a map or otherwise manipulating.

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

new SearchBoxCore(options: SearchBoxOptions?)

Parameters

options(SearchBoxOptions?)

Name	Description
options.accessToken `string?`

Example

const search = new SearchBoxCore({ accessToken: 'pk.my-mapbox-access-token' });

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

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

Programmatic search

Was this section on SearchBoxCore helpful?

Options and Type Definitions

SearchBoxOptions

Properties

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.

eta_type("navigation"): Used to estimate the time of arrival from the location specified in SearchBoxOptions#origin .

The only allowed value for this parameter is navigation. This parameter, along with SearchBoxOptions#origin and SearchBoxOptions#navigation_profile, is required for ETA calculations.

ETA calculations will incur additional latency.

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 .

navigation_profile(("driving" | "walking" | "cycling")): The navigation routing profile to use for distance/eta calculations.

For distance calculations, both SearchBoxOptions#navigation_profile and SearchBoxOptions#origin must be specified.

For ETA calculations: SearchBoxOptions#navigation_profile, SearchBoxOptions#origin, and SearchBoxOptions#eta_type must be specified.

origin((string | LngLatLike)): The location from which to calculate distance. This parameter may incur additional latency.

When both SearchBoxOptions#proximity and SearchBoxOptions#origin are specified, origin is interpreted as the target of a route, while proximity indicates the current user location.

For distance calculations, both SearchBoxOptions#navigation_profile and SearchBoxOptions#origin must be specified.

For ETA calculations: SearchBoxOptions#navigation_profile, SearchBoxOptions#origin, and SearchBoxOptions#eta_type must be specified.

poi_category(string): Limit results to those that belong to one or more categories, provided as a comma-separated list.

poi_category_exclusions(string): A comma-separated list of canonical category names that limits POI results to those that are not part of the given categories.

proximity((string | LngLatLike)): Bias the response to favor results that are closer to this location.

When both SearchBoxOptions#proximity and SearchBoxOptions#origin are specified, origin is interpreted as the target of a route, while proximity indicates the current user location.

radius((string | number)): Radius for the area to search within around a point.

rich_metadata_provider(string): A comma-separated list of rich metadata providers to include in a suggestion result.

route(string): A polyline encoded linestring describing the route to be used for searching.

Both polyline5 and polyline6 precision are accepted, but must be specified using the SearchBoxOptions#route_geometry parameter.

route_geometry(string): Passed in conjunction with a route polyline describing its precision. Options are polyline or polyline6. If this parameter is not provided with a SearchBoxOptions#route , the default is polyline.

Accurate results depend on including the correct route_geometry for the SearchBoxOptions#route provided.

sar_type(string): This indicates that the user intends to perform a higher cost search-along-route request.

This should be included when SearchBoxOptions#route is included and should have a value of isochrone.

time_deviation((string | number)): Maximum detour in estimated minutes from route.

types((string | Set<SearchBoxAdministrativeUnitTypes>)): Limit results to one or more types of features. If no types are specified, all possible types may be returned.

Reference: https://docs.mapbox.com/api/search/search-box/#administrative-unit-types

user_id(string): A customer provided user id.

Was this section on SearchBoxOptions helpful?

SearchBoxSuggestion

A SearchBoxSuggestion object represents a suggestion result from the Mapbox Search Box API.

SearchBoxSuggestion objects are "part one" of the two-step interactive search experience, and include useful information about the result, such as: SearchBoxSuggestion#name, SearchBoxSuggestion#full_address, and SearchBoxSuggestion#maki.

SearchBoxSuggestion objects do not include geographic coordinates. To get the coordinates of the result, use SearchBoxCore#retrieve.

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

Reference: https://docs.mapbox.com/api/search/search-box/#response-get-suggested-results

Type

Object

Properties

added_distance(number): The distance added to an input route by including the given suggestion, in meters.

added_time(number): The estimated time added to an input route by including the given suggestion, in minutes.

address(string): The address of the result containing the address number and street.

brand(string): The brand name of the result, if it is a POI and is applicable.

brand_id(string): The canonical brand ID of the result, if it is a POI and is applicable.

context(SuggestionJSONContext): The context of the feature. This context has layers that follow the Administrative unit types .

distance(number): An approximate distance to the origin location, in meters. Only provided when origin and navigation_profile are used in the request.

eta(number): The estimated time of arrival from the origin point to the feature, in minutes. Only provided when eta_type , origin , and navigation_profile are used in the request. If an address is not on the road network, an ETA will not be provided.

external_ids(any): An object containing the IDs of the feature found in external databases, with the keys being the data source names and the values being the IDs.

feature_type(string): The type of the result. For POIs, this will be poi . For categories, this will be category . For address-type results, the global context hierarchy is used ( country , region , postcode , district , place , locality , neighborhood , address ). See the Administrative unit types section for details about these types.

full_address(string): The full address of the result, which concatenates SearchBoxSuggestion#address and SearchBoxSuggestion#place_formatted .

language(string): An IETF language tag indicating the language of the result.

maki(string): A string representing an associated Maki icon to use for this result.

mapbox_id(string): The id to use with SearchBoxCore#retrieve to obtain full feature details.

metadata(any): An object containing additional metadata for the feature, if applicable.

name(string): The name of the feature.

name_preferred(string): The preferred name of the feature, if different than SearchBoxSuggestion#name .

place_formatted(string): A formatted string of result context comprised of the place, region, country, and postcode.

poi_category(Array<string>): An array including the POI categories the result falls into, if it is a POI.

Example

const search = new SearchBoxCore({ accessToken: 'pk.my-mapbox-access-token' });

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

const suggestion = result.suggestions[0];

const { features } = await search.retrieve(suggestion, { sessionToken });
doSomethingWithCoordinates(features);

Was this section on SearchBoxSuggestion helpful?

SearchBoxFeatureSuggestion

A SearchBoxFeatureSuggestion object represents a GeoJSON suggestion result from the Mapbox Search Box API.

Feature suggestions are "part two" of the two-step interactive search experience and includes geographic coordinates. Multiple feature suggestions may be returned from a single search query, for example in an airport with multiple terminals.

As per the Mapbox Search Box API, this will always be Point.

Legal terms:

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.

Type

GeoJSON.Feature<GeoJSON.Point, SearchBoxFeatureProperties>

Example

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

Response: Retrieve feature

Was this section on SearchBoxFeatureSuggestion helpful?

SearchBoxFeatureProperties

Raw GeoJSON feature properties from the Mapbox Search Box API.

Reference: https://docs.mapbox.com/api/search/search-box/#response-retrieve-a-suggested-feature

Extends Omit<SearchBoxSuggestion, 'distance' | 'eta' | 'added_distance' | 'added_time'>.

Type

Object

Properties

bbox([number, number, number, number]): A bounding box in the format minimum longitude , minimum latitude , maximum longitude , maximum latitude .

coordinates

({accuracy: string?, longitude: number, latitude: number, routable_points: Array<{name: string, latitude: number, longitude: number}>?})

: The geographical coordinates of the result.

Was this section on SearchBoxFeatureProperties helpful?

Was this section on SearchBoxSuggestionResponse helpful?

Was this section on SearchBoxRetrieveResponse helpful?

SearchBoxAdministrativeUnitTypes

Administrative unit types for the Mapbox Search Box API.

Type

https://docs.mapbox.com/api/search/search-box/#administrative-unit-types

Was this section on SearchBoxAdministrativeUnitTypes helpful?

Was this page helpful?

Class

SearchBoxCore

Parameters

Example

Instance Members

accessToken

defaults

Interactive search

suggest

retrieve

Programmatic search

category

reverse

Options and Type Definitions

SearchBoxOptions

Type

Properties

SearchBoxSuggestion

Type

Properties

Example

SearchBoxFeatureSuggestion

Type

Example

SearchBoxFeatureProperties

Type

Properties

SearchBoxSuggestionResponse

Type

Properties

SearchBoxRetrieveResponse

Type

Properties

SearchBoxAdministrativeUnitTypes

Type