REST API Overview¶

This introductory chapter provides an overview of the public Map Content API operations, conversions and formats. Map Content API is a set of JSON–over–HTTP operations that allows discovering, requesting, filtering and retrieving TomTom Maps products.

Overview of API operations¶

The following table summarises the operations supported by Map Content API, together with links to relevant documentation. As can be observed, the operations are divided in two logical areas: discovery and content.

Task to be performed	For more details see…
List all product families Get a product family by ID List all products List all products of a product family Get a product by ID List all releases List all releases of a product List latest releases of a product family List updates to get to the latest product version	Discovery REST API
Get a release by ID Get a release’s content by ID	Content REST API
Get the service status Get service build information	Internal REST API

Authentication and Authorization¶

With each API call, an Authorization request header must be set with the Bearer token as value.

Example for API Key ‘123’:

Authorization: Bearer 123

A 401 UNAUTHORIZED response status will be returned if the authorization has been refused for the provided API key. A 403 FORBIDDEN response status will be returned if the token provides insufficient access rights to a specific API endpoint. A 403 FORBIDDEN response status might still be returned unrelated to the provided credentials.

The bearer token can be found on the Account page of the Map Content Portal, which is reachable through the drop-down menu that opens when clicking the profile name in the top right corner.

Transport Security¶

Map Content API is configured to enforce TLS, a 403 FORBIDDEN response status code will be returned if HTTP is used.

Legal Restrictions¶

Governments might impose legal restrictions on handling specific data. Some data may only be downloaded from specific countries. In case of a geographical restriction a 403 FORBIDDEN response status code will be returned when the client is not in the white-listed country. The Map Content API provides the geoRestrictions field on content to denote from which countries the data can be downloaded.

Response¶

Responses will be in the JSON format. Certain APIs support metalink4 when specified.

Note

IDs are unique, are stable and don’t change for a given object once assigned.

Note

Date fields are serialised in ISO-8601 format and in the UTC timezone, for example 2023-11-07T10:35:32.000Z.

Filtering¶

Data can be filtered on certain properties. All calls with a list response accept an optional filter parameter which can be used to query for specific data.

When an invalid filter expression is provided, the Map Content API will respond with a 400 Bad Request response code and an error message.

Filter syntax was inspired by OData2 filters. A comprehensive list of supported operators and functions is provided below.

Filter Syntax¶

A filter consists of one or more expressions. An expression consists of an operator and two literals or properties.

Properties¶

A property is a field of a resource. Below are filter examples that can be applied to listing products.

Filter

Output

/products?filter=name eq ‘EUR’

All products named EUR

/products?filter=family.id eq 1

/products?filter=family/id eq 1

All products of a family with id 1

Note

If you are only interested in products of a single family, there is a dedicated API method to list products of a family. A similar call exists to list releases of a product.

Literal types¶

Name	Example
numeric	1
string	‘EUR’
datetime	datetime’2023-11-01T00:00’
empty tags	‘{}’

Operators¶

Name	Description	Supported literal types
eq	equal	numeric, string, datetime
ne	not equal	numeric, string, datetime
lt	less than	numeric, datetime
le	less than or equal	numeric, string, datetime
gt	greater than	numeric, datetime
ge	greater than or equal	numeric, string, datetime

Expression Operators¶

Name	Description	Example
and	both expressions should evaluate to true	/products?filter=family.id eq 10 and name eq ‘EUR’
or	one of expressions should evaluate to true	/products?filter=name eq ‘OCE’ or name eq ‘NAM’
not	negates an expression	/products?filter=not(family.id eq 10 or name eq ‘NAM’)
()	groups expressions	/products?filter=(name eq ‘OCE’ or name eq ‘NAM’) and family.id eq 10

String Functions¶

Name	Example
startswith	/families?filter=startswith(name, ‘MultiNet’)
endswith	/products?filter=endswith(name, ‘AM’)
length	/products?filter=length(name) eq 3
substringof	/families?filter=substringof(‘POI’, name)
tolower	/products?filter=tolower(name) eq ‘eur’
toupper	/families?filter=toupper(name) eq ‘MULTINET’

Example Requests¶

Find all releases due after 01 Nov 2023 12:00 and being released before 28 Dec 2023 12:00:

GET /releases?filter=dueDate gt datetime'2023-11-01T12:00'
                     and state.type eq 'released'
                     and state.date lt datetime'2023-12-28T12:00' HTTP/1.1
Host: example.com
Accept: application/vnd.tomtom.mcapi+json
Authorization: Bearer <api_key>

Find all releases where a tag with name ‘tag_key’ starts with ‘val’:

GET /releases?filter=startswith(tags.tag_key, 'val')
Host: example.com
Accept: application/vnd.tomtom.mcapi+json
Authorization: Bearer <api_key>

Find all releases where the tags are empty:

GET /releases?filter=tags eq '{}'
Host: example.com
Accept: application/vnd.tomtom.mcapi+json
Authorization: Bearer <api_key>

Sorting and Pagination¶

Sorting¶

Data can be sorted on certain properties. Sorting can be ascending or descending.

Sorting Request Parameters¶

Name

Description

Required

sort

Sorting criteria in the format: property(<field_name>[,asc|desc]).

Default sort order is ascending. Multiple sort criteria are supported.

No

Example Request¶

Sorting releases in reverse chronological order using the key desc:

GET /releases?sort=state.date,desc&filter=state.type eq 'released' HTTP/1.1
Host: example.com
Accept: application/vnd.tomtom.mcapi+json
Authorization: Bearer <api_key>

Nested sorting¶

Multiple sort parameters can be used to nest sorting.

Example Request¶

Sort all releases first by product ID and then by version:

GET /releases?sort=product.id&sort=version HTTP/1.1
Host: example.com
Accept: application/vnd.tomtom.mcapi+json
Authorization: Bearer <api_key>

Pagination¶

When making API calls to Map Content API, the default page size for returned resources is 50. The page size is configurable through a request parameter within the range (0..2000). The pagination uses zero-based numbering.

Pagination Request Parameters¶

Name	Description	Required
page	Results page you want to retrieve (0..N)	No
size	Number of records per page.	No

Example Request¶

Getting the latest release through sorting and limiting on returned results.

GET /releases?page=0&size=1&sort=state.date,desc HTTP/1.1
Host: example.com
Accept: application/vnd.tomtom.mcapi+json
Authorization: Bearer <api_key>

Versioning¶

Map Content API versions all REST endpoints both by application version and by resource version. The Accept header is used as a means to specify the desired version.

Media Types¶

Accepted System-Wide¶

The following media types are used by all REST endpoints.

Latest version of the resource:

application/json
application/vnd.tomtom.mcapi+json

Example:

curl -X GET 'https://example.com/releases'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

Version of the resource as of Map Content API version <version>:

application/vnd.tomtom.mcapi-v<version>+json
application/vnd.tomtom.mcapi-<version>+json

Example:

curl -X GET 'https://example.com/releases'
    --header 'Accept: application/vnd.tomtom.mcapi-2.4.0+json'
    --header 'Authorization: Bearer <api_key>'

Accepted by Specific Calls¶

The following media types are used by specific REST endpoints in addition to the media types mentioned above.

Endpoint	Media Type	Returns
`GET /releases`	`application/vnd.tomtom.mcapi.releasesummary+json`	Latest release summaries
`GET /releases`	`application/vnd.tomtom.mcapi.releasesummaryv2+json`	Release summaries v2
`GET /releases/{ID}`	`application/vnd.tomtom.mcapi.releasesummaryv1+json`	Release summaries v1
`GET /releases/{ID}`	`application/vnd.tomtom.mcapi.release+json`	Latest release
`GET /releases/{ID}`	`application/vnd.tomtom.mcapi.releasev2+json`	Release v2
`GET /releases/{ID}`	`application/vnd.tomtom.mcapi.releasev1+json`	Release v1
`GET /releases/{ID}/notes`	`application/vnd.tomtom.mcapi.releasenotes+json`	Latest release
`GET /releases/{ID}/notes`	`application/vnd.tomtom.mcapi.releasenotesv2+json`	Release v2
`GET /releases/{ID}/notes`	`application/vnd.tomtom.mcapi.releasenotesv1+json`	Release v1

Response Payload Changes¶

Release v1 -> v2
- "state" changed from a field to an object. Full json example of a release.
- "releaseDate" removed
- "dueDate" added

Same for release summary.

Release notes v1 -> v2
- "category" added to the release notes API
- The release notes are categorized into RELEASE_NOTE or META_INFORMATION. All release notes of a category are stored in the "zones" key:

{
  "notes": [
    {
      "category": "RELEASE_NOTE",
      "zones": [
        {
          ...
        }
      ]
    }
  [
{

Error Handling¶

When not specifying a mandatory parameter, using an incorrect or non-existing value for a parameter. The response uses the standard HTTP response status code as detailed below. This is also applicable when parameters are replaced by resources.

`200 OK`	The operation was successful
`400 Bad Request`	A client-related error occurred (check arguments and syntax)
`401 Unauthorized`	The authorization has been refused for the provided API key
`404 Not Found`	The requested resource does not exist
`500 Internal Server Error`	A server-related error occurred