Guides
Guides
  1. Traffic Analytics
  2. Using Traffic Analytics
  3. Traffic Analytics REST API

Traffic Analytics API service requests

Currently, there are two service APIs that a client app can use: one for submitting a request, and another to get the status of a submitted request. Typically, a client app makes a call to submit a request, and then polls the status API once a minute until it completes, and downloads the resulting dataset.

How to submit a request to the API

Using two services, a client app:

  • Submits a request.
  • Checks the request status.

Typically, the client app submits a request, then polls the status API once per minute until processing completes. After the request is complete, the app downloads the resulting dataset.

The API takes query JSON as input:

URL: https://trafficanalytics.api.here.com/dailyAnalytics/requests
HTTP Method: POST

When you also use whenSubmitted, actualSize, and requestId in your query, this returns all the information related to the request.

Request headers for services

The following table shows the request headers.

Header nameHeader valueDescription
Content-Typeapplication/jsonSince acceptable request body format is JSON.
Authorization<access token>Replace <access token> with access token received as described in previous section. NOTE that you must prepend 'Bearer ' (including the space) before the token in this header. Many people miss this.

Request body

The following is the request body description.

  • queryFilter (required): describes filter conditions for the query, each of which must be satisfied ('AND' conditions).
  • adminId (required): Number representing the adminId of the requested region in the HERE Map. Refer to the steps given in section 5 on how to get an adminId. This attribute is required in case location attribute is omitted.
  • adminLevel (required): Admin level associated with the admin ID (e.g. 1, 2, 3, 4). Please refer to the steps given in the section titled Admin ID and admin level on how to get an adminId. This attribute is required in case the location attribute is omitted.
  • location(optional)
    • geometry : string in WKT (Well-Known Text) format describing the polygon to use for geospatial filtering. The polygon must be closed, and it can contain a maximum of 10,000 points. This attribute is mandatory when admin ID and admin level attributes are omitted. Example: "geometry": "POLYGON((174.77 -40.67,176.23 -41.3,174.9 -41.87,174.27 -40.83,174.77 -40.67))"
  • startDate (required): “yyyy-MM-ddTHH:mm:ssZ” (ISO 8601) (local time for sample–only year, month and day are used in the backend)
  • endDate (required): “yyyy-MM-ddTHH:mm:ssZ” (ISO 8601) (local time for sample–only year, month and day are used in the backend)
  • requestType (required): describe how the query is to be processed based on the requestType. If used, only one of the following can be specified:
    • Probe Data + Per Probe = PROBE
    • Probe Data + Per Vehicle = AGGREGATED_PROBE
    • Probe Data + Per Probe + Path Data = PROBE_PATH
    • Probe Data + Per Vehicle + Path Data = AGGREGATED_PROBE_PATH
    • Path Data = PATH Important: A 'PATH-only' is mandatory if the user is using the new features added on 2024, HARMONIC MEANS, VDT or PROBE COUNT.
  • vehicleType (required): “TRUCK” | “CAR” | “ALL”
  • timeIntervals (optional, defaults to whole day): array of “hhmm-hhmm” items… (different time slots defined in user preferences on the front end, like "Morning Rush" means “0530-0930”)
  • daysOfWeek (optional, defaults to all days): days requested with the format like {“U”=false, “M”=true, “T”=true, “W”=true, “R”=true, “F”=true, “S”=false} for weekdays, using following values: U=Sunday, M=Monday, T=Tuesday, W=Wednesday, R=Thursday, F=Friday, S=Saturday
  • smoothedSpeed(optional, defaults to false): causes Traffic Analytics to generate smoothed Traffic Analytics. Speeds are averaged over a short time window similar to the way used by HERE Real-Time Traffic. Use this parameter to generate speeds that can be more directly compared to Real Time Traffic. But don't use this option without consulting with HERE technical staff. It causes much higher system load risks and system stability issues for all customers. The system overrides values for fallowing parameters as given below if smoothedSpeed=true.
    • "vehicleType":"ALL"
    • "requestType":"AGGREGATED_PROBE"
    • "timeIntervals”:["0000-2359"] It also changes the name of the MEAN field to SMOOTHED, since it represents a different value.
    • locationFilter (optional): describes how the query is to be filtered based on location. If used, only one of the following can be specified:
    • tmcs (optional): array of TMC codes
    • links (optional): array of link PVIDs with direction (example "links":["737021627T"])
    • funcClass (optional, defaults to all functional classes): functional classes from 1 through 5 requested with format like {“1”=true, “2”=true, “3”=false, “4”=false, “5”=false} for just functional classes 1 and 2.
    • linears (optional): array of TMC Linear IDs (numerics). Use only in case linear IDs are already known, as the product offers no way to derive them.
  • outputFormat
  • epochType (optional, defaults to 5 minutes): how to roll up 5-minute epoch data into bigger epochs (such as 10, 15, 60).
  • percentiles (optional, defaults to none): array of percentiles to include in output, like [25, 50, 75] for every 25th percentile for example–could also just be a particular target percentile of interest, so in that case something like [85] for just the 85th percentile value.
  • tmcBased (optional, defaults to false): boolean - whether the output is at the link level or rolled up to TMCs.
  • minMax (optional, defaults to false): boolean - whether the output contains min/max speed values.
  • mean (optional, defaults to false): boolean - whether output contains average speed.
  • confidence (optional, defaults to false): boolean-whether output contains confidence.
  • freeFlow (optional, defaults to false): boolean–whether output contains free flow speed value.
  • stdDev (optional, defaults to false): Boolean–whether the output contains standard deviation.
  • length (optional, defaults to false): Boolean–whether the output contains length.
  • sampleCount (optional, defaults to false): Boolean–whether output contains observation count.
  • harmonicMean (optional, defaults to false) Boolean–whether the output contains harmonic mean. This new feature requires a requestType = PATH.
  • vdt (optional, defaults to false) Boolean–whether the output contains vehicle distance traveled (vdt). This new feature requires a requestType = PATH.
  • probeCount (optional, defaults to false) whether the output contains probe count. This new feature requires a requestType = PATH.
  • If smoothedSpeed=true in queryFilter, then the system overrides the following output Format parameters values as given below.
    • "epochType" :5
    • "gapFilling": true
  • estimatedSize (required): This attribute is of type Long and represents the number of bytes. It's currently unused. Set the value to 0.
  • userEmail (required): email of the user authorized to use the Traffic Analytics website, which is used to login to that website.
  • userId (required): ID of the user who sends the request. HERE assigns the userId shares it separately with the client. Note that his isn't the consumer ID or the consumer secret credentials used to retrieve the token. Rather, it's an integer associated with the email address of the authorized website user associated with those credentials. The userId and the API credentials are provided to you.

Examples

The following are examples of service requests.

Query request JSON for specific list of Functional Classes

{
   "queryFilter": {
      "adminId": 23061376,
      "adminLevel": 4,
      "isoCountryCode": "NZL",
      "startDate": "2014-01-01T00:00:00Z",
      "endDate": "2014-01-31T00:00:00Z",
      "requestType": "PROBE",
      "vehicleType": "ALL",
      "timeIntervals": ["0100-0500", "0700-0930", "1600-2359"],
      "daysOfWeek": {"U":true, "M":true, "T":true, "W":true, "R": true, "F":true, "S":true},
      "locationFilter": {"funcClass":{"1":true,"2":true,"3":true,"4":true,"5":true}}
   },
   "outputFormat": {
      "tmcBased": true,
      "epochType": 60,
      "minMax": true,
      "mean": true,
      "stdDev": true,
      "confidence": true,
      "freeFlow": true,
      "length_": true,
      "speedLimit": true,
      "sampleCount": true,
      "gapFilling": true,
      "percentiles": [10, 20, 30, 40, 50, 60, 70, 80, 90]
   },
   "estimatedSize": 1000000,
   "userEmail": "<<Enter Email Id>>",
   "userId": <<Enter your user id without quotes>>
}

Query request JSON for specific list of TMCs

{
   "queryFilter": {
      "adminId": 23061376,
      "adminLevel": 4,
      "isoCountryCode": "NZL",
      "startDate": "2014-01-01T00:00:00Z",
      "endDate": "2014-01-31T00:00:00Z",
      "requestType": "PROBE",
      "vehicleType": "ALL",
      "timeIntervals": ["0000-2359"],
      "daysOfWeek": {"U":true, "M":false, "T":false, "W":false, "R":false, "F":false, "S":true},
      "locationFilter": {"tmcs": ["941N03850", "941P03850"]}
   },
   "outputFormat": {
      "tmcBased": true,
      "epochType": 60,
      "minMax": true,
      "mean": true,
      "stdDev": true,
      "confidence": true,
      "freeFlow": true,
      "length_": true,
      "speedLimit": true,
      "sampleCount": true,
      "gapFilling": true,
      "percentiles": [10, 20, 30, 40, 50, 60, 70, 80, 90]
   },
   "estimatedSize": 0,
   "userEmail": "<<Enter Email Id>>",
   "userId": <<Enter your user id without quotes>>
}

Query request JSON for PROBE data of specific list of linears on Saturday and Sunday

{
   "queryFilter": {
      "adminId": 23061376,
      "adminLevel": 4,
      "isoCountryCode": "NZL",
      "startDate": "2014-01-01T00:00:00Z",
      "endDate": "2014-01-31T00:00:00Z",
      "requestType": "PROBE",
      "vehicleType": "ALL",
      "timeIntervals": ["0000-2359"],
      "daysOfWeek": {"U":true, "M":false, "T":false, "W":false, "R":false, "F":false, "S":true},
      "locationFilter": {"linears": ["941-04190", "941-00441", "941+03795"]}
   },
   "outputFormat": {
      "tmcBased": true,
      "epochType": 60,
      "minMax": true,
      "mean": true,
      "stdDev": true,
      "confidence": true,
      "freeFlow": true,
      "length_": true,
      "speedLimit": true,
      "sampleCount": true,
      "gapFilling": true,
      "percentiles": [5,10,25,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95]
   },
   "estimatedSize": 0,
   "userEmail": "<<Enter Email Id>>",
   "userId": <<Enter your user id without quotes>>
}

Query request JSON for all data within that admin level (such as the locationFilter omitted)

{
   "queryFilter": {
      "adminId": 23061376,
      "adminLevel": 4,
      "isoCountryCode": "NZL",
      "startDate": "2014-01-01T00:00:00Z",
      "endDate": "2014-01-31T00:00:00Z",
      "requestType": "PROBE",
      "vehicleType": "ALL",

      "timeIntervals": ["0000-2359"],
      "daysOfWeek": {"U":true, "M":true, "T":true, "W":true, "R":true, "F":true, "S":true}
   },
   "outputFormat": {
      "tmcBased": true,
      "epochType": 60,
      "minMax": true,
      "mean": true,
      "stdDev": true,
      "confidence": true,
      "freeFlow": true,
      "length_": true,
      "speedLimit": true,
      "sampleCount": true,
      "gapFilling": true,
      "percentiles": [5,10,25,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95]
   },
   "estimatedSize": 0,
   "userEmail": "<<Enter Email Id>>",
   "userId": <<Enter your user id without quotes>>
}

Query request JSON for all data within set of coordinate (polygon) (such as the locationFilter, admin id, admin level needs to be omitted)

{
   "queryFilter": {
       "location": {
         "geometry": "POLYGON((174.77 -40.67,176.23 -41.3,174.9 -41.87,174.27 -40.83,174.77 -40.67))"
      },
      "isoCountryCode": "NZL",
      "startDate": "2015-08-15",
      "endDate": "2015-08-15",
      "requestType": "PROBE",
      "vehicleType": "ALL"
   },
   "outputFormat": {
      "percentiles": [],
      "tmcBased": true,
      "epochType": 60,
      "minMax": false,
      "mean": true,
      "stdDev": false,
      "sampleCount": false,
      "freeFlow": false,
      "length_": false,
      "confidence": false,
      "gapFilling": false
   },
   "distributed": false,
   "estimatedSize": 0,
   "userId": <<Enter your user id without quotes>>,
   "userEmail": "<<Enter Email Id>>"
}

Query request JSON for the new features added on 2024 release (Traffic Analytics 2024), harmonicMean, probeCount and vdt

{
    "estimatedSize": 5117627,
    "queryFilter":
    {
        "adminId": 23869478,
        "adminLevel": 1,
        "startDate": "2023-12-01",
        "daysOfWeek":
        {
            "U": true,
            "M": true,
            "T": true,
            "W": true,
            "R": true,
            "F": true,
            "S": true
        },
        "endDate": "2023-12-01",
        "isoCountryCode": "PHL",
        "locationFilter":
        {
            "funcClass":
            {
                "1": true,
                "2": true,
                "3": true,
                "4": true,
                "5": true
            },
            "tmcs":
            []
        },
        "mapVersion": "2023Q4",
        "requestType": "PATH",
        "vehicleType": "ALL",
        "timeIntervals":
        [
            "0000-2359"
        ],
        "smoothedSpeed": false
    },
    "outputFormat":
    {
        "mean": true,
        "harmonicMean": true,
        "probeCount": true,
        "confidence": true,
        "epochType": 5,
        "freeFlow": true,
        "gapFilling": false,
        "length_": true,
        "minMax": true,
        "percentiles":
        [
            50,
            55
        ],
        "sampleCount": true,
        "stdDev": true,
        "tmcBased": true,
        "speedLimit": true,
        "vdt": true
    },
    "userEmail": "...",
    "userId": xxxx  
}

Response

Upon successful invocation of the REST API, the client receives an HTTP response code as 202 and JSON in the response body containing the requestId. The program can use this request ID to get the status of its request. Possible values for status are:

  • Pending
  • In Progress
  • Completed Successfully
  • Completed With Error

Example of successful response

The following is an example of a successful response.

{
"queryFilter": {
      "adminId": 23061376,
      "adminLevel": 4,
      "isoCountryCode": "NZL",
      "mapVersion": "2018Q3",
      "startDate": "2014-01-01T00:00:00Z",
      "endDate": "2014-01-31T00:00:00Z",
      "requestType": "PROBE",
      "timeIntervals": ["0000-2359"],
      "daysOfWeek": {"U":true, "M":true, "T":true, "W":true, "R":true, "F":true, "S":true},
   },
   "outputFormat": {
      "tmcBased": true,
      "epochType": 60,
      "minMax": true,
      "mean": true,
      "stdDev": true,
      "confidence": true,
      "freeFlow": true,
      "length_": true,
      "speedLimit": true,
      "sampleCount": true,
      "gapFilling": true,
      "percentiles": [5,10,25,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95]
   },
   "requestId": 14049,
   "status": "Pending"
   "estimatedSize": 1000000,
   "userEmail": "[email protected]",
   "userId": 1234,
   "whenSubmitted": "2017-10-11T10:39Z"
}

Get request details

The following retrieves the status and request details about a request submitted by a specific user.

URL: https://trafficanalytics.api.here.com/dailyAnalytics/users/<userId>/requests/<requestId>
HTTP Method: GET
URL Example: https://trafficanalytics.api.here.com/dailyAnalytics/users/1234/requests/1093

Request headers for request details

The following table shows the request headers.

Header nameHeader valueDescription
Content-Typeapplication/jsonSince acceptable request body format is JSON.
Authorizationaccess tokenReplace access token with access token received as described in previous section. NOTE that you must prepend 'Bearer ' (including the space) before the token in this header. Many people miss this.

HTTP Query parameters

The following are the required query parameters:

  • userId (required): id of the user
  • requestId (required): id of the request

Returns: request info for the specified request id, with the same info submitted when the request was first submitted plus some additional metadata: whenSubmitted, status, requestId, actualSize (after completion), outputLocation (after completion)

Note

This call may be executed at a maximum of one per minute. Any HTTP request that's made in less than 60 seconds since the last request for a given query receives an error.

Possible values for status are:

  • Pending
  • In Progress
  • Completed Successfully
  • Completed With Error
  • Rejected

When the query completes, the user receives an email from the Traffic Analytics system for the query, containing the requestId.

Example of a request details response

The following shows request details about a request submitted by a specific user.

{
estimatedSize: 1000000
- queryFilter: {
adminId: 23061376
adminLevel: 4
startDate: "2014-01-01"
- daysOfWeek: {
U: true
M: false
T: false
W: false
R: false
F: false
S: true
}
endDate: "2014-01-31"
isoCountryCode: "NZL"
locationFilter: {
funcClass: {
1: true
2: true
3: true
4: true
5: true
}
- tmcs: [2]
0:  "941N03850"
1:  "941P03850"
}
mapVersion: "2014Q3"
requestType: "ALL"
timeIntervals: [1]
0:  "0000-2359"
}
-outputFormat: {
mean: true
confidence: true
epochType: 60
freeFlow: true
gapFilling: true
length_: true
minMax: true
percentiles: [9]
0:  10
1:  20
2:  30
3:  40
4:  50
5:  60
6:  70
7:  80
8:  90
sampleCount: true
stdDev: true
tmcBased: true
speedLimit: true
}
requestId: 1093
status: "Completed Successfully"
userEmail: "[email protected]"
userId: 1234
whenSubmitted: "2015-08-11T19:10"
"outputUrl": "https://traffic-analytics-test.s3.amazonaws.com/queryOutput/1234/20171011-14818/output/HERE_DA_14818.csv.gz?response-content-disposition=attachment%3B%20filename%3DHERE_DA_14818.csv.gz&AWSAccessKeyId=AKIAIGVCWDWC7WMDFKSA&Expires=1507799605&Signature=kzV4gB0lLs9%2BO1dnBKM%2Bdqzr1EA%3D",
"metadataUrl": "https://traffic-analytics-test.s3.amazonaws.com/queryOutput/1234/20171011-14818/output/HERE_DA_14818_metadata.txt?response-content-disposition=attachment%3B%20filename%3DHERE_DA_14818_metadata.txt&AWSAccessKeyId=AKIAIGVCWDWC7WMDFKSA&Expires=1507799605&Signature=scGzph3y3KZHGq75%2BmFMVe%2B7DOc%3D",
      "urlExpirationDate": "2011-10-12T09:13Z"
}

Note

If the output size is greater than 10GB the user gets multiple links in outputUrl to download each output file individually.

Example of JSON response for more than 10GB output request.

{
    "queryFilter": {
        "adminId": 20128886,
        "adminLevel": 1,
        "startDate": "2018-12-01",
        "daysOfWeek": {
            "U": true,
            "M": true,
            "T": true,
            "W": true,
            "R": true,
            "F": true,
            "S": true
        },
        "endDate": "2018-12-31",
        "isoCountryCode": "BEL",
        "locationFilter": {
            "funcClass": {
                "1": true,
                "2": true,
                "3": true,
                "4": true,
                "5": true
            },
            "tmcs": []
        },
        "mapVersion": "2018Q3",
        "requestType": "AGGREGATED_PROBE_PATH",
        "vehicleType": "ALL",
        "timeIntervals": [
            "0000-2359"
        ],
        "smoothedSpeed": false
    },
    "name": "Daily Query Test for 18-01-2024",
    "outputFormat": {
        "mean": true,
        "confidence": true,
        "epochType": 15,
        "freeFlow": true,
        "gapFilling": false,
        "length_": true,
        "minMax": true,
        "percentiles": [
            5,
            10,
            15,
            20,
            25,
            30,
            35,
            40,
            45,
            50,
            55,
            60,
            65,
            70,
            75,
            80,
            85,
            90,
            95
        ],
        "sampleCount": true,
        "stdDev": true,
        "tmcBased": false,
        "speedLimit": true
    },
    "requestId": 30024,
    "status": "Completed Successfully",
    "userEmail": "[email protected]",
    "userId": 1234,
    "whenSubmitted": "2024-01-19T18:24Z",
    "outputUrl": "1) https://traffic-analytics-prod.s3.amazonaws.com/2018Q3/queryOutput/1234/20240119-30024/output/HERE_DA_30024/FINAL/HERE_DA_00000.csv.gz?response-content-disposition=attachment%3B%20filename%3DHERE_DA_00000.csv.gz&AWSAccessKeyId=AKIAJROJNP7EFXQOVBSA&Expires 2) https://traffic-analytics-prod.s3.amazonaws.com/2018Q3/queryOutput/1234/20240119-30024/output/HERE_DA_30024/FINAL/HERE_DA_00001.csv.gz?response-content-disposition=attachment%3B%20filename%3DHERE_DA_00001.csv.gz&AWSAccessKeyId=AKIAJROJNP7EFXQOVBSA&Expires ",
    "metadataUrl": "https://traffic-analytics-prod.s3.amazonaws.com/2018Q3/queryOutput/1234/20240119-30024/output/HERE_DA_30024_metadata.txt?response-content-disposition=attachment%3B%20filename%3DHERE_DA_30024_metadata.txt&AWSAccessKeyId=AKIAJROJNP7EFXQOVBSA&Expires=1550523241&Signature=tie9DlAAzTdRYhEb20rWphMbbkg%3D",
    "urlExpirationDate": "2024-02-18T20:54Z"
}