This page includes reference documentation for Search Box in the Mapbox Search JS Core framework.
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:
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: <a href="/mapbox-search-js/api/core/search/#searchboxoptions">SearchBoxOptions</a>?)
| Name | Description |
|---|---|
| options SearchBoxOptions? | |
| options.accessToken string? |
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);Any default options (SearchBoxOptions) to be merged into options in the following methods:
SearchBoxCore#suggest is "part one" of the two-step interactive search experience, and includes useful information such as: SearchBoxSuggestion#name, SearchBoxSuggestion#place_formatted, and SearchBoxSuggestion#maki.
Suggestion 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.
If you'd like session tokens to be handled automatically, see SearchSession.
| Name | Description |
|---|---|
| searchText string | |
| optionsArg SearchBoxOptions | |
| optionsArg.sessionToken SessionTokenLike | |
| optionsArg.signal AbortSignal? |
SearchBoxCore#retrieve is "part two" of the two-step interactive search experience and includes geographic coordinates in GeoJSON format.
suggestion is usually a SearchBoxSuggestion returned from "part one," SearchBoxCore#suggest.
Multiple feature suggestions may be returned from a single search query, for example in an airport with multiple terminals.
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.
| Name | Description |
|---|---|
| suggestion SearchBoxSuggestion | |
| optionsArg any | |
| optionsArg.sessionToken SessionTokenLike | |
| optionsArg.signal AbortSignal? |
SearchBoxCore#category makes it possible to browse entire categories of results, like coffee shops, hotels, and bookstores around a specific location or along a route and returns feature collection in GeoJSON format.
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.
| Name | Description |
|---|---|
| category string | |
optionsArg Options (default {}) | |
| optionsArg.permanent boolean? | |
| optionsArg.signal AbortSignal? |
SearchBoxCore#reverse endpoint allows you to look up a single pair of coordinates and returns the geographic feature or features that exist at that location. The response to a request is a GeoJSON FeatureCollection.
Using the limit parameter, you can increase the maximum number of results up to 10. Pagination is not available, but this feature may be added in a later release. There is not an option to customize the order of search results.
Multiple feature suggestions may be returned from a single search query, for example in an airport with multiple terminals.
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.
| Name | Description |
|---|---|
| lngLat (string | LngLatLike) | Either a LngLatLike object or string in 'lng,lat' comma-separated format. |
optionsArg Options (default {}) | |
| optionsArg.signal AbortSignal? |
Options object for configuring SearchBoxCore, mapped to Search Box API parameters.
| Name | Description |
|---|---|
| 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, |
| 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, 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, |
| 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 |
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
| Name | Description |
|---|---|
| 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. |
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);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.
const featureSuggestion = {
type: 'Feature',
geometry: {
type: 'Point',
coordinates: [0,0]
},
properties: {
name: 'Washington D.C.',
}
};Raw GeoJSON feature properties from the Mapbox Search Box API.
Reference: https://docs.mapbox.com/api/search/search-box/#response-retrieve-a-suggested-feature
| Name | Description |
|---|---|
| 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. |
A SearchBoxSuggestionResponse object represents a returned data object from the suggest endpoint of the Mapbox Search Box API.
| Name | Description |
|---|---|
| attribution string | The attribution data for results. |
| suggestions Array<SearchBoxSuggestion> | The returned suggestion objects. |
A SearchBoxRetrieveResponse object represents a returned data object from the /retrieve endpoint of the Mapbox Search Box API.
| Name | Description |
|---|---|
| attribution string | The attribution data for results. |
| features Array<SearchBoxFeatureSuggestion> | The returned feature objects. |
Administrative unit types for the Mapbox Search Box API.
"country" | "region" | "postcode" | "district" | "place" | "locality" | "neighborhood" | "street" | "address" | "block")