Studies Overview
Traffic Study Data Retrieval
1. Introduction
This API allows users to retrieve data from the Traffic Study Module, facilitating detailed analysis and visualization of traffic patterns and study metrics, including volume, speed, and classification types.
2. Authentication
Obtain an authentication token by following the steps outlined in the authentication section. This token will be used in the request header for subsequent API calls.
3. Sending a Request
POST requests should be made to the Traffic Study endpoint. Ensure the token from the Authentication step is included in the request header.
- Endpoint URL: 🔗 https://integration.cloud.tes.ca/api/traffic/v1/studies
- IP Address Whitelisting: Before sending requests, ensure your IP address is whitelisted by sending a list of authorized IP addresses to 📧 help@tes.ca
Sample Request Header:
Authorization: Bearer [authentication_token]
Content-Type: application/json
Sample Request Body: The maximum allowable date range for a query is one year.
{
//Location Filters
"locationType": 2, //Intersection =1, Midblock =2
"GeoIds":[
"Y1488Y1491",
"Y1577Y1915"
],
"locationIds": [
"755a438d-94d2-b2e0-6d60-f0b1bc544387",
"755a4cd4-7242-61fb-dd73-df39d9bf4387"
],
"jurisdictionIds":[
"755a4746-c614-4ce6-8f4f-a4faa5d24387"
],
"municipalityIds":[
"755a42ed-cc19-53e8-a482-a9ddf4284387"
],
// Date Filters
"fromDate": "2020-05-02T16:26:17.600Z",
"toDate": "2024-05-02T16:26:17.600Z",
"studyIds": [
"755a4f1f-d8bd-8a67-a5fb-b506bf7b4387",
"755a4c2f-b86c-e37f-d079-5d5cad614387",
"755a40d3-8a48-8cc5-3dd5-f6db78a84387"
],
"studyType": 1, //"Volume" =1, "TMC" =2, "Speed"=4
"studyCategory": 1,
"status": 4,
//Aggregation interval. This is will set the aggregation interval in case that you need to have a different aggregation interval.
// "interval": 60, //5, 15, 60
"paging": {
"pageSize": 100,
"pageNumber": 1
}
}
Request Body Parameters
Explanation of parameter in Request Body (All applicable conditions are logical and with each other):
-
studyIds:
Array<Guid>- Filter by study IDs. -
locationIds:
Array<Guid>- Filter by location IDs. -
geoIds:
Array<string>- Filter by geographic IDs. -
jurisdictionIds:
Array<Guid>- Filter by jurisdiction IDs. -
municipalityIds:
Array<Guid>- Filter by municipality IDs. -
fromDate:
DateTime- Minimum date for the start of the first data time interval in the study in ISO 8601 format (e.g.,2020-05-02). -
toDate:
DateTime- Maximum date for the start of the first data time interval in the study in ISO 8601 format (e.g.,2024-05-02). -
studyType:
integer- Select the type of study. Options:- 1 : Volume
- 2 : TMC
- 4 : Speed
-
studyCategory:
integer- Select the category. Options:- 1 : Volume
- 2 : Speed
- 5 : Volume and Classification
- 6 : Speed and Classification
- 9 : Volume and Continuous Count
- 10 : Speed and Continuous Count
- 13 : Volume, Speed, and Continuous Count
- 14 : Speed, Classification, and Continuous Count
-
locationType
- 1 : Intersection
- 2 : Road segment
-
status:
integer- Select the status. Options:- 0 : Work order created
- 1 : Started
- 2 : Counted
- 3 : Count Completed
- 4 : Approved
- 5 : Warning
- 6 : Error
- 7 : Need Review
-
interval:
integer- Aggregation interval. Options:- 5 : 5 minutes
- 15 : 15 minutes
- 60 : 60 minutes
-
paging:
Object- For chunked data retrieval:- pageSize:
integer- Number of records per page (1 to 100). - pageNumber:
integer- Page number to retrieve.
- pageSize:
Example Request
Note: In the request object, only the paging parameter is required. All other parameters are optional and can be used to filter the data as needed.
4. Response
The API response will either provide the requested traffic study data or return an error message if an issue is encountered.
Response with Errors
When an error occurs, the response will include an errorMessages section and a responseCode identifying the specific error. Here is a sample error response:
Sample Error Response:
{
"id": "00000000-0000-0000-0000-000000000000",
"errorMessages": [
{
"id": "00000000-0000-0000-0000-000000000000",
"message": "The IP is not allowed.",
"messageCode": 2005,
"type": 1
}
],
"responseCode": 2005,
"results": null
}
Explanation of Error Response Codes
- responseCode 2005: IP is not allowed or the maximum number of pull requests per hour has been reached.
- responseCode 1010: The “from” date must be earlier than the “to” date.
- responseCode 1011: The maximum allowable number of days for querying has been reached.
Successful API Response Structure
When a request is successful, the API response includes the following sections:
- errorMessages: Empty if no errors were encountered.
- results: Contains an array of traffic study data, organized into sub-categories:
- approachType:
integer- Aggregation interval. Options:- 0 : Unknown
- 1 : North
- 2 : East
- 4 : South
- 8 : East
- 16 : Both
- SectionType
- 1 : Four-leg Intersection
- 2 : North T-Intersection (North approach leg is missing)
- 3 : East T-Intersection (East approach leg is missing)
- 4 : South T-Intersection (South approach leg is missing)
- 5 : West T-Intersection (West approach leg is missing)
- 6 : One-way Road Northbound
- 7 : One-way Road Eastbound
- 8 : One-way Road Southbound
- 9 : One-way Road Westbound
- 10 : Two-way Road in North and South direction
- 11 : Two-way Road in East and West direction
The other parameters are the same as in the request body.
Sample Request
{
"fromDate": "2020-05-02",
"toDate": "2024-05-02",
"status:": "Approved", // WorkOrderCreated = 0, Started = 1, Counted = 2, CountCompleted = 3, Approved = 4, Warning = 5, Error = 6, NeedReview = 7,
"paging": {
"pageSize": 500,
"pageNumber": 1
}
}
Sample Successful Response
{
"pagingInfo": {
"pagingInfo": {
"itemsPerPage": 500,
"totalPages": 4,
"totalItems": 1948,
"currentPage": 1
},
},
"id": "00000000-0000-0000-0000-000000000000",
"errorMessages": [],
"responseCode": 200,
"results": [
//Array of traffic studies. Below there are results for Volume, TMC, and Speed studies ]
}
5. Example Results
Sample Result Volume Study:
{
"id": "755a4ea5-da46-f6da-30a1-e5da5f4e4387",
"studyNo": 49939,
"customerId": "755a46bb-b505-46bf-28f0-08d9bf264387",
"divisionId": "00000000-0000-0000-0000-000000000000",
"jurisdictionId": "755a4746-c614-4ce6-8f4f-a4faa5d24387",
"municipalityId": "755a4587-79f7-efd3-720b-94311fe44387",
"studyType": 1,
"studyCategory": 1,
"status": 4,
"locationId": "755a45c7-5e8f-cb8b-0139-19925fb64387",
"locationDescription": "Woodbine Avenue btwn Herald Road/Green Lane East & Mount Albert Road",
"geoId": "Y2022Y2145",
"locationType": 2,
"sectionType": 10,
"aggregationInterval": 15,
"lastModifiedDT": null,
"rawDataStartDT": "2020-05-12T12:45:00",
"rawDataEndDT": "2020-05-26T09:30:00",
"workOrder": {
"no": "43819",
"note": null,
"startDT": "0001-01-01T00:00:00Z",
"endDT": "0001-01-02T00:00:00Z"
},
"speedLimit": 0,
"aadt": {
"northPercent": 48.82351990608581,
"eastPercent": 0.0,
"westPercent": 0.0,
"southPercent": 50.791807433316265,
"percentSummary": "SB:48.82% (2473) NB:50.79% (2573) ",
"aadt": 5066
},
"volumeSummary": {
"northApproachVolume": 37782,
"eastApproachVolume": 0,
"westApproachVolume": 0,
"southApproachVolume": 40910,
"totalVolume": 78692
}
},
Sample Result TMC Study:
{
"isTrafficSignalJustified": true,
"justificationSummary": "1: 100%, 2: 100%, 3: 100%, 4: 100%, 5: 100%, 6: 0%",
"aadt": {
"majorAADT": 29046,
"minorAADT": 5661,
"northApproachAADT": 28223,
"southApproachAADT": 29839,
"eastApproachAADT": 5051,
"westApproachAADT": 4038,
"aadt": 34707
},
"id": "755a4e2c-6511-75ed-5ce4-1dc05cce4387",
"studyNo": 6465,
"customerId": "755a46bb-b505-46bf-28f0-08d9bf264387",
"divisionId": "00000000-0000-0000-0000-000000000000",
"jurisdictionId": "755a4746-c614-4ce6-8f4f-a4faa5d24387",
"municipalityId": "755a46ad-c3fe-f716-efd4-08a74f9a4387",
"studyType": 2,
"studyCategory": 0,
"status": 4,
"locationId": "755a4e6d-d4a0-b6b4-10fc-840056424387",
"locationDescription": "Bathurst Street @ Milner Gate/Chabad Gate",
"geoId": "Y1532",
"locationType": 1,
"sectionType": 1,
"aggregationInterval": 15,
"lastModifiedDT": null,
"rawDataStartDT": "2020-08-11T07:00:00",
"rawDataEndDT": "2020-08-11T18:00:00",
"workOrder": {
"no": "6304",
"note": null,
"startDT": "2017-06-02T07:00:00Z",
"endDT": "2017-06-02T18:00:00Z"
},
"volumeSummary": {
"northApproachVolume": 15660,
"eastApproachVolume": 2931,
"westApproachVolume": 2433,
"southApproachVolume": 16593,
"totalVolume": 37617
}
},
Sample Result Speed Study:
{
"speedStatisticsSummary": {
"approachType": 16,
"average": 66.03,
"median": 66.73,
"speed85thPercentile": 77.66,
"speed95thPercentile": 84.29,
"extraPercentile": [],
"compliance": 0.09,
"standardDeviation": 2.55,
"postedSpeed": 50,
"maximumSpeed": 150,
"minimumSpeed": 0,
"minPace": 66,
"maxPace": 70,
"pace": "66-70",
"pacePercent": 0.19
},
"speedStatisticsSummaryDirection1": {
"approachType": 1,
"average": 63.69,
"median": 64.12,
"speed85thPercentile": 74.54,
"speed95thPercentile": 82.22,
"extraPercentile": [],
"compliance": 0.12,
"standardDeviation": 3.41,
"postedSpeed": 50,
"maximumSpeed": 150,
"minimumSpeed": 0,
"minPace": 66,
"maxPace": 70,
"pace": "66-70",
"pacePercent": 0.19
},
"speedStatisticsSummaryDirection2": {
"approachType": 4,
"average": 68.36,
"median": 68.43,
"speed85thPercentile": 79.3,
"speed95thPercentile": 87.06,
"extraPercentile": [],
"compliance": 0.06,
"standardDeviation": 3.83,
"postedSpeed": 50,
"maximumSpeed": 140,
"minimumSpeed": 0,
"minPace": 66,
"maxPace": 70,
"pace": "66-70",
"pacePercent": 0.19
},
"speedLimit": 50,
"aadt": {
"northPercent": 47.85088329392127,
"eastPercent": 0.0,
"westPercent": 0.0,
"southPercent": 52.149116706078736,
"percentSummary": "SB:47.85% (6880) NB:52.15% (7498) ",
"aadt": 14378
},
"id": "755a45e4-0753-620f-78c0-a67d3ca24387",
"studyNo": 5084,
"customerId": "755a46bb-b505-46bf-28f0-08d9bf264387",
"divisionId": "00000000-0000-0000-0000-000000000000",
"jurisdictionId": "755a4746-c614-4ce6-8f4f-a4faa5d24387",
"municipalityId": "755a46ad-c3fe-f716-efd4-08a74f9a4387",
"studyType": 4,
"studyCategory": 2,
"status": 4,
"locationId": "755a4bce-c63f-2af4-beaf-84d821884387",
"locationDescription": "Location Description Redacted",
"geoId": "geoID redacted",
"locationType": 2,
"sectionType": 10,
"aggregationInterval": 15,
"lastModifiedDT": null,
"rawDataStartDT": "2020-08-26T00:00:00",
"rawDataEndDT": "2020-08-27T00:00:00",
"workOrder": {
"no": "3795",
"note": "for SR# 245018\r\n\r\nBefore PMs",
"startDT": "0001-01-01T00:00:00Z",
"endDT": "0001-01-02T00:00:00Z"
},
"volumeSummary": {
"northApproachVolume": 7466,
"eastApproachVolume": 0,
"westApproachVolume": 0,
"southApproachVolume": 8136,
"totalVolume": 15602
}
},
{
"speedStatisticsSummary": {
"approachType": 16,
"average": 52.48,
"median": 52.64,
"speed85thPercentile": 59.16,
"speed95thPercentile": 63.96,
"extraPercentile": [],
"compliance": 0.37,
"standardDeviation": 1.74,
"postedSpeed": 50,
"maximumSpeed": 85,
"minimumSpeed": 1,
"minPace": 51,
"maxPace": 55,
"pace": "51-55",
"pacePercent": 0.32
},
"speedStatisticsSummaryDirection1": {
"approachType": 1,
"average": 53.15,
"median": 53.12,
"speed85thPercentile": 61.0,
"speed95thPercentile": 64.81,
"extraPercentile": [],
"compliance": 0.35,
"standardDeviation": 2.45,
"postedSpeed": 50,
"maximumSpeed": 85,
"minimumSpeed": 1,
"minPace": 51,
"maxPace": 55,
"pace": "51-55",
"pacePercent": 0.29
},
"speedStatisticsSummaryDirection2": {
"approachType": 4,
"average": 51.82,
"median": 52.21,
"speed85thPercentile": 58.14,
"speed95thPercentile": 61.93,
"extraPercentile": [],
"compliance": 0.39,
"standardDeviation": 2.48,
"postedSpeed": 50,
"maximumSpeed": 85,
"minimumSpeed": 1,
"minPace": 51,
"maxPace": 55,
"pace": "51-55",
"pacePercent": 0.35
},
"speedLimit": 50,
"aadt": {
"northPercent": 48.004397091155084,
"eastPercent": 0.0,
"westPercent": 0.0,
"southPercent": 51.995602908844916,
"percentSummary": "SB:48% (5677) NB:52% (6149) ",
"aadt": 11826
},
"id": "755a441e-a4ec-05d4-f848-47a6ca154387",
"studyNo": 4331,
"customerId": "755a46bb-b505-46bf-28f0-08d9bf264387",
"divisionId": "00000000-0000-0000-0000-000000000000",
"jurisdictionId": "755a4746-c614-4ce6-8f4f-a4faa5d24387",
"municipalityId": "755a4534-4e91-c2b6-7b8e-2c8136004387",
"studyType": 4,
"studyCategory": 2,
"status": 4,
"locationId": "755a43a7-5717-b371-b9fc-6c4e770d4387",
"locationDescription": "Prospect Street btwn Bayview Avenue/College Street & Bayview Avenue/Penrose Street/Bondi Avenue",
"geoId": "Y0671Y0967",
"locationType": 2,
"sectionType": 10,
"aggregationInterval": 15,
"lastModifiedDT": null,
"rawDataStartDT": "2020-10-14T00:00:00",
"rawDataEndDT": "2020-10-15T00:00:00",
"workOrder": {
"no": "3419",
"note": "Im requesting speed study",
"startDT": "0001-01-01T00:00:00Z",
"endDT": "0001-01-02T00:00:00Z"
},
"volumeSummary": {
"northApproachVolume": 5974,
"eastApproachVolume": 0,
"westApproachVolume": 0,
"southApproachVolume": 6470,
"totalVolume": 12444
}
},
]
}