Locations

Service version: v1
Last edit: 2023.02.28

Purpose

The Locations endpoint provides access to locations created by users from your organization.

Request data

HTTPS Method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for these values. The generic URL format is as follows.

URL format

GET
URL request format
https://enterprise-api.rer.tomtom.com/api/v1/locations/?key={Your_API_Key}

curl command format

GET
Request curl command format
curl 'https://enterprise-api.rer.tomtom.com/api/v1/locations/?key={Your_API_Key}'

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.
  • Optional parameters may be used.

Required parameters

Description

baseURL


string

Base URL for calling the API.
Value: enterprise-api.rer.tomtom.com

versionNumber
string

Service version.
Value: The current value is v1.

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

page
integer

The page number.
Value: An integer

size
integer

Gets the number of items that should be returned in one call.
Value: An integer.

Optional parameters

Description

country
string

The ISO Country code.
Value: A string.

createdBy
string

Email of the event reporter
Value: A string.

sort
array (of strings)

The sort facility.
Value: lastModifiedAt;desc or lastModifiedAt;asc

Request headers

Header

Description

Accept-Encoding

Optional. Enables response compression.


Value: gzip

Response data

Response body

For illustrative purposes the example below is neatly indented and includes all possible response fields.

  • Actual responses are more compact and the fields present will vary based on the result type and the data available.
  • See the following response field documentation for more information.

When requesting JSON output, the response has the following structure:

Response body structure - JSON
1{
2  "entities": [
3    {
4      "locationId": 0,
5      "locationName": "string",
6      "locationEffect": "string",
7      "isBidirectional": true,
8      "startDateTime": "2020-06-03T15:59:26.862Z",
9      "startDateTimeZoned": "2020-06-03T15:59:26.863Z",
10      "endDateTime": "2020-06-03T15:59:26.863Z",
11      "endDateTimeZoned": "2020-06-03T15:59:26.863Z",
12      "createdAt": "2020-06-03T15:59:26.863Z",
13      "createdBy": "string",
14      "geometry": "string",
15      "liveStatusAB": "string",
16      "liveStatusBA": "string",
17      "eventId": 0,
18      "eventName": "string",
19      "eventType": "string",
20      "eventTimeZone": "string",
21      "eventSource": "string",
22      "eventNotes": "string",
23      "eventTags": "string",
24      "eventCause": "string",
25      "eventScheduleStartDate": "2020-06-03T15:59:26.863Z",
26      "eventScheduleEndDate": "2020-06-03T15:59:26.863Z",
27      "eventScheduleRRule": "string"
28    }
29  ],
30  "commonFilters": {
31    "additionalProp1": {},
32    "additionalProp2": {},
33    "additionalProp3": {}
34  },
35  "domainFilters": {
36    "additionalProp1": {},
37    "additionalProp2": {},
38    "additionalProp3": {}
39  }
40}

Response fields

The following table describes all of the fields that can appear in a response. Fields are listed by the response section they belong to and in the order that they appear in the response.

Primary fields

Field

Description

entities
array

A list of location items.
entities

commonFilters
object

The list of common filters applied.

domainFilters
object

The list of additional fiters applied.
entities array
Field Description

locationId
integer

The location id.

locationName
string

The name of the location.

locationEffect
integer

TMCCode

isBidirectional
integer

True if the location is biderectional.

startDateTime
date

The location start date in UTC format.

startDateTime
date

The location start date in the location timezone.

endDateTime
date

The location end date in the location.

endDateTimeZoned
date

The location end date in the location timezone.

createdAt
date

The location creation date.

createdBy
string

Email of the user who created the location.

geometry
geojson

GeoJSON with geometry.

liveStatusAB
string

Live Traffic status for a positive direction.

liveStatusBA
string

Live Traffic status for a negative direction.

eventId
integer

Id of the event.

eventName
string

The event name.

eventType
string

The event type.

eventTimeZone


string

The timezone name.

eventSource


string

The event source URL.

eventNotes


string

The event public notes.

eventTags


string

The event tags.

eventCause


string

The cause name.

eventScheduleStartDate


string

The schedule start date. The start date of the first scheduled occurrence.

eventScheduleEndDate


string

The schedule end date. The end date of the first scheduled occurrence.

eventScheduleRRule


string

The Schedule RRULE ( RFC-5545 ).

Response codes

The following table contains HTTPS response codes signifying successful and failed requests to an API server. (Choose which response codes are used in this endpoint from the following table. Delete the ones not used, and add new ones if needed.)

Code

Meaning & possible causes

200

OK

206

Partial Content

400

Malformed request : The requested syntax is not available.

400

Bad request : Parameters out of range.

401

Unauthorized :

  • The supplied Admin Key is not valid for this request.
  • No Admin Key is supplied.

401

Unauthorized : Configuration not found.

  • The configuration does not exist in the database.
  • The user has not registered an Admin Key.

403

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

403

Forbidden : User can only register once.

429

Too Many Requests : The API key is over QPS (Queries per second).

500

Internal Server Error : There is a problem with the TomTom Road Event Reporter Enterprise API service.

Response headers

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

Header

Description

Access-Control-Allow-Origin

The Access-Control-Allow-Origin response header indicates whether the Response can be shared with the requesting code from the given origin.
Value: *

Connection

The Connection general header controls whether or not the network connection stays open after the current transaction finishes.
Value: keep-alive

Content-Encoding

The Content-Encoding entity header is used to compress the media-type.
Value: gzip

Content-Length

The Content-Length entity header indicates the size of the entity-body in bytes that are sent to the recipient.
Value: Content-Length

Content-Type

The Content-Type entity header is used to indicate the media type of the resource.
Value: application/json;charset=UTF-8

Date

The Date general header contains the date and time at which the message was originated.
Value: Date

Strict-Transport-Security

The HTTP Strict-Transport-Security response header (often abbreviated as HSTS) lets a web site tell browsers that it should only be accessed using HTTPS, instead of using HTTP.
Value: max-age=<expire-time>& includeSubDomains

Vary

The Vary HTTP response header determines how to match future request headers to decide whether a cached Response can be used rather than requesting a fresh one from the origin server.
Value: A comma-separated list of header names.

Tracking-ID

An identifier for the request. An unique identifier used by TomTom to identify and log a specific client request and trace it back for support purposes. It is only meant to be used for support and does not involve tracking of you or your users in any form. If the Tracking-ID header was specified, it is replicated in the response. Otherwise, it is generated automatically by the service.
Value: string