Area Analysis

The Area Analysis API calculates statistics for an area. This API is asynchronous. There are two endpoints consuming two types of requests. The first one is only for ordering jobs with POST requests. In its response the user receives a jobId, which should be used in the second endpoint with GET request to the check job's status. When job is successfully finished user in response will receive links to download results.

There are some important notes about using this API:

• The latitude and longitude coordinates are in EPSG4326 / WGS84 format for both input and output. Other coordinate systems are not supported.
• All averages are calculated arithmetically unless otherwise stated (example JSON field: harmonicAverageSpeed is calculated harmonically).
• The current API version is 1.
• The maximum length of date range is 366 days.
• The maximum number of time sets is 24.
• Network size, calculated as size of bounding box of defined geometry, cannot be greater than 20 000 km².
• As the service is asynchronous it can take a while before results are available, depending on how busy the service is. Do not repost your request multiple times if you do not get feedback within seconds, we will ensure that the results are delivered.
• At the same time you can have only 5 jobs in MAPMATCHED and READING_GEOBASE statuses per each developer key. When you reach this limit you can still create new jobs as they will be queued until at least one of currently running jobs is done.

Request

Format

https://<baseURL>/traffic/trafficstats/areaanalysis/<versionNumber>?key=<apiKey>

Required POST Headers

Content-Type: application/json

Parameters

The table below describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters may be used.

JSON request parameters

Below JSON parameters refer to POST request.

Structure of network

Structure of dateRange

Structure of timeSets

JSON example request

{
  "jobName":"Test job",
  "distanceUnit":"KILOMETERS",
  "network": {
    "name": "test",
    "geometry" : {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [19.44305, 51.75612],
            [19.44992, 51.75612],
            [19.44992, 51.75947],
            [19.44305, 51.75947],
            [19.44305, 51.75612]
          ]
        ],
        [
          [
            [19.45011, 51.75789],
            [19.45687, 51.75789],
            [19.45687, 51.75946],
            [19.45011, 51.75946],
            [19.45011, 51.75789]
          ]
        ]
      ]
    },
    "timeZoneId": "Europe/Warsaw",
    "frcs": [
      "0",
      "1",
      "2",
      "3",
      "4",
      "5",
      "6",
      "7",
      "8"
    ],
    "probeSource":"ALL"
 },
  "dateRange": {
    "name":"Last working week of April",
    "from":"2015-04-24",
    "to":"2015-04-30",
    "exclusions":[
      "2015-04-25",
      "2015-04-26"
    ]
  },
  "timeSets":[
    {
      "name":"Monday morning hour",
      "timeGroups":[
        {
          "days":[
            "MON"
          ],
          "times":[
            "7:00-8:00"
          ]
        }
      ]
    }
  ]
}

Response

In response to the request a jobId is provided, which is required for further communication about the query. A JSON response content example:

{"jobId":"677","responseStatus":"OK","messages":["Job created. Processing started."]}

Check job status

When a job has been initiated via the API request it is possible to check the status.

JSON request

https://<baseURL>/traffic/trafficstats/status/<versionNumber>/<job_id>?key=<apiKey>

Parameters

The table below describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters may be used.

JSON response

{"jobId":"<job_id>","jobState":"<job_status>","responseStatus":"OK"}

Job status flow

During the process there are different stages applicable. Via the get state request you can see what the state of your job is. Below you find the different stages of the process.

Response and Results

Final DONE response

{"jobId":"<job_id>","jobState":"DONE","responseStatus":"OK","urls":["<url_for_json_result_file>","<url_for_geojson_result_file>","<url_for_shape_result_file>"]}

Results

Output of Area Analysis is available in JSON, GeoJSON and SHAPE format. JSON and GeoJSON results are provided in a gzip compressed format. SHAPE files are packed into zip archives. If you want to get an example of these files please click on the applicable names.

JSON result description

Structure of timeSets

Structure of network

Structure of segmentResults

Structure of segmentTimeResults