Developer

Parking Locations

Request Access
Service version: 1
Last edit: 2024.07.17
Automotive only
TomTom Orbis Maps

Important note

This API is unavailable on a Freemium or Pay As You Grow (PAYG) basis.
Click the Request Access button above to contact our Sales team.

Important notes:

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

get
URL format
https://{baseURL}/maps/orbis/on-street-parking/locations?apiVersion=1&key={Your_API_Key}&point={latitude},{longitude}&radius={radius}&targetTime={timestamp}&fields={fields}&maxLocations={maxLocations}&selectionType={selectionType}

URL example

get
URL example
https://api.tomtom.com/maps/orbis/on-street-parking/locations?apiVersion=1&key={Your_API_Key}&point=-33.872809993512945,151.20807219091648&radius=100&targetTime=2022-01-01T00:00:01Z&fields=probability&maxLocations=150&selectionType=probability

curl command example

get
curl command example
curl 'https//api.tomtom.com/maps/orbis/on-street-parking/locations?apiVersion=1&key={Your_API_Key}&point=-33.872809993512945,151.20807219091648&radius=100&targetTime=2022-01-01T00:00:01Z&fields=probability&maxLocations=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.

Required parameters

Description

baseURL


string

Base URL for calling the API.


Value: api.tomtom.com

key


string

The authorization key for access to the API.


Value: Your valid API Key.

point


float,float

The coordinates of the point close to which on-street parking locations are searched for.


They must be comma-separated and calculated using EPSG:4326 projection (also known as WGS84 ).


Value: latitude,longitude

Optional parameters

Description

apiVersion integer

A version of the API to call. If the parameter is set, it will overwrite the value stored in TomTom-Api-Version header. Value: The current version is 1.

radius


positive integer

Maximum radius in a straight line from a point to a parking location, measured in meters.


Default value: 100


Values: 1..1000

targetTime


string

The time value used to determine the parking data.

  • Parking data is time-dependent; the target time can be specified to get the data for the particular date or hour.

  • Only future dates and time values are supported.

  • The only supported time standard is UTC.

Default value: current timestamp


Values: timestamp in the format of YYYY-MM-DDThh:mm:ssZ

fields


string

This parameter allows the customization of response content by choosing which fields (data in the response) are displayed.


The names of the fields must be specified as a comma-separated list.


Default value: probability,coordinates


Values:

  • easeOfParking

  • probability

  • coordinates

  • id

  • parkAndRide

maxLocations


integer

The maximum number of parking locations that are returned.


Default value: 20


Values: 1..200

selectionType


string

The method of selecting the returned locations.


Default value: distance


Values:

  • distance : The closest locations to a requested point are returned.

  • probability : Locations with the highest probability field are returned.

Request headers

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

Note: There are no required headers in this endpoint.

Optional headers

Description

TomTom-Api-Version integer

Contains a version of the API to call. Value: The current version is 1.

Accept-Encoding

Contains the content encoding (usually a compression algorithm), that the client is able to understand.


Value: gzip

Tracking-ID

Specifies an identifier for the request. It can be used to trace a call. The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$' An example of the format that matches this regular expression is a UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1 ). For details check RFC 4122. If specified, it is replicated in the Tracking-ID response header. It is only meant to be used for support and does not involve tracking of you or your users in any form.


Value: <string>

Response data

Successful response

  • For a single valid request, the Parking Locations endpoint returns its response body in JSON format.
  • The fields that appear in a response depend on a value of the {fields} request parameter.
  • By default, the client only gets the probability and coordinates data.

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
Query
1type Query {
2  easeOfParking: Float
3  locations: [Location]
4}
Coordinates
1type Coordinates {
2  longitude: Float
3  latitude: Float
4}
Location
1type Location {
2  probability: Float
3  parkAndRide: Boolean
4  id: String
5  coordinates: [Coordinates]
6}

Response field structure

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

Field

Description

locations


array

It contains available parking locations. If there is no data in the requested area the array is empty.

coordinates


array

It contains geometry of a particular on-street parking location in the form of a linestring - longitudes and latitudes in a EPSG:4326 projection ( WGS84 ).

probability


float

It is a probability of finding an available on-street parking location belonging to the given coordinates.


If probability equals null in a particular parking location, it means that the parking location coordinates are available, but currently there is no probability associated with it.


Values: null,0.0..1.0

easeOfParking


float

It is an aggregated probability of finding an available parking location, calculated upon all of the locations available in the requested area.


If easeOfParking equals null , it means that one of the following situations occurs:

  • All of the available parking locations have probability equal to null.

  • There is no on-street parking data in requested area.

Values: 0.0..1.0

id


string

This is the parking location ID, coming directly from our parking data provider. It can be used to combine data from different sources.


Value: A parking location ID.

parkAndRide


boolean

Indicates if it is a parking location with public transport connections that allows people to leave their vehicles and transfer to a means of public transport for the remainder of the journey.


Value: true or false

Response examples

Example 1 - request & response

get
Request example 1
maps/orbis/on-street-parking/locations?apiVersion=1&point=-33.872809993512945,151.20807219091648
Response example 1 - JSON
1{
2  "locations":[
3    {
4      "probability":0.37,
5      "coordinates":[
6        {
7          "longitude":151.2080673806,
8          "latitude":-33.8724552573
9        },
10        {
11          "longitude":151.2080566518,
12          "latitude":-33.8726078057
13        }]
14    },
15    {
16      "probability":null,
17      "coordinates":[
18        {
19          "longitude":151.2080566518,
20          "latitude":-33.8726859588
21        },
22        {
23          "longitude":151.2080539696,
24          "latitude":-33.8728385067
25        }]
26    }
27    ...]
28}

Example 2 - request & response

get
Request example 2
https://api.tomtom.com/maps/orbis/on-street-parking/locations?apiVersion=1&point=-33.872809993512945,151.20807219091648&fields=easeOfParking
Response example 2 - JSON
1{
2  "easeOfParking": 0.46
3}

Example 3 - request & response

get
Request example 3
https://api.tomtom.com/maps/orbis/on-street-parking/locations?apiVersion=1&point=-33.872809993512945,151.20807219091648&fields=coordinates,probability,easeOfParking,id
Response example 3 - JSON
1{
2  "easeOfParking":0.37,
3  "locations":[
4    {
5      "id":"00000000-000c-719d-0009-20d4467654e2",
6      "probability":0.37,
7      "coordinates":[
8        {
9          "longitude":151.2080673806,
10          "latitude":-33.8724552573
11        },
12        {
13          "longitude":151.2080566518,
14          "latitude":-33.8726078057
15        }]
16    },
17    {
18      "id":"00000000-000c-719d-0009-20d4467654e2",
19      "probability":null,
20      "coordinates":[
21        {
22          "longitude":151.2080566518,
23          "latitude":-33.8726859588
24        },
25        {
26          "longitude":151.2080539696,
27          "latitude":-33.8728385067
28        }]
29    }
30    ...]
31}

Error response

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

Response field structure

Field

Description

detailedError


object

Main object of the error response.

code


string

One of a server-defined set of error codes.

message


string

A human-readable description of the error code.

Response example

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

HTTP response codes

Code

Meaning & possible causes

200

OK

400

Bad request

403

Forbidden: The supplied API Key is not valid for this request.

405

Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource.

429

Too Many requests: Too many requests were sent in a given amount of time for the supplied API Key.

500

Internal Server Error

503

Service currently unavailable: The service is currently unavailable.

596

Service Not Found: Unknown version of the service.

HTTP response headers

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

Header

Description

Access-Control-Allow-Origin

Indicates that cross-origin resource sharing (CORS) is allowed.


Value: *

Allow

Lists the set of supported HTTP methods. The header is sent in case a 405 HTTP response code is returned.


Value: GET, HEAD

Content-Encoding

Indicates which encodings were applied to the response body.


Value: gzip

Content-Length

Contains information about the size of the response body.


Value: <decimal number>

Content-Type

Indicates the media type of the resource returned.


Value: <application/json; charset=utf-8>

Date

Contains the date and time at which the message was originated. For details check RFC 7231.
Value: <http-date>

Tracking-ID

An identifier for the request. If the Tracking-ID header was specified in the request, it is replicated in the response. Otherwise, it is generated automatically by the service. For details check RFC 4122. It is only meant to be used for support and does not involve tracking of you or your users in any form.


Value: <string>