Sorry, you need to enable JavaScript to visit this website.

Analysis Preview

Request

Format

https://<baseURL>/origindestination/<versionNumber>/analysis/<id>?key=<apiKey>[&getParameters=<getParameters>][&getResult=<getResult>][&pruneSingular=<pruneSingular>]

Example

https://api.tomtom.com/origindestination/1/analysis/512?key=test-api-key&getParameters=true&getResult=true

Parameters

The table below describes the parameters that must be used in a request or the call will fail.

Request parameters
parameter Description Required? Type / Values Default Value

baseURL

Base URL for calling the API.

Yes

api.tomtom.com

-

id

Analysis number id.

Yes

long

-

versionNumber

Service version number. The current value is 1.

Yes

1

-

apiKey

Authorization key for access to the API.

Yes

API Key

-

getParameters

Defines if parameters of request should be included in response

No

boolean

true

getResult

Defines if result should be included in response

No

boolean

true

pruneSingular

Removes single value dimensions from result.

No

boolean

false

Response

The table below describes all of the fields that can appear in a response.

Structure of response (JSON)
Field(s) Description Type / Values

id

Analysis number id (from request).

(as in request)

creationTime

Job creation time.

Timestamp in format: YYYY-MM-DDTHH:mm:ss.SSSZ

status

Job status.

String:

  • WAITING

  • RUNNING

  • ENDED

  • FAILED

  • CANCELLED

statusDetails

Optional description of status. For example reason of FAILED status.

String

type

Type of analysis.

String / "FLOW_MATRIX"

parameters

Parameters regarding analysis. See structure here.

Object with properties:

  • time

  • regions

  • name

  • timeMode

  • timeWindow

  • separateHours

  • separateDaysOfWeek

  • pass Matrix

result

Analysis result

Result structure

name

Job name, given for user’s convenience.

String

owner

Email of apiKey’s owner with which analysis was requested.

String

startAnalysisTime

Date and time start of analysis.

Timestamp in format: YYYY-MM-DDTHH:mm:ss.SSSZ

endAnalysisTime

Date and time end of analysis.

Timestamp in format: YYYY-MM-DDTHH:mm:ss.SSSZ

currentProgress

Current value of job progress.

Integer (0-1000)

maxProgress

Maximum value of job progress.

Integer (1000)

Parameters structure

The table below describe structure of the field parameters which were used during analysis creation (copy of JSON request)

Structure of parameters
Field(s) Description Type / Values

time

Time sets used during calculations.

List of properties:

  • zoneId

  • dataRanges

  • timeRanges

  • daysOfWeek

regions

Defined regions during calculations.

Defined in GeoJSON format (RFC 7946)

Result structure

The table below describe structure of the field result.

Structure of result (JSON)
Field(s) Description Type / Values

flows

Array of flows.

Array of integers (E.g. [[[[[[[[1482,139,10,35,5,8,27,14,…​],…​]]]]]]])

dimensions

Array with explanation of each dimension.

Array of object with fields:

  • name: dimension name (E.g. Local Time Ranges)

  • values: values of this dimension (E.g. [0:"00:00-00:00", 1:"07:00-10:00", 2:"16:00-19:00"])

Result intepretation example

{
  "flows": [...],
  "dimensions": [
    {
      "name": "Default Time Window",
      "values": [
        "00:01-23:58"
      ]
    },
    {
      "name": "Local Date Ranges",
      "values": [
        "2016-01-01-2016-06-31",
        "2017-01-01-2017-06-31",
        "2018-01-01-2018-06-31",
      ]
    },
    {
      "name": "Local Time Ranges",
      "values": [
        "00:00-00:00",
        "07:00-10:00",
        "16:00-19:00"
      ]
    },
    {
      "name": "Time Window",
      "values": [
        "whole"
      ]
    },
    {
      "name": "Start Region",
      "values": [
        "Region 1",
        "Region 2",
        "Region 3",
        "exterior"
      ]
    },
    {
      "name": "End Region",
      "values": [
        "Region 1",
        "Region 2",
        "Region 3",
        "exterior"
      ]
    },
    {
      "name": "Via Region",
      "values": [
        "Region 1",
        "Region 2",
        "Region 3",
        "total"
      ]
    }
  ]
}

In this example dimensions array describes each dimension as follows: First dimension is whether traces are passing through midnight, the second contains date range and so on. To demonstrate we can write it in the following form:

flows[Default Time Window][Date range][Time range][Time window][Start region][End region][Via region]

For example if we want to get total flows between Region 1 and Region 3 for first date range and first time range we would use

flows[0][0][0][0][0][2][3]

Where the first index means that we select first value from Default Time Window dimension, the second index means that we select first value from Date range dimension which is "2017-01-01-2017-12-31" as we can see in a values field in dimension description object. Third index 0 means that we select first time range "00:00-00:00". Fourth index 0 defines time mode as a whole. Last three indices define regions. 0 and 2 means that we select the first region Region 1 as a origin and the third region Region 3 as a destination. Via region dimension allows us to get flows that passed through particular region but in our case we selected fourth value which corresponds to total value.

Here is another exmaple:

flows[0][0][0][0][2][2][3]

In this case we selected Region 3 as both an origin and a destination which will return internal flows of that region.

To get flows that started or ended outside of defined regions you need to select an index that corresponds to the exterior value - note this will work only for default option of passMatrix. When passMatrix is selected as true, no additional region exterior is generated and all trips are trimmed to defined regions.

Retrieving huge results

When analysis contains big amount of regions, date and time ranges.
The best approach we recommend is to get partial results by specifying which date and time range you need:
For above example, you can easily get results only for:
* Local Date Range : 2016-01-01-2016-06-31* Local Time Range : 07:00-10:00

to achieve this, add the following parameters to your request:

&Local Date Ranges=2016-01-01-2016-06-31&Local Time Ranges=07:00-10:00

(white characters should be escaped with standard %20)

final example of your request should look like following:

https://api.tomtom.com/origindestination/1/analysis/512?key=test-api-key&getParameters=false&getResult=true&Local Date Ranges=2016-01-01-2016-06-31&Local Time Ranges=07:00-10:00

We will consider providing some hypermedia links for easier usage in the future.

Final Example

Here is example, showing correct final response
{
  "id": 0,
  "creationTime": "2018-09-19T18:00:41.740Z",
  "status": "ENDED",
  "statusDetails": string,
  "type": "FLOW_MATRIX",
  "parameters": {
    "time": {...},
    "regions": [...],
    "name": "string",
    "timeMode": "WHOLE_INSIDE",
    "timeWindow": null,
    "separateHours": false,
    "separateDaysOfWeek": false,
    "passMatrix": false
  },
  "result": {
    "flows": [...]
    "dimensions": [...]
  },
  "name": "string",
  "owner": "user@example.com",
  "startAnalysisTime": "2018-09-21T12:11:28.645Z",
  "endAnalysisTime": "2018-09-21T12:21:17.164Z",
  "currentProgress": 1000,
  "maxProgress": 1000
}

Errors

If there is an error in the supplied parameters or any other internal problem an error response is generated in the requested format.

HTTP Response Codes
Code Reason

401

Unauthorized

403

Forbidden

404

Not Found

You are here