Traffic Study by Movement
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.
{
"interval": 60,
//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,
"studyCategory": 1,
"status": 4,
"paging": {
"pageSize": 100,
"pageNumber": 1
}
}
Request Body Parameters
- 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. Read more - municipalityIds:
Array<Guid>- Filter by municipality IDs. Read more - 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. This option sets the aggregation time interval.
If the input interval is smaller than the original aggregation interval or if no interval value is provided, the data will be returned with the original study interval. - Options:
- 5 : 5 minutes
- 15 : 15 minutes
- 60 : 60 minutes
- -1 : If -1 is provided, all time data will be aggregated and displayed as a single unit. Alternatively, the string
"AggregateAll"can be used.
- paging:
Object- For chunked data retrieval:- pageSize:
integer- Number of records per page (1 to 100). - pageNumber:
integer- Page number to retrieve.
- pageSize:
4. Response
The API response is structured to either provide the requested traffic study data or to 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 that identifies the specific error encountered. Here is a sample of an 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 with ErrorsResponse Codes:
- responseCode =
2005: IIP 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 is organized into the following sections:3
- errorMessages: Empty if no errors were encountered.
- results: Contains an array of traffic study data, organized into sub-categories.
- study: Summary information about the study. Please refer to Studies Overview for more details.
- 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
- SummaryData
- NT : North Approach Through
- NL : North Approach Left Turn
- ER : East Approach Right Turn
- ET : East Approach Through
- EL : East Approach Left Turn
- SR : South Approach Right Turn
- ST : South Approach Through
- SL : South Approach Left Turn
- WR : West Approach Right Turn
- WT : Wet Approach Through
- WL : West Approach Left Turn
- NR : North Approach Right Turn
- NRC : North Approach Right Pedestrian Crossing
- NLC : North Approach Left Pedestrian Crossing
- EUC : East Approach Up Pedestrian Crossing
- EDC : East Approach Down Pedestrian Crossing
- SRC : South Approach Right Pedestrian Crossing
- SLC : South Approach Left Pedestrian Crossing
- WUC : West Approach Up Pedestrian Crossing
- WDC : West Approach Down Pedestrian Crossing
- NU : North Approach U-Turn
- EU : East Approach U-Turn
- SU : South Approach U-Turn
- WU : West Approach U-Turn
The other parameters are the same as in the request body. Sample Request
{
"fromDate": "2020-05-02",
"toDate": "2024-05-02",
"status:": 4
"paging": {
"pageSize": 2,
"pageNumber": 1
}
}
Sample Successful Response:
{
"pagingInfo": {
"pagingInfo": {
"itemsPerPage": 2,
"totalPages": 4,
"totalItems": 8,
"currentPage": 1
},
},
"id": "00000000-0000-0000-0000-000000000000",
"errorMessages": [],
"responseCode": 200,
"results": [
//Array of traffic studies.The result section, would be very similar in Volume, TMC, and Speed studies ]
}
5. Example Result
The results section's each traffic study.
{
"pagingInfo": {
"pageSize": 2,
"pageCount": 11,
"currentPageNumber": 1
},
"id": "00000000-0000-0000-0000-000000000000",
"errorMessages": [],
"responseCode": 200,
"results": [
{
"binMapping": null,
"study": {
"id": "755a407d-3c4b-f06e-a7aa-196c7c554387",
"studyNo": 4232,
"studyType": 2,
"workOrderNo": "4176",
"locationId": "755a440e-b158-6c3f-ff77-120a46614387",
"locationDescription": "Teston Road @ Mosque Gate",
"geoId": "Y0859",
"locationType": 1,
"sectionType": 2,
"aggregationInterval": 15,
"status": 4
},
"summaryData": [
{
"startDT": "2016-04-05T07:00:00Z",
"endDT": "2016-04-05T08:00:00Z",
"unKnown": 0,
"nt": 0,
"nl": 0,
"er": 0,
"et": 1399,
"el": 9,
"sr": 47,
"st": 0,
"sl": 60,
"wr": 28,
"wt": 970,
"wl": 0,
"nr": 0,
"nrc": 0,
"nlc": 0,
"euc": 0,
"edc": 0,
"src": 0,
"slc": 3,
"wuc": 0,
"wdc": 0,
"nu": 0,
"eu": 0,
"su": 0,
"wu": 0
},
{
"startDT": "2016-04-05T08:00:00Z",
"endDT": "2016-04-05T09:00:00Z",
"unKnown": 0,
"nt": 0,
"nl": 0,
"er": 0,
"et": 1610,
"el": 11,
"sr": 32,
"st": 0,
"sl": 55,
"wr": 28,
"wt": 1039,
"wl": 0,
"nr": 0,
"nrc": 0,
"nlc": 0,
"euc": 0,
"edc": 0,
"src": 0,
"slc": 4,
"wuc": 0,
"wdc": 0,
"nu": 0,
"eu": 0,
"su": 0,
"wu": 0
}
]
},
{
"binMapping": null,
"study": {
"id": "755a42fb-1193-4bc3-ab2e-d0dc0e184387",
"studyNo": 4798,
"studyType": 2,
"workOrderNo": "4723",
"locationId": "755a440e-b158-6c3f-ff77-120a46614387",
"locationDescription": "Teston Road @ Mosque Gate",
"geoId": "Y0859",
"locationType": 1,
"sectionType": 2,
"aggregationInterval": 15,
"status": 4
},
"summaryData": [
{
"startDT": "2017-12-23T07:00:00Z",
"endDT": "2017-12-23T08:00:00Z",
"unKnown": 0,
"nt": 0,
"nl": 0,
"er": 0,
"et": 190,
"el": 1,
"sr": 10,
"st": 0,
"sl": 21,
"wr": 8,
"wt": 134,
"wl": 0,
"nr": 0,
"nrc": 0,
"nlc": 0,
"euc": 0,
"edc": 0,
"src": 0,
"slc": 1,
"wuc": 0,
"wdc": 0,
"nu": 0,
"eu": 0,
"su": 0,
"wu": 0
},
{
"startDT": "2017-12-23T08:00:00Z",
"endDT": "2017-12-23T09:00:00Z",
"unKnown": 0,
"nt": 0,
"nl": 0,
"er": 0,
"et": 320,
"el": 0,
"sr": 22,
"st": 0,
"sl": 29,
"wr": 21,
"wt": 214,
"wl": 0,
"nr": 0,
"nrc": 0,
"nlc": 0,
"euc": 0,
"edc": 0,
"src": 0,
"slc": 0,
"wuc": 0,
"wdc": 0,
"nu": 0,
"eu": 0,
"su": 0,
"wu": 0
}
]
}
]
}