Developer

API

The following is for Version 2.1.+

Real-Time Data

Request:

Method: HTTP GET
URL:​ <tvhost/realtime_data>
Required headers: authorization header as explained below

To get realtime data from all cameras across all connected TrafficVision systems, a client can send a GET request for https://tvhost/realtime_data​ resource. "tvhost" is the ip address or computer name of the primary (aggregator / TAN) TrafficVision unit.

Response:

Response to the GET for /realtime_data​ is a JSON object as described below. The order of elements in a JSON object is not guaranteed according to the specs (http://www.json.org/). As a result it is highly recommended that a JSON parser should be used to extract the data from the GET response instead of relying on line numbers.

Elements shown in ITALICS are required as part of other requests described later in the document.

{"responses": [{data_1}, {data_2},... , {data_N}]}

‘responses’ is an array of JSON objects, one object for each camera in the system.

Each {data_#} object has following elements relevant to realtime data:

Zones

Sample Response:

Sample response from a camera having only a single rocessing unit ("host":"127.0.0.1") and two cameras (camera ‘Camera 1’ has a congestion incident).

{
   "responses": [{
    "timestamp":1494595904,
    "camera_index":1,
    "camera_name":"Camera 1",
    "station_id":"",
    "latitude":0,
    "longitude":0,
    "incidents":[
       {

        "incident_type":4,
        "incident_priority":2,
"incident_snapshot":"tmcdata/24/incidents/2017-05-12_09-24-07_incident_congestion_zone_near-la
nes.jpg",

"incident_clip":"tmcdata/24/incidents/2017-05-12_09-24-07_incident_congestion_zone_near-lanes.
mp4",
        "timestamp":1494595447,
        "incident_zone":"near-lanes"
     }
   ],
   "inactive":0,
   "inactive_reason":"",
   "calib_data":{
      "ptz_mode":"PTZ_DPA"
   },
   "realtime_data":{
      "lane_mean_speed_data":{
         "lanes_near":2,
         "lanes_far":2,
         "duration_sec":60,
         "timestamp":1494595860,
         "mean_speeds":[
            63.8125,
            72.2142868,
            51.2105255,
            47.7142868
        ]
     },
     "lane_count_data":{
        "lanes_near":2,
        "lanes_far":2,
        "duration_sec":60,
        "timestamp":1494595860,
        "lane_counts_total":[
           16,
           14,
           19,
           7
      ],
      "lane_vph":[
         960,
         840,
         1140,
         420
      ],
      "lane_occupancy":[
         11,
         8,
         16,
         6
      ],
      "lane_density":[
         15,
         11,
         22,
         8
      ]
     },
     "lane_ids":[
        "NS-1",
        "NS-2",
        "FS-1",
        "FS-2"
     ]
  },
  "response_id":0,
  "host":"127.0.0.1",
  "sid":"60e10a5d-1adb-11e7-ae5b-90b11c541a07-24"
},
  {
  "timestamp":1494595904,
  "camera_index":2,
  "camera_name":"Camera 2",
  "station_id":"",
  "latitude":0,
  "longitude":0,
  "incidents":[

  ],
  "inactive":0,
  "inactive_reason":"",
  "calib_data":{
  "ptz_mode":"PTZ_AUTOLEARN"
  },
  "realtime_data":{
     "lane_mean_speed_data":{
        "lanes_near":0,
        "lanes_far":0,
        "duration_sec":60,
        "timestamp":1494595860,
        "mean_speeds":[

        ]
     },
     "lane_count_data":{
        "lanes_near":0,
        "lanes_far":0,
        "duration_sec":60,
        "timestamp":1494595860,
        "lane_counts_total":[

        ],
        "lane_vph":[

        ],

        "lane_occupancy":[

        ],
       "lane_density":[

       ]
     },
     "lane_ids":[

     ]
  },
  "response_id":0,
  "host":"127.0.0.1",
  "sid":"60e10a5d-1adb-11e7-ae5b-90b11c541a07-2"
 }]
}

Clear/Reset incident

Request:

Method: HTTP POST
URL: tvhost/proxy/hostjson_post
(host is obtained from the host field in the object corresponding to the alert)
Required headers:​ authorization header similar to that of /realtime_data
POST content: JSON formatted object similar to the example below:

{
	"request": "cr_reset_incident",
	"request_id": 123,
	"camera_indices": [1],
	"incident_data": {
		"incident_type": 4
	}
}

The values for camera_indices (single-element array) andincident_data (json-object) can be obtained from the camera_index (integer) and incidents (json-array of objects) fields of the corresponding object in the /realtime_data​ response.
request_id is a random integer which can be checked later with the response_id​ in the response to determine if the request was processed successfully.

Response:

If the request was processed correctly, the response_id​ will match the request_id​. It might take between 5-10 seconds for cleared state of the incident to show up in the polled realtime data.

{
	"responses":[
		   {
				   "response_id":123,
				   "camera_index":1,
				   "sync_flags": {
						  "sync_settings": 2,
						  "sync_calib":1,
						  "sync_camera_info":1395842106,
						  "sync_source":1395842106
				   }
		   }
	],
	"response_id":123,
	"sync_indicator":1395842105
}

Authorization Headers

Clients need to include the ‘Authorization’ header (as described below) in each request for the request to be successful. The Authorization header should be constructed as follows:

For example, if the user agent uses ‘Aladdin’ as the username and ‘open sesame’ as the password then the header is formed as follows:

Since the authorization header is passed as plain-text (base64 encoded), it is strongly recommended that HTTPS (SSL) should be used for realtime_data request. Note that all TrafficVision units come with self-signed SSL certificate by default. Clients should take this into account while performing HTTPS request. For instance in libcurl (http://curl.haxx.se/) CURLOPT_SSL_VERIFYHOST and CURLOPT_SSL_VERIFYPEER options need to be set to 0.

TrafficVision