Available Maps

Important Note Explore ready-to-use traffic reports and data visualizations immediately by signing up for a 30-day free trial on the MOVE Portal. Once registered, you’ll receive an API key to start using the Traffic Analytics APIs right away. Alternatively, you may contact our Sales team for a tailored solution.

Purpose

Use this endpoint to find the map versions available for an area. The returned version can be passed as the optional mapVersion field of the Selected Link analysis creation endpoint and the Flow matrix analysis creation endpoint, so that map-matching runs on a map that matches your analysis period.

The endpoint takes the map generation as the last path segment. A version 2 analysis runs on TomTom Orbis Maps, so use ORBIS.

Request data

HTTPS Method: `GET`

Format

get

URL request format

1
https://api.tomtom.com/origindestination/1/maps/{mapType}?boundingBox={lonMin,latMin,lonMax,latMax}&from={startDate}&to={endDate}&onlyVolumeVersions={onlyVolumeVersions}&key={Your_API_Key}

Example

get

URL request example

1
https://api.tomtom.com/origindestination/1/maps/ORBIS?boundingBox=2.28974,48.87338,2.29797,48.87478&from=2026-03-02&to=2026-03-08&key={Your_API_Key}

Request parameters

The following table describes all request parameters that can be used. Required parameters must be included for the call to succeed. Optional parameters may be used.

Required parameters	Description
`key` string	Authorization key for access to the API. Value: Your valid API Key.
`mapType` string	Path segment that determines the map generation used. Possible values: `ORBIS` - TomTom Orbis Maps combine open map data and TomTom proprietary data that is validated, fresh, and of the highest quality. They also integrate data sources from Overture Maps Foundation™, OpenStreetMap (OSM), partner data, and sensor-derived observations (SDOs). Read more about Orbis maps.
`boundingBox` string	Coordinates defining a boundingbox in the following format: longitudeLeftDown,latitudeLeftDown,longitudeRightUpper,latitudeRightUpper. Value: 4 comma-separated float numbers.

Required parameters

Description

key
string

Authorization key for access to the API.

Value: Your valid API Key.

mapType
string

Path segment that determines the map generation used.
Possible values: ORBIS - TomTom Orbis Maps combine open map data and TomTom proprietary data that is validated, fresh, and of the highest quality. They also integrate data sources from Overture Maps Foundation™, OpenStreetMap (OSM), partner data, and sensor-derived observations (SDOs). Read more about Orbis maps.

boundingBox
string

Coordinates defining a boundingbox in the following format: longitudeLeftDown,latitudeLeftDown,longitudeRightUpper,latitudeRightUpper.

Value: 4 comma-separated float numbers.

Optional parameters	Description
`from` string	First day of the period you intend to analyze, in `YYYY-MM-DD` format. Together with `to` it drives the `recommended` flag of every returned map version. Also required when `onlyVolumeVersions=true` is used. Default value: none. Without it the `recommended` flag is not returned.
`to` string	Last day of the period you intend to analyze, in `YYYY-MM-DD` format. The `recommended` flag is calculated only when both `from` and `to` are given; with either of them missing the flag is not returned at all. Default value: none.
`onlyVolumeVersions` boolean	When `true`, the response contains exactly the one map version that carries the estimated traffic volume data for the calendar year of `from`, instead of the list of available maps. Used to fill in `mapVersion` when creating a Selected Link version 2 analysis with the `VOLUME` enhanced metric; see Enhanced metrics for the full description. Requires `from`, and works only for years with published traffic volume data. Default value: `false`

Optional parameters

Description

from
string

First day of the period you intend to analyze, in YYYY-MM-DD format.

Together with to it drives the recommended flag of every returned map version. Also required when onlyVolumeVersions=true is used.

Default value: none. Without it the recommended flag is not returned.

to
string

Last day of the period you intend to analyze, in YYYY-MM-DD format.

The recommended flag is calculated only when both from and to are given; with either of them missing the flag is not returned at all.

Default value: none.

onlyVolumeVersions
boolean

When true, the response contains exactly the one map version that carries the estimated traffic volume data for the calendar year of from, instead of the list of available maps. Used to fill in mapVersion when creating a Selected Link version 2 analysis with the VOLUME enhanced metric; see Enhanced metrics for the full description.

Requires from, and works only for years with published traffic volume data.

Default value: false

Response data

The response returns the map versions available in the bounding box, sorted by release time, newest first. For ORBIS, versions older than the first production Orbis map are not listed and only one version per calendar month is returned.

Response example

Response body - JSON

1
{
2
    "maps": [
3
        {"type":"OPEN_DSEG","version":"{map_version}","releaseTimestamp":"1772409600000","recommended":true},
4
        {"type":"OPEN_DSEG","version":"{previous_map_version}","releaseTimestamp":"1769904000000","recommended":false},
5
        {"type":"OPEN_DSEG","version":"{older_map_version}","releaseTimestamp":"1767225600000","recommended":false}
6
    ]
7
}

Response structure

Field	Description
`maps` array	Available map versions, sorted by release time, newest first.
`maps[].type` string	Name of the map the version belongs to.
`maps[].version` string	Map version. Pass this value as `mapVersion` when creating an analysis. An `ORBIS` version has the form `YYYY.MM.NNNN`. Do not construct the value yourself - always pass back a version this endpoint returned.
`maps[].releaseTimestamp` string	Release time of the map version, in milliseconds since the Unix epoch.
`maps[].recommended` boolean	Whether the map version covers the period given by `from` and `to`. Returned only when both parameters are present, and always `true` when `onlyVolumeVersions=true` is used.

Errors

If there is an error in the supplied parameters or any other internal problem, an error response is generated in the requested format.

Response codes

Code	Meaning & possible causes
`200`	OK
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`500`	Internal Server Error