Migration Guide

This guide helps you migrate to the On-Street Parking Orbis v2 endpoints. It covers differences from both the TomTom Maps v1 endpoints and the Orbis v1 endpoints.

General changes

Changes in authentication

Attributes mechanism

In Orbis v2 a unified Attributes mechanism is introduced for controlling response content. It provides a flexible way to specify which attributes and data fields to include or exclude in API responses.

The Attributes mechanism consists of:

• Attributes request header — Specifies which JSON response fields or attributes to include (required).
• Attributes-Exclude request header — Specifies which fields or attributes to omit (optional).

This mechanism replaces the previous fields query parameter for JSON response fields selection, providing more granular control and a consistent interface across all endpoints.

For detailed information about Attributes syntax, available values, and usage examples, refer to the Attributes section in each respective Orbis v2 endpoint documentation.

Error message format

Error messages are returned in JSON format in the following structure:

1
{
2
  "detailedError": {
3
    "code": "BAD_REQUEST",
4
    "message": "Invalid tile position arguments"
5
  }
6
}

Migrating from TomTom Maps

This section describes the changes when migrating from the TomTom Maps v1 On-Street Parking endpoints to the Orbis v2 endpoints.

Parking Locations endpoint

Where do I find the new endpoint

The new Orbis v2 Parking Locations endpoint has the following path:

1
https://api.tomtom.com/maps/orbis/on-street-parking/locations?key={Your_API_Key}&point={longitude},{latitude}

instead of:

1
https://api.tomtom.com/parking/services/{versionNumber}/locations?key={Your_API_Key}&point={latitude},{longitude}

Changes in the endpoint base path

Changes in request query parameters

Changes in request headers

Changes in response fields

Response example comparison

TomTom Maps v1 response:

1
{
2
  "easeOfParking": 0.37,
3
  "locations": [
4
    {
5
      "probability": 0.37,
6
      "coordinates": [
7
        { "longitude": 151.2080673806, "latitude": -33.8724552573 },
8
        { "longitude": 151.2080566518, "latitude": -33.8726078057 }
9
      ]
10
    }
11
  ]
12
}

Orbis v2 response:

1
{
2
  "easeOfParkingPercentage": 0.37,
3
  "locations": [
4
    {
5
      "probabilityPercentage": 0.37,
6
      "coordinates": [
7
        [151.2080673806, -33.8724552573],
8
        [151.2080566518, -33.8726078057]
9
      ]
10
    }
11
  ]
12
}

Vector Tiles endpoint

Where do I find the new endpoint

The new Orbis v2 Vector Tiles endpoint has the following path:

1
https://api.tomtom.com/maps/orbis/on-street-parking/vector/tile/{zoom}/{x}/{y}?key={Your_API_Key}

instead of:

1
https://api.tomtom.com/parking/map/{versionNumber}/tile/{zoom}/{x}/{y}.{format}?key={Your_API_Key}

Changes in the endpoint base path

Changes in request query parameters

Changes in request headers

Changes in response content type

Changes in tag behavior

• In TomTom Maps v1 tags were split into default (probability) and on-demand (id) categories, controlled by the tags query parameter.
• In Orbis v2, both probability and id tags are always returned. The tags parameter has been removed.

Migrating from Orbis v1

This section describes the changes when migrating from the Orbis v1 On-Street Parking endpoints to the Orbis v2 endpoints.

Parking Locations endpoint

Endpoint URL

The base path remains the same. Only the API version changes:

1
https://api.tomtom.com/maps/orbis/on-street-parking/locations

1
https://api.tomtom.com/maps/orbis/on-street-parking/locations

Changes in request query parameters

Changes in request headers

Changes in response fields

Response example comparison

Orbis v1 response:

1
{
2
  "easeOfParking": 0.37,
3
  "locations": [
4
    {
5
      "probability": 0.37,
6
      "coordinates": [
7
        { "longitude": 151.2080673806, "latitude": -33.8724552573 },
8
        { "longitude": 151.2080566518, "latitude": -33.8726078057 }
9
      ]
10
    }
11
  ]
12
}

Orbis v2 response:

1
{
2
  "easeOfParkingPercentage": 0.37,
3
  "locations": [
4
    {
5
      "probabilityPercentage": 0.37,
6
      "coordinates": [
7
        [151.2080673806, -33.8724552573],
8
        [151.2080566518, -33.8726078057]
9
      ]
10
    }
11
  ]
12
}

Vector Tiles endpoint

Endpoint URL

The base path changes and the API version changes:

1
https://api.tomtom.com/maps/orbis/on-street-parking/tile/{zoom}/{x}/{y}.{format}

1
https://api.tomtom.com/maps/orbis/on-street-parking/vector/tile/{zoom}/{x}/{y}

Changes in the endpoint path

Changes in request query parameters

Changes in request headers

Changes in response content type

Changes in tag behavior

• In Orbis v1, tags were split into default and on-demand categories (same as TomTom Maps v1), controlled by the tags query parameter.
• In Orbis v2, both probability and id tags are always returned. The tags parameter has been removed.