TomTom Maps SDK for JavaScript
TomTom Maps for JavaScript
    Preparing search index...

    Function discoverPlaces

    • Finds places by text query, within geometries or along a route, from one universal function.

      It runs one of three searches, picked from its params:

      • Along-route search when route is given, for places within a detour budget of the route.
      • Geometry search when geometries is given, for places inside those areas.
      • Fuzzy search otherwise, for free text, optionally biased by geoBias.

      With a route, each result's properties are AlongRoutePlaceProps, which add the detour a stop at the place costs.

      Parameters

      • queryOrParams: { filters?: DiscoverPlacesCategoryFilters } & Partial<
            Omit<GlobalConfig, "displayUnits">,
        > & { signal?: AbortSignal; validateRequest?: boolean } & {
            extendedPostalCodesFor?: SearchIndexType[];
            limit?: number;
            mapcodes?: MapcodeType[];
        } & {
            filters?: PlaceFilters;
            openingHours?: "nextSevenDays";
            query?: string;
            relatedPois?: RelatedPoisRequest;
            timeZone?: "iana";
        } & {
            maxDetourTimeSeconds: number;
            route: LineString
            | Route
            | Position[];
            sortBy?: AlongRouteSortBy;
        } & Without<FuzzySearchParams, AlongRouteSearchParams> & Without<
            GeometrySearchParams,
            AlongRouteSearchParams,
        > & { filters?: { countries?: undefined } } & { sortBy: "detourOffset" }

        A query string, which runs a fuzzy search the same as { query }, or the FuzzySearchParams, GeometrySearchParams or AlongRouteSearchParams. Pass the params form to set any other option, signal included.

        • Optionalsignal?: AbortSignal

          An AbortSignal used to cancel the request.

          Aborting rejects the call with an SDKAbortError (its name is 'AbortError') and cancels the underlying HTTP request, including while the SDK is waiting to retry a rate-limited (429) response. Aborting a call that already completed has no effect.

          To add a deadline, compose signals: AbortSignal.any([mine, AbortSignal.timeout(5000)]).

          Keep only the latest search with createLatestRequest:

          const latestSearch = createLatestRequest();
          const search = await latestSearch.run((signal) => discoverPlaces({ query, signal }));
          if (search.current) showResults(search.value);

          undefined (the request cannot be cancelled)

        • OptionalvalidateRequest?: boolean

          Whether the SDK validates the request parameters against the expected schema before sending them.

          Validation also rejects a parameter the service doesn't know, and names it. To skip validation, set it to false, which then drops an unknown parameter silently. The commonBaseURL check (INSECURE_BASE_URL) runs either way.

          true

        • OptionalextendedPostalCodesFor?: SearchIndexType[]

          The indexes for which results include extended postal codes.

          Extended postal codes carry more detailed postal code information, including sub-divisions and hierarchical structures.

          By default, extended postal codes are included for all indexes except Geo. Geographic entities can have very long postal code lists, so you must request them explicitly when needed.

          A regular postal code is "10001" (basic ZIP code), and an extended one "10001-1234" (ZIP+4 format).

          Note that including them for geographies can significantly increase response size.

          // Include for addresses and POIs only
          extendedPostalCodesFor: ['PAD', 'Addr', 'POI']

          // Include for all types including geographies
          extendedPostalCodesFor: ['Geo', 'PAD', 'Addr', 'Str', 'XStr', 'POI']
        • Optionallimit?: number

          The maximum number of results in a single response, which controls pagination.

          Fuzzy search and geocoding page with cursor, as CommonGeocodeAndFuzzySearchParams.cursor describes.

          The range is 1 to 100. Higher limits increase response size and processing time, and lower limits improve performance. For large result sets, use pagination.

          10

          limit: 20   // Get 20 results
          limit: 5    // Get only top 5 results
          limit: 100  // Maximum allowed
        • Optionalmapcodes?: MapcodeType[]

          The mapcode representations to request for locations.

          Mapcodes are short, human-friendly location codes that can represent any location on Earth to within a few meters. They're easier to remember and communicate than coordinates.

          The mapcode types are:

          • Local: Short codes valid within a specific territory (e.g., "49.4V" in Netherlands)
          • International: Codes that work globally (e.g., "NLD 49.4V")
          • Alternative: Alternative representations for the same location

          Use them for:

          • Emergency services (shorter than full addresses)
          • Areas without formal addressing systems
          • Easy verbal communication of locations
          • Navigation to precise spots

          Mapcode Project

          // Get all mapcode types
          mapcodes: ['Local', 'International', 'Alternative']

          // Get only local mapcodes
          mapcodes: ['Local']
        • Optionalfilters?: PlaceFilters

          The kinds of places that may come back, as PlaceFilters.

        • OptionalopeningHours?: "nextSevenDays"

          The format and detail level of the POI opening hours data that the response includes.

          Each mode gives a different level of detail about when a POI is open for business.

          Use it to:

          • Display "Open Now" status
          • Show full weekly schedule
          • Plan visits during open hours
          • Filter to currently open locations
          // Request opening hours
          openingHours: 'nextSevenDays'
        • Optionalquery?: string

          The text to search for.

          It can be a place name, POI, address, or any free-form location query. If you leave it out, filters alone drive the results (a category, a brand, a fuel type), or geometries do on geometry search.

          For example:

          • Place/POI names: "Eiffel Tower", "Starbucks"
          • General queries: "pizza near me", "gas station"
          • Partial inputs: "Amst" (for autocomplete / typeahead)

          Pass it as plain text. The SDK encodes it for the request path, so a value you already encoded is encoded again and can resolve to a different place.

          The query is processed with fuzzy matching to handle typos and variations.

          // Text-driven search
          query: 'coffee shop'

          // Omit query to search purely by category
          filters: { poiCategories: ['CHARGING_LOCATION'] }
        • OptionalrelatedPois?: RelatedPoisRequest

          Which related POIs the response includes.

          Some POIs have hierarchical relationships (e.g., terminal inside airport).

          The relationship types are:

          • off: No related POIs (default)
          • child: Include child POIs (e.g., terminals of an airport)
          • parent: Include parent POIs (e.g., airport of a terminal)
          • all: Include both parent and child relationships

          Use it to:

          • Show all terminals when user searches for airport
          • Navigate from specific location to broader facility
          • Display hierarchical location structure
          • Provide alternative entry points
          'off'

          // Include child POIs
          relatedPois: 'child'  // Airport → show terminals

          // Include parent POIs
          relatedPois: 'parent'  // Terminal → show airport

          // Include all related POIs
          relatedPois: 'all'
        • OptionaltimeZone?: "iana"

          The timezone information to include for POI locations, for scheduling and time-aware applications.

          With iana, the response carries the IANA timezone identifier (e.g., "Europe/Amsterdam").

          Use it to:

          • Display local time for POI
          • Schedule appointments across timezones
          • Calculate opening hours in local time
          • International business coordination
          // Request IANA timezone ID
          timeZone: 'iana'
        • maxDetourTimeSeconds: number

          Maximum allowed detour time in seconds, a positive integer up to 3600 (one hour); request validation rejects a larger one.

          Only POIs reachable within this additional travel time from the route are returned. It controls the width of the search corridor.

          maxDetourTimeSeconds: 300  // 5-minute detour budget
        • route: LineString | Route | Position[]

          Route geometry to search along.

          It accepts any of three forms:

          • Route feature as returned by calculateRoute (most common)
          • LineString GeoJSON geometry object
          • Position[], a plain array of [longitude, latitude] coordinate pairs

          Coordinates must always be in [longitude, latitude] order.

          // Route Feature from calculateRoute (most common)
          route: routeResult.features[0]

          // GeoJSON LineString geometry
          route: routeResult.features[0].geometry

          // Plain coordinate array
          route: [[4.9, 52.37], [4.95, 52.28], [5.1, 52.09]]
        • OptionalsortBy?: AlongRouteSortBy

          Sort order for the results.

          'detourTime'

          sortBy: 'detourOffset'  // order by position along the route
        • Optionalfilters?: { countries?: undefined }
        • sortBy: "detourOffset"

      Returns Promise<
          AlongRouteSearchResponse<
              CommonPlaceProps & { distance?: number; info?: string; score?: number } & {
                  detourDistanceInMeters: number;
                  detourOffsetInMeters?: number;
                  detourTimeInSeconds: number;
              } & Required<Pick<AlongRoutePlaceProps, "detourOffsetInMeters">>,
          >,
      >

      The matching places.

      // Free-text search
      const cafes = await discoverPlaces('coffee shop Amsterdam');

      // Free-text search near a location
      const results = await discoverPlaces({
        query: 'pizza restaurant',
        geoBias: { position: [4.9041, 52.3676] },  // Amsterdam
        limit: 10
      });

      // Search within a specific area
      const areaResults = await discoverPlaces({
        query: 'coffee shop',
        geometries: [polygon],  // Search within this polygon
        limit: 20
      });

      // Category search
      const restaurants = await discoverPlaces({
        filters: { poiCategories: ['ITALIAN_RESTAURANT'] },
        geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }  // Within 5km
      });

      // The same, from a category in words
      const italian = await discoverPlaces({
        filters: { poiCategoryQuery: 'italian food' },
        geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }
      });

    • Finds places by text query, within geometries or along a route, from one universal function.

      It runs one of three searches, picked from its params:

      • Along-route search when route is given, for places within a detour budget of the route.
      • Geometry search when geometries is given, for places inside those areas.
      • Fuzzy search otherwise, for free text, optionally biased by geoBias.

      With a route, each result's properties are AlongRoutePlaceProps, which add the detour a stop at the place costs.

      Parameters

      • queryOrParams: { filters?: DiscoverPlacesCategoryFilters } & Partial<
            Omit<GlobalConfig, "displayUnits">,
        > & { signal?: AbortSignal; validateRequest?: boolean } & {
            extendedPostalCodesFor?: SearchIndexType[];
            limit?: number;
            mapcodes?: MapcodeType[];
        } & {
            filters?: PlaceFilters;
            openingHours?: "nextSevenDays";
            query?: string;
            relatedPois?: RelatedPoisRequest;
            timeZone?: "iana";
        } & {
            maxDetourTimeSeconds: number;
            route: LineString
            | Route
            | Position[];
            sortBy?: AlongRouteSortBy;
        } & Without<FuzzySearchParams, AlongRouteSearchParams> & Without<
            GeometrySearchParams,
            AlongRouteSearchParams,
        > & { filters?: { countries?: undefined } }

        A query string, which runs a fuzzy search the same as { query }, or the FuzzySearchParams, GeometrySearchParams or AlongRouteSearchParams. Pass the params form to set any other option, signal included.

        • Optionalsignal?: AbortSignal

          An AbortSignal used to cancel the request.

          Aborting rejects the call with an SDKAbortError (its name is 'AbortError') and cancels the underlying HTTP request, including while the SDK is waiting to retry a rate-limited (429) response. Aborting a call that already completed has no effect.

          To add a deadline, compose signals: AbortSignal.any([mine, AbortSignal.timeout(5000)]).

          Keep only the latest search with createLatestRequest:

          const latestSearch = createLatestRequest();
          const search = await latestSearch.run((signal) => discoverPlaces({ query, signal }));
          if (search.current) showResults(search.value);

          undefined (the request cannot be cancelled)

        • OptionalvalidateRequest?: boolean

          Whether the SDK validates the request parameters against the expected schema before sending them.

          Validation also rejects a parameter the service doesn't know, and names it. To skip validation, set it to false, which then drops an unknown parameter silently. The commonBaseURL check (INSECURE_BASE_URL) runs either way.

          true

        • OptionalextendedPostalCodesFor?: SearchIndexType[]

          The indexes for which results include extended postal codes.

          Extended postal codes carry more detailed postal code information, including sub-divisions and hierarchical structures.

          By default, extended postal codes are included for all indexes except Geo. Geographic entities can have very long postal code lists, so you must request them explicitly when needed.

          A regular postal code is "10001" (basic ZIP code), and an extended one "10001-1234" (ZIP+4 format).

          Note that including them for geographies can significantly increase response size.

          // Include for addresses and POIs only
          extendedPostalCodesFor: ['PAD', 'Addr', 'POI']

          // Include for all types including geographies
          extendedPostalCodesFor: ['Geo', 'PAD', 'Addr', 'Str', 'XStr', 'POI']
        • Optionallimit?: number

          The maximum number of results in a single response, which controls pagination.

          Fuzzy search and geocoding page with cursor, as CommonGeocodeAndFuzzySearchParams.cursor describes.

          The range is 1 to 100. Higher limits increase response size and processing time, and lower limits improve performance. For large result sets, use pagination.

          10

          limit: 20   // Get 20 results
          limit: 5    // Get only top 5 results
          limit: 100  // Maximum allowed
        • Optionalmapcodes?: MapcodeType[]

          The mapcode representations to request for locations.

          Mapcodes are short, human-friendly location codes that can represent any location on Earth to within a few meters. They're easier to remember and communicate than coordinates.

          The mapcode types are:

          • Local: Short codes valid within a specific territory (e.g., "49.4V" in Netherlands)
          • International: Codes that work globally (e.g., "NLD 49.4V")
          • Alternative: Alternative representations for the same location

          Use them for:

          • Emergency services (shorter than full addresses)
          • Areas without formal addressing systems
          • Easy verbal communication of locations
          • Navigation to precise spots

          Mapcode Project

          // Get all mapcode types
          mapcodes: ['Local', 'International', 'Alternative']

          // Get only local mapcodes
          mapcodes: ['Local']
        • Optionalfilters?: PlaceFilters

          The kinds of places that may come back, as PlaceFilters.

        • OptionalopeningHours?: "nextSevenDays"

          The format and detail level of the POI opening hours data that the response includes.

          Each mode gives a different level of detail about when a POI is open for business.

          Use it to:

          • Display "Open Now" status
          • Show full weekly schedule
          • Plan visits during open hours
          • Filter to currently open locations
          // Request opening hours
          openingHours: 'nextSevenDays'
        • Optionalquery?: string

          The text to search for.

          It can be a place name, POI, address, or any free-form location query. If you leave it out, filters alone drive the results (a category, a brand, a fuel type), or geometries do on geometry search.

          For example:

          • Place/POI names: "Eiffel Tower", "Starbucks"
          • General queries: "pizza near me", "gas station"
          • Partial inputs: "Amst" (for autocomplete / typeahead)

          Pass it as plain text. The SDK encodes it for the request path, so a value you already encoded is encoded again and can resolve to a different place.

          The query is processed with fuzzy matching to handle typos and variations.

          // Text-driven search
          query: 'coffee shop'

          // Omit query to search purely by category
          filters: { poiCategories: ['CHARGING_LOCATION'] }
        • OptionalrelatedPois?: RelatedPoisRequest

          Which related POIs the response includes.

          Some POIs have hierarchical relationships (e.g., terminal inside airport).

          The relationship types are:

          • off: No related POIs (default)
          • child: Include child POIs (e.g., terminals of an airport)
          • parent: Include parent POIs (e.g., airport of a terminal)
          • all: Include both parent and child relationships

          Use it to:

          • Show all terminals when user searches for airport
          • Navigate from specific location to broader facility
          • Display hierarchical location structure
          • Provide alternative entry points
          'off'

          // Include child POIs
          relatedPois: 'child'  // Airport → show terminals

          // Include parent POIs
          relatedPois: 'parent'  // Terminal → show airport

          // Include all related POIs
          relatedPois: 'all'
        • OptionaltimeZone?: "iana"

          The timezone information to include for POI locations, for scheduling and time-aware applications.

          With iana, the response carries the IANA timezone identifier (e.g., "Europe/Amsterdam").

          Use it to:

          • Display local time for POI
          • Schedule appointments across timezones
          • Calculate opening hours in local time
          • International business coordination
          // Request IANA timezone ID
          timeZone: 'iana'
        • maxDetourTimeSeconds: number

          Maximum allowed detour time in seconds, a positive integer up to 3600 (one hour); request validation rejects a larger one.

          Only POIs reachable within this additional travel time from the route are returned. It controls the width of the search corridor.

          maxDetourTimeSeconds: 300  // 5-minute detour budget
        • route: LineString | Route | Position[]

          Route geometry to search along.

          It accepts any of three forms:

          • Route feature as returned by calculateRoute (most common)
          • LineString GeoJSON geometry object
          • Position[], a plain array of [longitude, latitude] coordinate pairs

          Coordinates must always be in [longitude, latitude] order.

          // Route Feature from calculateRoute (most common)
          route: routeResult.features[0]

          // GeoJSON LineString geometry
          route: routeResult.features[0].geometry

          // Plain coordinate array
          route: [[4.9, 52.37], [4.95, 52.28], [5.1, 52.09]]
        • OptionalsortBy?: AlongRouteSortBy

          Sort order for the results.

          'detourTime'

          sortBy: 'detourOffset'  // order by position along the route
        • Optionalfilters?: { countries?: undefined }

      Returns Promise<AlongRouteSearchResponse>

      The matching places.

      // Free-text search
      const cafes = await discoverPlaces('coffee shop Amsterdam');

      // Free-text search near a location
      const results = await discoverPlaces({
        query: 'pizza restaurant',
        geoBias: { position: [4.9041, 52.3676] },  // Amsterdam
        limit: 10
      });

      // Search within a specific area
      const areaResults = await discoverPlaces({
        query: 'coffee shop',
        geometries: [polygon],  // Search within this polygon
        limit: 20
      });

      // Category search
      const restaurants = await discoverPlaces({
        filters: { poiCategories: ['ITALIAN_RESTAURANT'] },
        geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }  // Within 5km
      });

      // The same, from a category in words
      const italian = await discoverPlaces({
        filters: { poiCategoryQuery: 'italian food' },
        geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }
      });

    • Finds places by text query, within geometries or along a route, from one universal function.

      It runs one of three searches, picked from its params:

      • Along-route search when route is given, for places within a detour budget of the route.
      • Geometry search when geometries is given, for places inside those areas.
      • Fuzzy search otherwise, for free text, optionally biased by geoBias.

      With a route, each result's properties are AlongRoutePlaceProps, which add the detour a stop at the place costs.

      Parameters

      Returns Promise<DiscoverPlacesResponse>

      The matching places.

      // Free-text search
      const cafes = await discoverPlaces('coffee shop Amsterdam');

      // Free-text search near a location
      const results = await discoverPlaces({
        query: 'pizza restaurant',
        geoBias: { position: [4.9041, 52.3676] },  // Amsterdam
        limit: 10
      });

      // Search within a specific area
      const areaResults = await discoverPlaces({
        query: 'coffee shop',
        geometries: [polygon],  // Search within this polygon
        limit: 20
      });

      // Category search
      const restaurants = await discoverPlaces({
        filters: { poiCategories: ['ITALIAN_RESTAURANT'] },
        geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }  // Within 5km
      });

      // The same, from a category in words
      const italian = await discoverPlaces({
        filters: { poiCategoryQuery: 'italian food' },
        geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }
      });

    Settings
    Member Visibility