Search Box
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.
Parameters
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);
Instance Members
Interactive search
Programmatic search
Options and Type Definitions
SearchBoxOptions
ObjectProperties
((string | LngLatBoundsLike)): Limit results to only those contained within the supplied bounding box.
(string): An
ISO 3166 alpha-2 country code
to be returned.
If not specified, results will not be filtered by country.
("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.
(("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.
((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.
(string): Limit results to those that belong to one or more categories, provided as a comma-separated list.
(string): A comma-separated list of canonical category names that limits POI results to those that are not part of the given categories.
((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.
(string): A comma-separated list of rich metadata providers to include in a suggestion result.
(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.
(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.
(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.
((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
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
ObjectProperties
(number): The distance added to an input route by including the given suggestion, in meters.
(number): The estimated time added to an input route by including the given suggestion, in minutes.
(SuggestionJSONContext): The context of the feature. This context has layers that follow the
Administrative unit types
.
(number): An approximate distance to the
origin
location, in meters. Only provided when
origin
and
navigation_profile
are used in the request.
(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.
(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.
(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.
(string): The full address of the result, which concatenates
SearchBoxSuggestion#address
and
SearchBoxSuggestion#place_formatted
.
(any): An object containing additional metadata for the feature, if applicable.
(string): The preferred name of the feature, if different than
SearchBoxSuggestion#name
.
(string): A formatted string of result context comprised of the place, region, country, and postcode.
(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);
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.
GeoJSON.Feature<GeoJSON.Point, SearchBoxFeatureProperties>Example
const featureSuggestion = {
type: 'Feature',
geometry: {
type: 'Point',
coordinates: [0,0]
},
properties: {
name: 'Washington D.C.',
}
};
Related
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
Properties
([number, number, number, number]): A bounding box in the format
minimum longitude
,
minimum latitude
,
maximum longitude
,
maximum latitude
.
({accuracy: string?, longitude: number, latitude: number, routable_points: Array<{name: string, latitude: number, longitude: number}>?}): The geographical coordinates of the result.
Related
SearchBoxAdministrativeUnitTypes
Administrative unit types for the Mapbox Search Box API.
("country" | "region" | "postcode" | "district" | "place" | "locality" | "neighborhood" | "street" | "address" | "block")