Discover

Base URL for calling the API.
Values:

• api.tomtom.com

• kr-api.tomtom.com

• eu-api.tomtom.com

• us-api.tomtom.com

An API Key valid for the requested service. See: How do I get a TomTom API Key?
Value: Your valid API Key.

Version of the API. The API version MUST be specified in all requests.
Value: The current value is 3.
Supported Api Versions: 3

A comma-separated list of response attributes to return. Nested attributes are specified in dot notation. Multiple attributes sharing the same parent can be grouped together using parentheses.
Specifying a non-leaf attribute returns all available subattributes implicitly.
Note:

• New response fields may be added over time without notice.
• When (sub)attributes are requested implicitly, the client must be forward-compatible with respect to new subattributes.
• Requesting attributes implicitly may have variable cost/billing implications and is therefore not recommended for production use.
• An empty top-level Attributes parameter is not valid.
• Invalid attributes are rejected with a 400 Bad Request response.

Examples:

• results
• results(address,distanceInMeters)
• results(address,chargingLocation(chargingStations))

A unique identifier that must be a 36-character hyphenated UUID (v4 or v7) in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12, 36 characters including hyphens), for a places search flow session.
A places search application user journey (flow) may start with a suggest, discover or details request. Typically, the application is responsible for identifying the beginning of a places search session and thus is responsible for generating a unique SessionId for the session. The session identifier should be reused for all requests within the same user journey.
Suggest, Discover and Details results include follow-up places search requests with an embedded SessionId.
As the user progresses through a search query typing session, interacts with suggestions or discover / details results by making followup places search requests, the session id is propagated via the SessionId header prescribed in the followup request specification.
A places search session is terminated when either no request has been received by the server for a given SessionId within a dynamic server-controlled use-case dependent timeout, or a suggest request is received not preceded by a suggest request with the same SessionId.
Format: 36-character hyphenated UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
Min Length: 36
Max Length: 36

A unique identifier for tracking the request across services. The client should provide a globally unique value, preferably a UUID (v4 or v7). While any string format is accepted, the tracking ID must be unique to enable effective request tracing and correlation in logs.
Min Length: 10
Max Length: 50

Sequence of preferred response IETF BCP 47 language tags compliant with RFC 7231 (section 5.3.5).
The API makes best effort to return results in one of the preferred languages, falling back to the prevalent local language in the result's geographical region if none of the preferred languages is available.
Example: en-US,en,hi-Deva;q=0.9

The standard HTTP Accept header indicating the media type(s) the client is able to understand. HTTP reference
Allowed Values: application/json

Text query, assumed to be fully expressed by the user.
Min Length: 0

The position from which result distances are calculated, populating the distanceInMeters field on each result. It does not affect result ranking or ordering. Typically the position of the user making the request.
Type: Point geometry restricted to 2D coordinates (Longitude, Latitude).
Properties:

• type (required): "point"

• coordinates (required): PositionWithoutElevation - Array of [longitude, latitude] in degrees

  • Array of 2 numbers: [longitude, latitude]
  • longitude: number, -180 to 180 (Longitude of point in degrees)
  • latitude: number, -90 to 90 (Latitude of point in degrees)

Example: {"type": "point", "coordinates": [-73.935242, 40.73061]}

Maximum number of results to return.
Default value: 10
Minimum value: 1
Maximum value: 100

Geopolitical view. The context used to resolve the handling of addressing schemes in disputed territories.
Default value: "Unified"
Enum: "AR" "CN" "IL" "IN" "KR" "MA" "PK" "RU" "RS" "TR" "TW" "Unified"
Supported geopolitical views:

• Unified
• AR: Argentina
• CN: China
• IL: Israel
• IN: India
• KR: South Korea
• MA: Morocco
• PK: Pakistan
• RU: Russia
• RS: Serbia
• TR: Türkiye
• TW: Taiwan

The default and available values depend on the country where the request is made in. If valid value but non available one is used the 403 error is raised. Possible values and defaults(per request-origin country) are as follows:

• Argentina - default view: AR, available views: All
• China - default view: CN, available views: All
• India - default view: IN, available views: IN (no other views available)
• Israel - default view: IL, available views: All
• South Korea (check for region specific contents) - default view: KR, available views: KR (no other views available)
• Morocco - default view: MA, available views: All
• Pakistan - default view: PK, available views: All
• Russia - default view: RU, available views: All
• Türkiye - default view: TR, available views: All
• Taiwan - default view: TW, available views: All
• Serbia - default view: RS, available views: All
• Others - default view: Unified, available views: All

When not specified, the appropriate geopolitical view is applied based on the origin location of the request.

Filters to apply for discover requests. Filter parameters narrow the set of candidate results and do not affect result ranking or ordering. Includes all suggest filters plus additional POI-specific filters.
Properties:

• types - Types of results to include. When not specified, all types are included. Array of ResultType. ResultType can be either a LocationType (poi, address, street, intersection, area) or the string discoverAction. Default: ["address", "street", "intersection", "poi", "area", "discoverAction"], Min items: 1
• countryCodesIso2 - List of ISO 3166-1 alpha-2 country codes to restrict results to. When not specified, all countries are included. Format: 2-character uppercase country codes
• areaTypes - Types of areas to include. When not specified, all area types are included. Allowed values: country, countrySubdivision, countrySecondarySubdivision, countryTertiarySubdivision, municipality, municipalitySubdivision, municipalitySecondarySubdivision, postalCode, neighborhood, block
• poiTypes - Types of places of interest to include. When not specified, all place-of-interest types are included
• poiBrands - List of brand IDs to filter results by. Brand IDs are case-sensitive uppercase strings (e.g. STARBUCKS, MCDONALDS); mixed-case or lowercase values will not match and return unfiltered results. When not specified, all brands are included
• geometry - Limits the results to the provided geometrical boundary. Type discriminated by the type property: Circle (circle, with center and radiusInMeters in range 1-1000000), Rectangle (rectangle, with coordinates as [southWestLon, southWestLat, northEastLon, northEastLat]), or Simple Polygon (simplePolygon, with a closed coordinates array of [longitude, latitude] pairs, min 4)
• chargingLocation - Filters/preferences applicable to places of interest of poiType: ev_charger. Properties: connectorTypes, currentType, minPowerInKilowatts (default: 0, range: 0-1000), maxPowerInKilowatts (range: 1-1000), status, capabilities
• fuelStation - Properties: fuelTypes (array of: e100, e95, e85, diesel, cng, hydrogen, lpg, biodiesel)

Preferences for results.
Properties:

• geometry - Indicates a preference for results around a preferred geometry. When a point is provided as the preferred geometry, results closer to the point may generally appear higher in the result list, subject to other ranking factors.

  • type (required): "point"
  • coordinates (required, PositionWithoutElevation): position array [longitude, latitude] in degrees

A list of discover results. Each result can be one of the following types: discoverAction, poi, address, street, intersection, area.

Unique identifier of the result.
Example: qv3FAP2e0GnYgS-KeAgciA

Type of the result.
Values: poi, address, street, intersection, area, discoverAction

Localized display title for the result.

An ordered list of localized text lines that help to understand the result, such as providing additional information or display a colloquial, region-specific address.

Distance of the result from the origin in meters.

GeoJSON Point position of the location. Contains type (Point) and coordinates (array of [longitude, latitude]).

Follow-up request information for getting more details. Contains operation, pathParameters, queryParameters, and optional requestBody.

Country name.

ISO 3166-1 alpha-2 country code.

State or province.

ISO 3166-2 country subdivision code.

County.

Named area.

City or town.

Subdivision of a city.

Smaller subdivision of a city.

Neighborhood.

Postal code (ZIP code).

An address component which represents the name for a postal code that is related to a single administrative area, city, town, or other populated place.

Extended postal code (availability dependent on region).

Name of the street.

The building number on the street.

IANA timezone identifier.
Example: Europe/Berlin

Current UTC offset in seconds, takes into account daylight saving time if applicable.
Example: 7200

Types of places of interest associated with this place of interest. Each object contains id, name, and optional parentId.

Brands associated with this place of interest. Each object contains id and name. The id is a case-sensitive uppercase brand identifier (e.g. STARBUCKS).

The opening hours for specific dates. The date is in the local time of the place. Each object contains date (RFC 3339 format "YYYY-MM-DD") and timeRanges array with start, end, and utcOffsetSeconds.

Contact information. Each object contains type (label like "Reservations", "Customer Support"), phones (array), emails (array), and websites (array).

Array of charging station objects. Each contains id and chargingPoints array. Each charging point has evseId, status, physicalReference, capabilities array, and connectors array. Each connector includes type, ratedPowerInKilowatts, currentType, currentInAmperes, and voltageInVolts.

Type of area.
Values: country, countrySubdivision, countrySecondarySubdivision, countryTertiarySubdivision, municipality, municipalitySubdivision, municipalitySecondarySubdivision, postalCode, neighborhood, block

OK: A list of places.

Bad Request: The request was invalid.

Forbidden: The API Key is missing, inactive, invalid, not entitled to use this API, or the geopolitical view is not available for the request origin.

Not Found: The requested resource could not be found.

Too Many Requests: The API Key is over QPS (Queries per second).

Server Error: The service was unable to process your request. Contact support to resolve the issue.

A unique identifier that must be a 36-character hyphenated UUID (v4 or v7) in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12, 36 characters including hyphens), for a places search flow session.

A unique identifier for tracking the request across services. If the client provided a Tracking-Id in the request header, this value is echoed back. If not provided, TomTom systems will generate a tracking identifier automatically. This identifier enables effective request tracing and correlation in logs.

Indicates the format of the response as chosen by the client.
Value: application/json

The HTTP Content-Language representation header is used to describe the language(s) intended for the audience.

A unique identifier for this particular occurrence of the problem that SHOULD be human-readable.

It is intended as an aid to developers and is not suitable for exposure to end users. Do not build logic on the content of this field and rely on the code instead.

The target of the error (e.g., the name of the property in error).

Additional details about the error.

The contents of this object are service-defined. Each nested innerError object represents a higher level of detail than its parent.