Traffic Planning

This API provides details on how traffic is flowing, by lane, on a monitored road.

There are three ways to retrieve near real-time data:
  • By AssetUid
  • By Locations
  • By LocationUid
There are three ways to retrieve historical data:
  • By AssetUid
  • By Locations
  • By LocationUid

Retrieve Near Real-Time Data by AssetUid

LocationUid is configured to identify two bi-directional traffic lanes when used for traffic planning. Direction, speed, and vehicle count are calculated for both the direction and counter direction of traffic.

Note: The node provides a maximum of one response / per second for traffic.
Note: The timestamp returned is the end of the averaging interval; for traffic data, this interval begins 15 seconds earlier. For example, if you are trying to capture traffic data on August 20th as of 11:05:00, you will need to include data from the beginning of the interval at 11:04:45.
WebSocket URL wss://<production url>/events
JSON Request Parameters {“assetUid":"<assetUID>","eventTypes":["<eventType1>”]}
Sample JSON Request {“assetUid":"CAMERA-HYP1083-CAM-L","eventTypes":["TFEVT”]}

JSON Request Parameters

Parameter Description Required? Filter Values
assetUid GE identifier for the device. Yes Value such as "CAMERA-HYP1083-CAM-L".
eventTypes Type of event. Yes Receive a list of vehicles in traffic lanes.

Retrieve Near Real-Time Data by Locations

WebSocket URL wss://<production url>/events
JSON Request Parameters {"bbox":"< lat1:long1>,<lat2:long2 >","eventTypes":[“ <eventType1>”]}
Sample JSON Request {"bbox":"32.715675:-117.161230,32.708498:-117.151681","eventTypes":[“TFEVT”]}

JSON Request Parameters

Parameter Description Required? Filter Values
bbox GPS location of the asset. Yes Value such as "32.715675:-117.161230,32.708498:-117.151681".
eventTypes Filter for traffic events. Yes Receive a list of vehicles in traffic lanes.

Retrieve Near Real-Time Data by LocationUid

WebSocket URL wss://<production url>/events
JSON Request Parameters {“locationUid":"<location-UID>","eventTypes":[“ <eventType1>”]}
Sample JSON Request {“locationUid":"LOCATION-282","eventTypes":["TFEVT"]}

JSON Request Parameters

Parameter Description Required? Filter Values
locationUid The unique identifier assigned to a given location. Yes Value such as "LOCATION-282".
eventTypes Filter for traffic events. Yes Receive a list of vehicles in traffic lanes.

Retrieve Historical Data by AssetUid

METHOD GET
URI <production url>/v2/assets/{assetUid}events?eventTypes=TFEVT&(startTime,endTime)
Sample Request URI <production url>/v2/assets/CAMERA-HYP1037-CAM-F/events?eventTypes=TFEVT&startTime=1473897230802&endTime=1473898239338

Query Parameters

Parameter Description Required? Filter Values
assetUid GE identifier for the device. Yes For example, CAMERA-HYP1037-CAM-F
events? Query for historical data Yes eventTypes
eventTypes Type of event. Yes Receive a list of vehicles in traffic lanes.
startTime Start time (timestamp) recorded in EPOCH format. Yes Numerical value, such as 1453766605577.
Note: If you use the same timestamp for startTime and endTime, a single result will be returned.
endTime End time (timestamp) recorded in EPOCH format. Yes Numerical value, such as 1453772603879.

Retrieve Historical Data by Locations

METHOD GET
URI <production url>/v2/locations/events?eventTypes=TFEVT&bbox={ lat1:long1,lat2:long2 }&locationType=TRAFFIC_LANE&(startTime,endTime)
Sample Request URL <production url>/v2/locations/events?eventTypes=TFEVT&bbox=32.715675:-117.161230,32.708498:-117.151681&locationType=TRAFFIC_LANE&startTime=1473897230802&endTime=1473898239338

Query Parameters

Parameter Description Required? Filter Values
bbox The GPS-defined area containing the asset Yes For example, 32.715675:-117.161230,32.708498:-117.151681
eventTypes Type of event. Yes Receive a list of vehicles in traffic lanes.
startTime Start time (timestamp) recorded in EPOCH format. Yes Numerical value, such as 1453766605577.
Note: If you use the same timestamp for startTime and endTime, a single result will be returned.
endTime End time (timestamp) recorded in EPOCH format. Yes Numerical value, such as 1453772603879.

Retrieve Historical Data by LocationUid

METHOD GET
URI <production url>/v2/locations/{locationUid}/events?eventTypes=TFEVT&{startTime,endTime}
Sample Request URL <production url>/v2/locations/LOCATION-20-1037-1/events?eventTypes=TFEVT&startTime=1473897230802&endTime=1473898239338

Query Parameters

Parameter Description Required? Filter Values
locationUid GE identifier for the location. Yes For example, LOCATION-20-1037-1
events? Query for historical data Yes eventTypes
eventTypes Type of event. Yes Receive a list of vehicles in traffic lanes.
startTime Start time (timestamp) recorded in EPOCH format. Yes Numerical value, such as 1453766605577.
Note: If you use the same timestamp for startTime and endTime, a single result will be returned.
endTime End time (timestamp) recorded in EPOCH format. Yes Numerical value, such as 1453772603879.

Response Parameters

Parameter Data Type Description
locationUid String A unique identifier established by a customer or external resource to identify the lane number.
assetUid String A unique identifier established by a customer or external resource for the asset recording the traffic flow.
eventTypes String Identifies the TFEVT event type.
timestamp Number Timestamp recorded in EPOCH format.
properties String Vehicle properties being tracked by the asset.
directionUnit
Direction defined by degree(s).
speedUnit
Roadway speed limit.
vehicleType
Current definition for vehicleType is
vehicle
.
Future definition will include multi-vehicle types, including
car, truck, motorcycle
, and so on.
counter_direction_vehicleType
Uses same properties definition as vehicleType; defines vehicles for counter direction of travel.
measures String Vehicle properties being tracked by the device.
direction
Positive integer value = from 0 to 360
Direction calculates the average direction of traffic.
The node will display traffic movement in opposite directions as two different values. For example, if a given street is oriented East/West, (East =90; West=270), and you run the API call for the Eastern direction of travel, direction output will display:
“direction”: 90.
When you run the API call for the Western direction of travel, direction output will display:
“direction”: 270.
See the Degree Range and Direction Value diagram below.
counter_direction
Counter-direction defined by degree(s).
See direction (above) for general description.
speed
value = X, unit = meters per second (METERS_PER_SEC)
counter_direction_speed
value = X, unit = meters per second (METERS_PER_SEC)
vehicleCount
value = count, unit = number
counter_direction_vehicleCount
value = count, unit = number
Degree Range and Direction Value

Sample Response


{
            "locationUid": "LOC-ATL-0001-T1",
            "assetUid": "CAM-ATL-0001-1",
            "eventType": "TFEVT",
            "timestamp": 1508389324461,
            "properties": {
                "speedUnit": "METERS_PER_SEC",
                "directionUnit": "DEGREE",
                "counter_direction_vehicleType": "vehicle",
                "vehicleType": "vehicle"
            },
            "measures": {
                "counter_direction": 190,
                "counter_direction_speed": 0,
                "counter_direction_vehicleCount": 0,
                "direction": 10,
                "speed": 41,
                "vehicleCount": 3
            }
}