API
The GRIDSMART API allows you to retrieve data and images from GRIDSMART Processors using HTTP. You can, for example, see camera images 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 necessarily 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 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/apiParameters
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_IMAGEParameters
CAMERA_MAC_ADDRESS: MAC address of camera (see Camera status below).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/camerahttp://ip:port/api/camera.jsonParameters
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/clientParameters
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/countshttp://ip:port/api/counts.jsonParameters
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 performance data files for the requested days.
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?ZIPNAMEParameters
None.
DATE: Date in YYYY-MM-DD form.ZIPNAME(optional): Name for zip file. Defaults tocounts.zip.
Returns
Zip file containing counts folder structure as described below for the different versions.
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/datetimehttp://ip:port/api/datetime.jsonParameters
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, camera exposure and system uptime.
Examples
http://ip:port/api/diagnosticdatahttp://ip:port/api/diagnosticdata.jsonParameters
None.
Returns
XML or JSON string.
Hardware ID
Get the hardware identifier.
Examples
http://ip:port/api/system/hardwareidhttp://ip:port/api/system/hardwareid.jsonParameters
None.
Returns
XML or JSON string.
Hardware info
Get the hardware identifier and serial number.
Examples
http://ip:port/api/system/hardwareinfohttp://ip:port/api/system/hardwareinfo.jsonParameters
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/historyhashhttp://ip:port/api/historyhash.jsonParameters
None.
Returns
XML or JSON string.
License file
Get the license file.
Example
http://ip:port/api/licenseParameters
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 (Deprecated in v19.3)
Get the log files.
Example
http://ip:port/api/logsParameters
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/settingshttp://ip:port/api/network/settings.jsonParameters
None.
Returns
XML or JSON string.
Network Reachability
Get the reachability of network services from the Server.
Example
http://ip:port/api/network/reachabilityhttp://ip:port/api/network/reachability.jsonParameters
None.
Returns
XML or JSON string.
NTP Settings
Gets the NTP Settings being used on the processor.
Example
http://ip:port/api/ntphttp://ip:port/api/ntp.jsonParameters
None.
Returns
XML or JSON string.
Output states
Get states for each of the possible 64 outputs.
Examples
http://ip:port/api/outputstateshttp://ip:port/api/outputstates.jsonParameters
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/phaseshttp://ip:port/api/phases.jsonParameters
None.
Returns
XML or JSON string. Phase state is indicated as an integer from 0 to 5 with the enumeration {UNKNOWN=0, RED=1, YELLOW=2, NOT_GREEN=3, CURRENTLY_UNUSED=4, GREEN=5}.
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/phasehttp://ip:port/api/realtimedata/phase.jsonParameters
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/zonehttp://ip:port/api/realtimedata/zone.jsonParameters
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 (ZoneApproach), zone name (ZoneName), assigned phases (ProtectedPhases, PermittedPhases), assigned outputs (Outputs), and assigned turn types (ZoneTurnType).
Data includes minute-by-minute arrays of Exits, GreenOccupancyTime (seconds), GreensReceived (usually 0 or 1), GreenTime (seconds), MedianSpeedKph (-1 indicates no data), MedianSpeedMph (-1 indicates no data), OccupancyTime (seconds), PercentArrivalsOnGreen, PercentArrivalsOnRed, RedOccupancyTime (seconds), RedTime (seconds), and turning movement counts by turn type (TurnsLeft, TurnsRight, TurnsThrough, TurnsUturn). The arrays are ordered from 0 to 59 minutes past the hour according to the processor local time, which is provided as the Timestamp field for each zone.
Also included is a current Snapshot of the zone that includes CurrentGreenTime (seconds), current MedianSpeedKph (-1 indicates no data), current MedianSpeedMph (-1 indicates no data), and estimated OccupancyCount (number of vehicles in zone).
Other fields that may appear represent unused and/or unsupported data that may be from legacy applications or preserved for future use.
Realtime total volume
Get total volume counts. (Requires valid license for Realtime Data Module.)
Example
http://ip:port/api/realtimedata/volumehttp://ip:port/api/realtimedata/volume.jsonParameters
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/approachvolumehttp://ip:port/api/realtimedata/approachvolume.jsonParameters
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/volumedatahttp://ip:port/api/realtimedata/volumedata.jsonParameters
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/zonevolumehttp://ip:port/api/realtimedata/zonevolume.jsonParameters
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/sitehttp://ip:port/api/site.jsonParameters
None.
Returns
XML or JSON string.
Site configuration at revision
Get site configuration for the specified revision.
Examples
http://ip:port/api/site/REVISIONhttp://ip:port/api/site/REVISION.jsonParameters
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/historyhttp://ip:port/api/history.jsonParameters
None.
Returns
XML or JSON string.
Site ID
Get the site identifier.
Examples
http://ip:port/api/system/siteidhttp://ip:port/api/system/siteid.jsonParameters
None.
Returns
XML or JSON string.
Site name
Get the site name that appears in the client (street1 & street2).
Examples
http://ip:port/api/sitenamehttp://ip:port/api/sitename.jsonParameters
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/REVISIONhttp://ip:port/api/history/REVISION.jsonParameters
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_ADDRESShttp://ip:port/api/zonestates/vehicle/CAMERA_MAC_ADDRESS.jsonParameters
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.