API

Version 6.6 | Document Updated 2017-05-09

The GRIDSMART API allows you to retrieve data and images from GRIDSMART Processors using HTTP. You can, for example, see camera images and even quad-views in any web browser, or even automate the retrieval of count and/or realtime data. You can also get the site history, current configuration, and camera status returned in XML (default) or JSON (by appending .json to the request).

In the documentation below you will find several live links to specific API calls. These links will work only if you are connected to a configured GRIDSMART Processor over the local port. If you can connect to a remote GRIDSMART Processor, you can replace the IP address in those URLs appropriately and query your own site.

The GRIDSMART API requires a defined User-Agent in the request headers to return results. Browsers supply this with requests made from the address bar, but most programmatic solutions don't neccessarily provide this header value natively.

Important Release Notes

Please see the special note regarding speed data and reporting at the end of this document.

We have recently made available some open source Python code that demonstrates interacting with the GRIDSMART API, in particular downloading and parsing traffic data from the GRIDSMART System.

With the GRIDSMART 6.4, the previously unused Confidence data element was removed from the count lines and new elements will be appended. If you parse count and/or realtime data files from the GRIDSMART System, we strongly advise that you write code that can gracefully handle the addition of new data elements. After GRIDSMART 6.4, we will not remove or re-order data elements in the count or realtime data lines; we may, however, append additional elements.

With GRIDSMART 6.0, the count file format and the structure of the downloaded data changed significantly. Please see Counts by date below for more detailed info.

API version

Get version of the GRIDSMART API that is running on the queried GRIDSMART Processor.

Example

http://ip:port/api

Parameters

None.

Returns

Plain text version number.

Camera image

Get an image for the specified camera.

Example

The best way to see an example camera image URL is to use the GRIDSMART Client. Select the site of interest and open Info on the Site Menu. The appropriate URLs can be found therein.

http://ip:port/api/camera/CAMERA_MAC_ADDRESS?SEND_NULL_IMAGE

Parameters

  • CAMERA_MAC_ADDRESS : MAC address of camera (see Camera status above).
  • SEND_NULL_IMAGE (optional) : Send null camera image (question mark) for offline camera. Defaults to true.

Returns

JPEG encoded image.

Camera status

Get the current camera status of all known cameras.

Examples

http://ip:port/api/camera
http://ip:port/api/camera.json

Parameters

None.

Returns

XML or JSON string. Contains up to three collections of cameras: Active, Missing and/or Unknown. Active cameras are those that are configured and operating. Missing cameras are those that are configured but not operating. Unknown cameras are those that are not configured but are operating.

Client

Downloads the Client installer from the Processor. The version of the Client downloaded will correspond to the Processor Firmware.

Examples

http://ip:port/api/client

Parameters

None.

Returns

Client EXE installer

Counts available

Get list of dates for which count data is available. (Requires valid license for Counts Module.)

Example

http://ip:port/api/counts
http://ip:port/api/counts.json

Parameters

None.

Returns

XML or JSON string.

Counts by date

Get zip-compressed, raw data for requested dates. Available dates can be queried using the Counts available API. Requires that the Processor be licensed for the Performance Module or the now-deprecated Counts Module. If the Processor being queried is licensed for the Performance Module, the returned package will also include event data and phase-based realtime data for the requested day.

Important Note: As of GRIDSMART 6.0, the count file format and the structure of the downloaded data have changed significantly; please continue reading for more detail or contact Support for further clarification.

Example

http://ip:port/api/counts/bydate/DATE?ZIPNAME

Parameters

None.

  • DATE : Date in YYYY-MM-DD form.
  • ZIPNAME (optional): Name for zip file. Defaults to counts.zip.

Returns

Zip file containing counts folder structure as described below for the different versions.

Count file formats and folder structure

Note that some of the data in the count files (i.e., speed and confidence) is experimental in nature and not officially supported.

v8 (new data types added with GRIDSMART 6.6)

In addition to events and realtime, the zip will have arrivals and states folders containing a YYYY-MM-DD.zip file with a GUID.csv for each zone. The arrivals file has a list of timestamps for arrivals for the zone GUID in the file name. The states file has a list of timestamps and the beginning and end state that the zone transitioned between for the zone GUID in file name. Please contact Support if you would like more detailed specifications on the contents of these files.

v8 (released with GRIDSMART 6.4)

Zipped folder structure: Returned zip archive contains one folder for each camera MAC. Inside that folder is one zipped YYYY-MM-DD.zip. Unzipping that archive will produce a GUID.csv for each zone, where the zone GUID can be found in the Site configuration for the appropriate revision, which contains columns as described below.

Additionally, with the Performance Module, the zip archive will contain two additional folders, events and realtime, each containing a YYYY-MM-DD.csv file. The events file contains timestamps, codes, and data for certain system events such as reboot, publish, flash, and phase changes. The realtime file contains minute-by-minute data, the same as that returned by the Realtime data by phase API, but for each minute the entire day rather than just the past hour. Please contact Support if you would like more detailed specifications on the contents of these files.

Zone count file CSV columns: Count Version (8), Site Version, Local Timestamp (HHMMSS.f format), UTC Offset In Minutes, Turn, Vehicle Length in Feet, Vehicle Speed in MPH (uncalibrated), Light State, Seconds in Zone, Vehicles Remaining in Zone, Seconds of Light State, Seconds Since Green, Zone Recent Free Flow Speed (-1 if unavailable), Zone Calibration Free Flow Speed (-1 if unavailable)

v7 (released with GRIDSMART 6.0)

Zipped folder structure: Returned zip archive contains one folder for each camera MAC. Inside that folder is one zipped YYYY-MM-DD.zip. Unzipping that archive will produce a GUID.csv for each zone, where the zone GUID can be found in the Site configuration for the appropriate revision, which contains columns as described below.

Additionally, with the Performance Module, the zip archive will contain two additional folders, events and realtime, each containing a YYYY-MM-DD.csv file. The events file contains timestamps, codes, and data for certain system events such as reboot, publish, flash, and phase changes. The realtime file contains minute-by-minute data, the same as that returned by the Realtime data by phase API, but for each minute the entire day rather than just the past hour. Please contact Support if you would like more detailed specifications on the contents of these files.

Zone count file CSV columns: Count Version (7), Site Version, Local Timestamp (HHMMSS.f format), UTC Offset In Minutes, Turn, Vehicle Length in Feet, Vehicle Speed in MPH (uncalibrated), Light State, Seconds in Zone, Vehicles Remaining in Zone, Confidence.

v4 (through GRIDSMART 5.4)

Zipped folder structure: Returned zip archive contains one folder for each camera MAC. Inside that folder is one GUID.csv file for each zone, where the zone GUID can be found in the Site configuration for the appropriate revision.

Zone count file CSV columns: CountFileVersion (4.0), SiteVersion, UtcTimestamp, InternalVehicleId, InternalVehicleType, VehicleLengthFeet, VehicleSpeedMph (uncalibrated), Turn, AllowableTurns, SecondsInZone, SecondsSinceLastExit, EstimatedQueueLength, LightStateOnExit, SecondsSinceGreen, InternalFrameCount, DayOrNight

Older versions

Please contact Support for information on older count file formats.

Date-time

Get current date, time and timezone setting.

Example

http://ip:port/api/datetime
http://ip:port/api/datetime.json

Parameters

None.

Returns

XML or JSON string. Also includes list of possible timezones.

Diagnostic data

Get diagnostic data such as temperature, voltages, tracking mode, camera gain, and camera exposure.

Examples

http://ip:port/api/diagnosticdata
http://ip:port/api/diagnosticdata.json

Parameters

None.

Returns

XML or JSON string.

Hardware ID

Get the hardware identifier.

Examples

http://ip:port/api/system/hardwareid
http://ip:port/api/system/hardwareid.json

Parameters

None.

Returns

XML or JSON string.

Hardware info

Get the hardware identifier and serial number.

Examples

http://ip:port/api/system/hardwareinfo
http://ip:port/api/system/hardwareinfo.json

Parameters

None.

Returns

XML or JSON string.

History hash

Get SHA 256 hash of the site history. Can be cached and used to determine if the site history has changed since last checked.

Examples

http://ip:port/api/historyhash
http://ip:port/api/historyhash.json

Parameters

None.

Returns

XML or JSON string.

License file

Get the license file.

Example

http://ip:port/api/license

Parameters

None.

Returns

XML string or 404 if no license file exists. License file will contain information about licensed modules such as Performance or Performance Plus.

Log files

Get the log files.

Example

http://ip:port/api/logs

Parameters

None.

Returns

Zipped archive of the system log files that might be requested for technical support issues.

Network Settings

Get the network settings.

Example

http://ip:port/api/network/settings
http://ip:port/api/network/settings.json

Parameters

None.

Returns

XML or JSON string.

Network Reachability

Get the reachability of network services from the Server.

Example

http://ip:port/api/network/reachability
http://ip:port/api/network/reachability.json

Parameters

None.

Returns

XML or JSON string.

NTP Settings

Gets the NTP Settings being used on the processor.

Example

http://ip:port/api/ntp
http://ip:port/api/ntp.json

Parameters

None.

Returns

XML or JSON string.

Output states

Get states for each of the possible 64 outputs.

Examples

http://ip:port/api/outputstates
http://ip:port/api/outputstates.json

Parameters

None.

Returns

XML or JSON string. The integer value for the output states is 1 to indicate the output is ON, 0 to indicate OFF.

Phases

Get current phases.

Examples

http://ip:port/api/phases
http://ip:port/api/phases.json

Parameters

None.

Returns

XML or JSON string. Phase state is indicated as an integer from 0 to 5 with the enumeration {UNKNOWN, RED, YELLOW, NOT_GREEN, PERMITTED_GREEN, GREEN}.

Quad view image

Get an image comprised of images from the four requested views.

Example

The best way to see an example QuadView URL is to use the GRIDSMART Client. Select the site of interest and change the Site View to the desired four-panel view. Open Info on the Site Menu and the appropriate URL can be found therein.

http://ip:port/api/quadview/CAMERA_MAC_ADDRESS,FISHEYE_X,FISHEYE_Y,ZOOM,IS_PERSPECTIVE&CAMERA_MAC_ADDRESS,FISHEYE_X,FISHEYE_Y,ZOOM,IS_PERSPECTIVE&CAMERA_MAC_ADDRESS,FISHEYE_X,FISHEYE_Y,ZOOM,IS_PERSPECTIVE&CAMERA_MAC_ADDRESS,FISHEYE_X,FISHEYE_Y,ZOOM,IS_PERSPECTIVEQUALITY

Parameters

  • CAMERA_MAC_ADDRESS : MAC address of camera (see Camera status above).
  • FISHEYE_X : The normalized fisheye point in the x plane to center on. This is used when the desired output of a fisheye camera is a converted rectilinear image. If you wish to retrieve a fisheye image, or if the camera is a rectilinear camera, you may leave this value as **0**.
  • FISHEYE_Y : The normalized fisheye point in the y plane to center on. This is used when the desired output of a fisheye camera is a converted rectilinear image. If you wish to retrieve a fisheye image, or if the camera is a rectilinear camera, you may leave this value as **0**.
  • ZOOM : This is zoom scale of the converted rectilinear image. If you wish to retrieve a fisheye image, or if the camera is a rectilinear camera, you may leave this value as **0**. Appropriate values range from **0 - 1.0** Above **1.0** images quickly begin to become very poor in quality.
  • IS_PERSPECTIVE : This is the boolean value indicating if the specified camera image should be converted to a rectilinear image using the *fisheyeX*, *fisheyeY*, and *zoom* parameters. If you wish to retrieve a fisheye image, or if the camera is a rectilinear camera, you may live this value as **false**.
  • QUALITY (optional) : JPEG quality factor from 0 to 100. Defaults to 25.

Returns

JPEG encoded image.

Realtime data by phase

Get last hour realtime data for each phase. Requires Performance or Performance Plus Module. Historical data can be downloaded using the Counts by date API.

Example

http://ip:port/api/realtimedata/phase
http://ip:port/api/realtimedata/phase.json

Parameters

None.

Returns

XML or JSON string of realtime data for each of the 16 possible phases for each minute of the last hour. Data includes minute-by-minute arrays of arrivals, arrivals on green, green occupancy time (seconds), green time (seconds), greens received (usually 0 or 1), occupancy time (seconds), percent arrivals on green, red occupancy time (second), red time (seconds), and turning movement counts by turn type. The arrays are ordered from 0 to 59 minutes past the hour. Also included is a current snapshot of the zone that includes current green time (seconds) and estimated occupancy count (number of vehicles in zone).

Realtime data by zone

Get last hour realtime data for each zone. Requires Performance or Performance Plus Module.

Example

http://ip:port/api/realtimedata/zone
http://ip:port/api/realtimedata/zone.json

Parameters

None.

Returns

XML or JSON string of realtime data for each zone for each minute of the last hour. The zone is described with approach, zone name, assigned phase(s), and assigned output(s). Includes minute-by-minute arrays of arrivals, arrivals on green, green occupancy time (seconds), green time (seconds), greens received (usually 0 or 1), occupancy time (seconds), percent arrivals on green, red occupancy time (second), red time (seconds), and turning movement counts by turn type. The arrays are ordered from 0 to 59 minutes past the hour. Also included is a current snapshot of the zone that includes current green time (seconds) and estimated occupancy count (number of vehicles in zone).

Realtime total volume

Get total volume counts. (Requires valid license for Realtime Data Module.)

Example

http://ip:port/api/realtimedata/volume
http://ip:port/api/realtimedata/volume.json

Parameters

None.

Returns

XML or JSON string of total volume counts. The data is returned in a list of 96 15 minute intervals that are in order from 00:00 to 24:00. The first entry is for 00:00-00:15, the second is for 00:15-00:30, so on and so forth until 23:45-24:00.

Realtime approach volume

Get total volume counts by approach. (Requires valid license for Realtime Data Module.)

Example

http://ip:port/api/realtimedata/approachvolume
http://ip:port/api/realtimedata/approachvolume.json

Parameters

None.

Returns

XML or JSON string of total volume counts, grouped by approach. The data is returned in a 5 element dictionary, one for each approach plus unassigned. Each approach entry has a list of 96 15 minute intervals that are in order from 00:00 to 24:00. The first entry is for 00:00-00:15, the second is for 00:15-00:30, so on and so forth until 23:45-24:00.

Realtime volume data

Gets all volume data. (Requires valid license for Realtime Data Module.)

Example

http://ip:port/api/realtimedata/volumedata
http://ip:port/api/realtimedata/volumedata.json

Parameters

None.

Returns

XML or JSON string of total volume counts as well as volume counts for each approach. This is a combination of the realtime total volume and the realtime approach volume API calls.

Realtime zone volume

Gets total volume counts by zone. (Requires valid license for Realtime Data Module.)

Example

http://ip:port/api/realtimedata/zonevolume
http://ip:port/api/realtimedata/zonevolume.json

Parameters

None.

Returns

XML or JSON string of total volume counts, grouped by zone. The data is returned as a dictionary with each entry representing a zone. Each zone entry has a list of 96 15 minute intervals that are in order from 00:00 to 24:00. The first entry is for 00:00-00:15, the second is for 00:15-00:30, so on and so forth until 23:45-24:00.

Site configuration

Get the current site configuration.

Example

http://ip:port/api/site
http://ip:port/api/site.json

Parameters

None.

Returns

XML or JSON string.

Site configuration at revision

Get site configuration for the specified revision.

Examples

http://ip:port/api/site/REVISION
http://ip:port/api/site/REVISION.json

Parameters

  • REVISION : Revision number of requested site configuration.

Returns

XML or JSON string.

Site history

Get full history of site configurations.

Examples

http://ip:port/api/history
http://ip:port/api/history.json

Parameters

None.

Returns

XML or JSON string.

Site ID

Get the site identifier.

Examples

http://ip:port/api/system/siteid
http://ip:port/api/system/siteid.json

Parameters

None.

Returns

XML or JSON string.

Site name

Get the site name that appears in the client (street1 & street2).

Examples

http://ip:port/api/sitename
http://ip:port/api/sitename.json

Parameters

None.

Returns

XML or JSON string.

Site revision info

Get site configuration information, including the site and publish data, for the specified revision.

Examples

http://ip:port/api/history/REVISION
http://ip:port/api/history/REVISION.json

Parameters

  • REVISION : Revision number of requested site configuration.

Returns

XML or JSON string.

Vehicle zone states

Get states for each of the possible 64 vehicle zones according to the specified camera.

Examples

http://ip:port/api/zonestates/vehicle/CAMERA_MAC_ADDRESS
http://ip:port/api/zonestates/vehicle/CAMERA_MAC_ADDRESS.json

Parameters

  • CAMERA_MAC_ADDRESS : MAC address of camera (see Camera status above).

Returns

XML or JSON string. The order of the zones in the returned value corresponds to the order of the zones in the current site configuration. The integer value for the zone state is a bit mask defined by the following enumeration {OFF = 0, ON = 1, LEARNING = 2, DETECTION = 4, TIME = 8, LATCHING = 16, LOSS_OF_VISIBILITY = 32, USER_SET = 256, USER = 512} where USER_SET implies the zone state was affected by a user and then the state of the USER bit defines whether or not the user activated or deactivated the zone.

Speed Data and Reporting in GRIDSMART

GRIDSMART has developed an approach to compute normalized speeds without resorting to complicated, error-prone, and potentially dangerous camera calibration methods. The user enters the approximate free flow speed for each zone in its Zone Options dialog. Generally, this should be approximately the posted speed limit, perhaps a little higher. The default value is 40mph, or 40kph if metric units have been selected in the Site Settings.

Why and how does GRIDSMART normalize speed?

The raw speed measurement computed by the Engine is subject to significant bias by very small camera tilt and/or road surface deviation from level. This, however, can be corrected statistically using a known, approximate free flow speed.

GRIDSMART observes the zones over a learning period of 14 days and equates the raw free flow speed during that time to the user-entered free flow speed to compute a normalization factor. The raw calibration free flow speed from the first 14 days, along with the most recent free flow speed over the last 14 days, are both recorded in each count line as noted in the count file documentation. Speeds written to the realtime data files and/or returned by the realtime data APIs are already normalized. Note that the computed normalization can be applied to generate accurate speed reports on historical data. Also note that a value of -1 for any speed data element means that no speed data is available.

Speed Reports

Speed reports are done by cycle for stop-line zones - i.e., those assigned to phases - with a user configurable Start-Up Lost Time. For zones without assigned phases, the speed reports are presented using the selected time interval. No data is shown for cycles or intervals with less than 3 measurements. Speed reports are not shown for zones without allowed thru movements.