Skip to main content

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:

  1. 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.
  2. 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?) 
NameDescription
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);

Instance Members

Was this section on SearchBoxCore helpful?

Options and Type Definitions

SearchBoxOptions

Object

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.

                      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

                                  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

                                  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.

                                                                        GeoJSON.Feature<GeoJSON.Point, SearchBoxFeatureProperties>

                                                                        Example

                                                                        const featureSuggestion = {
                                                                        type: 'Feature',
                                                                        geometry: {
                                                                        type: 'Point',
                                                                        coordinates: [0,0]
                                                                        },
                                                                        properties: {
                                                                        name: 'Washington D.C.',
                                                                        }
                                                                        };
                                                                        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'>.
                                                                        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?

                                                                            SearchBoxSuggestionResponse

                                                                            Object

                                                                            Properties

                                                                            attribution(string): The attribution data for results.
                                                                              suggestions(Array<SearchBoxSuggestion>): The returned suggestion objects.
                                                                                Was this section on SearchBoxSuggestionResponse helpful?

                                                                                SearchBoxRetrieveResponse

                                                                                Object

                                                                                Properties

                                                                                attribution(string): The attribution data for results.
                                                                                  features(Array<SearchBoxFeatureSuggestion>): The returned feature objects.
                                                                                    Was this section on SearchBoxRetrieveResponse helpful?

                                                                                    SearchBoxAdministrativeUnitTypes

                                                                                    Administrative unit types for the Mapbox Search Box API.

                                                                                    ("country" | "region" | "postcode" | "district" | "place" | "locality" | "neighborhood" | "street" | "address" | "block")
                                                                                    Was this section on SearchBoxAdministrativeUnitTypes helpful?
                                                                                    Was this page helpful?