The GRIDSMART Processor API allows you to retrieve data and images from GRIDSMART Processors using HTTPS requests. You can, for example, see camera images in any web browser, or automate the retrieval of count and/or realtime data. You can also get the site history, current configuration, and camera status.


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 Processor 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.


Contact Info: support@gridsmart.com
Version: 2.0

Base API URL

https://ip:port/api

Camera

get /camera
Gets the current camera status of all known cameras.

Contains up to three collections of cameras: Active, Missing and Unknown.

  • Active cameras are those that are configured and online.
  • Missing cameras are those that are configured but not online.
  • Unknown cameras are those that are not configured but are online.

Return type

String

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/xaml

Responses

200

OK String

get /camera/{macAddress}
Gets a JPEG image for the specified camera.
This is the same image that's visible in the GRIDSMART Desktop App and the GRIDSMART Web App

Path parameters

macAddress (required)
Path Parameter — default: null

Return type

File

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • image/jpeg
  • text/plain

Responses

200

OK File

404

Not Found String

get /cameras
Gets the current camera status as a bitmask

Returns a JSON object where each property is the mac address of a camera associated with the GRIDSMART Processor. Each JSON value is a bitmask representation of four possible camera states.

BitStateDescription
1History KnownThis camera is part of the Site configuration
2Engine OnlineThe Engine responsible for detecting and tracking the scene knows the camera is available
3Finder KnownThe Camera has been detected by the Camera finder
4Engine Receiving ImagesThe camera is providing images to the Engine

Return type

String

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK String

Counts

get /counts/bydate/{date}
Gets a zip file of count and performance data for the requested date.

Available dates can be queried using the /counts API.

This API requires one of the following modules:

  • Performance
  • Performance+
  • VDM
  • VDM+

Path parameters

date (required)
Path Parameter — default: null

Return type

File

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/zip

Responses

200

OK File

get /counts
Gets a list of dates for which count data is available.

This API requires one of the following modules:

  • Performance
  • Performance+
  • VDM
  • VDM+

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

General

get /datetime
Gets the processors current date, time, and timezone setting.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

get /outputstates
Gets states for each of the possible 64 detector outputs.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

get /phases
Gets current phases.

Phases are represented by the following enumeration

Unknown = 0
Red = 1
Yellow = 2
NotGreen = 3
Green = 5
FlashingYellow = 6

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

get /
Gets the Processor's Firmware Version.

Return type

String

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK String

get /sitename
DEPRECATED - Gets the site's name.
Use /site/name instead. This API will be removed in a future version.

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • text/plain

Responses

404

Not Found String

Up
get /zonestates/vehicle/{cameraMac}
Gets the current vehicle zone states for the specified camera.

The order of the zones in the returned value corresponds to the order of the zones in the current site configuration where the zones are sorted by ID. The integer value for the zone state is a bitmask 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
}

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.

The response array will always contain 64 elements. If N is the number of configured vehicle zones and N < 64, array elements for index i where N <= i < 64 will be 1 by default.

Path parameters

cameraMac (required)
Path Parameter — (Required) default: null

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

RealtimeData

get /realtimedata/approachvolume
Gets total volume counts by approach.

This API requires one of the following modules:

  • Performance
  • Performance+

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 ninety-six 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, and so on and so forth until 23:45-24:00.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

get /realtimedata/phase
Gets last hour realtime data for each phase.


This API requires one of the following modules:

  • Performance
  • Performance+

Historical data can be downloaded using the /counts/bydate/{date} API.

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).

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

Up
get /realtimedata/volume
Gets total volume counts.

This API requires one of the following modules:

  • Performance
  • Performance+

The data is returned in a list of ninety-six 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, and so on and so forth until 23:45-24:00.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

Up
get /realtimedata/volumedata
Gets all realtime volume data.


This API requires one of the following modules:

  • Performance
  • Performance+

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.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

Up
get /realtimedata/zone
Gets Realtime data for each zone for each minute of the last hour.

This API requires one of the following modules:

  • Performance
  • Performance+

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.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

Up
get /realtimedata/zonevolume
Gets total volume counts by zone.

This API requires one of the following modules:

  • Performance
  • Performance+

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 ninety-six 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.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

Site

Up
get /site
Gets the full site configuration, including history.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

Up
get /site/id
Gets the site ID.

Return type

String

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK String

Up
get /site/name
Gets the friendly site name.

Return type

String

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • text/plain

Responses

200

OK String

SiteRevisions

Up
get /site/revisions/current
Gets the current site revision.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

Up
get /site/revisions/{version}
Gets site revision for the specified revision number.

Path parameters

version (required)
Path Parameter — (Required) default: null

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object

System

Up
get /system/hardwareid
Gets the hardware identifier (ID).

Return type

String

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • text/plain

Responses

200

OK String

Up
get /system/hardwareinfo
Gets metadata about the GRIDSMART Processor.
This legacy API is maintained for backwards compatibility with the GRIDSMART Desktop App.

Return type

String

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/xaml

Responses

200

OK String

Up
get /system/siteid
DEPRECATED - Gets the site ID.
Use /site/id instead. This API will be removed in a future version.

Return type

Object

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

OK Object