Parking Locations v2

Purpose

The On-Street Parking API Parking Locations endpoint provides information about on-street parking location probability in the requested point and within the area described by the given radius. Additionally, it can provide parking location ID’s and aggregated probability calculated upon the requested area.

Request data

HTTPS Method: GET

• Constants and parameters enclosed in curly brackets {} must be replaced with their values.
• See the following Request parameters section with the required and optional parameters tables for these values.

URL format

1
https://{baseURL}/maps/orbis/on-street-parking/locations?apiVersion=2&key={Your_API_Key}&point={longitude},{latitude}&radiusInMeters={radius}&parkingDataAtDateTime={timestamp}&maxResults={maxResults}&selectionType={selectionType}

URL example

1
https://api.tomtom.com/maps/orbis/on-street-parking/locations?apiVersion=2&key={Your_API_Key}&point=151.20807219091648,-33.872809993512945&radiusInMeters=100&parkingDataAtDateTime=2022-01-01T00:00:01Z&maxResults=150&selectionType=probability

curl command example

1
curl 'https://api.tomtom.com/maps/orbis/on-street-parking/locations?apiVersion=2&key={Your_API_Key}&point=151.20807219091648,-33.872809993512945&radiusInMeters=100&parkingDataAtDateTime=2022-01-01T00:00:01Z&maxResults=150&selectionType=probability'

Request parameters

The following table describes the parameters that can be used in a request.

• Required parameters must be used or the call will fail.
• Parameters and values are case-sensitive.
• Optional parameters may be used.

Request headers

The following data table lists HTTP request headers of particular interest to clients of the Parking locations endpoint.

Attributes

Attributes header

A list of response fields to return, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
Attributes header must contain at least one valid top-level field. Using only a top-level * wildcard is not allowed.
When a field name refers to a non-primitive object, all its non-EXPLICIT subfields are returned by default unless further restricted in the header. EXPLICIT fields (as documented per API) are only returned when they are explicitly listed in Attributes (they are never included solely by selecting their parent or by using *).
The * wildcard may be used only at non–top-level positions to include all non-EXPLICIT subfields of the selected object.

Syntax:

• <field-list> ::= <field> (',' <field>)*
• <field> ::= <name> ('.' <field> | <field-set>)?
• <field-set> ::= '(' <field-set-list> ')'
• <field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
• <name> ::= one or more alphabetic characters

Note:

• All listed field names must exist in the response schema; unknown fields result in an error.
• Response schema can be found in Response schema section.
• APIs may restrict which fields are allowed in Attributes. Disallowed-but-existing fields result in an error.
• New fields may be added over time. When they are marked EXPLICIT, they are not returned unless explicitly requested via Attributes, preserving backward compatibility and performance.

Examples:

• easeOfParkingPercentage
• easeOfParkingPercentage, locations.probabilityPercentage
• `locations.*

Attributes-Exclude header

A list of response fields to omit, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
Any field listed in Attributes-Exclude, including its entire sub-tree, is omitted from the response, regardless of whether it was included implicitly or explicitly via the Attributes header. Exclusion always overrules inclusion.
The format of the field list is the same “listed dot-notation” used for the Attributes header:

Syntax:

• <field-list> ::= <field> (',' <field>)*
• <field> ::= <name> ('.' <field> | <field-set>)?
• <field-set> ::= '(' <field-set-list> ')'
• <field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
• <name> ::= one or more alphabetic characters

Notes:

• The exclusion list is applied to the result of the inclusion list. If a parent field is excluded, all of its children are excluded, even if some of those children were explicitly listed in Attributes.
• When Attributes header inclusion list is not present in the request, then Attributes-Exclude header value is ignored.
• Listed field names in Attributes-Exclude must exist in the response schema; unknown fields result in an error.
• Response schema can be found in Response schema section.
• APIs may restrict which fields are allowed in Attributes-Exclude. Disallowed-but-existing fields result in an error.
• Fields may occur multiple times in Attributes-Exclude (not recommended, but not an error).
• Some overlap between Attributes and Attributes-Exclude is allowed. In case of overlap, the exclusion takes precedence.
• Whether a field is EXPLICIT or not does not change the semantics of exclusion: if it is present in Attributes-Exclude, it is omitted whenever it would otherwise have been returned.
• If all fields are excluded, then HTTP 204 No Content response is returned.

Example:
Attributes: locations.*
Attributes-Exclude: locations.id
Results in returning properties for all locations present in the response except id property.

Response data

Successful response

For a single valid request, the Parking Locations endpoint returns its response body in JSON format.

Response schema

The exclamation mark ! means that a particular field cannot be equal to null, for example:

• Point! - value cannot be equal to null
• [Point!] - array of non-null objects
• [Point]! - array cannot be null, but it can contain null values

1
type Query {
2
  easeOfParking: Float
3
  locations: [Location]
4
}

1
type Location {
2
  probability: Float
3
  id: String
4
  coordinates: [[Float!]!]!
5
}

Response field structure

The following table describes JSON element fields that appear in a response.

Response examples

Example request & response

1
https://api.tomtom.com/maps/orbis/on-street-parking/locations?apiVersion=2&point=151.20807219091648,-33.872809993512945

1
{
2
  "easeOfParkingPercentage":0.37,
3
  "locations":[
4
    {
5
      "id":"00000000-000c-719d-0009-20d4467654e2",
6
      "probabilityPercentage":0.37,
7
      "coordinates":[
8
        [
9
          151.2080673806,
10
          -33.8724552573
11
        ],
12
        [
13
          151.2080566518,
14
          -33.8726078057
15
        ]
16
      ]
17
    },
18
    {
19
      "id":"00000000-000c-719d-0009-20d4467654e2",
20
      "probabilityPercentage":null,
21
      "coordinates":[
22
        [
23
          151.2080566518,
24
          -33.8726859588
25
        ],
26
        [
27
          151.2080539696,
28
          -33.8728385067
29
        ]
30
      ]
31
    }
32
    ...]
33
}

Error response

The Parking Locations endpoint, for an invalid single request, returns a response body in JSON format.

Response field structure

Response example

1
{
2
  "detailedError": {
3
    "code": "INVALID_REQUEST",
4
    "message": "Missing required parameter: point."
5
  }
6
}

HTTP response codes

HTTP response headers

The following data table contains response headers sent back from an API server.