API Reference
The Cascade Gateway data warehouse includes a Developer API that allows users to query the data warehouse and retrieve information in various formats including JSON and CSV. The API allows for the retrieval of data for crossings, crossing gates and detectors.
CrossingA crossing is a border crossing and can be queried for both directions or by a single direction. A crossing can be queried using query string parameters in the format of: /Crossing?param1=value¶m2=value...
Crossing Ids can be retrieved using the following call that will retrieve all active Crossings:
/Crossing/?format=json
ExamplesExample 1: Average Delay and Average Service Rate, between Jan 1-2010 and Mar 1-2010, for crossing ID 131. Prepare JSON-formatted response.
Crossing/?id=131&start=01/01/2010&end=03/01/2010&data=avg-delay,avg-rate&format=json
Example 2: Average Delay and Average Service Rate, between Jan 1-2010 and Mar 1-2010, for crossing ID 131. Group results by day-of-the-week. Prepare JSON-formatted response.
Crossing/?id=131&start=01/01/2010&end=03/01/2010&data=avg-delay,avg-rate&dg=DayOfWeek&format=json
Parameter Definition
Parameter | Default Value | Description |
---|---|---|
id | A valid crossing ID. Use the listing function to get valid IDs. | |
year |
The year to query. Must be a valid 4-digit number. Note: When year is provided, start, end, dg, tg, moy and dow parameters are ignored. |
|
month | The month to query. Only used if year is provided. Must be a valid 1- or 2-digit number (1 to 12). | |
day | The day of the month to query. Only used if year and month are provided. Must be a valid 1- or 2-digit number (1 to last day in the month). | |
start |
The date on which to start querying, inclusive. Must be in format: mm/dd/yyyy. Note: when providing this parameters, end parameter must also be provided. |
|
end |
The date on which to stop querying, inclusive. Must be in format: mm/dd/yyyy. Note: when providing this parameters, start parameter must also be provided. |
|
data | avg-vol |
The metrics and aggregations to return. Must be a comma-separated list of aggregation-metric pairs:
Aggregations:
Metrics: |
dir |
The direction of travel through the crossing to filter for. Must be one of: Northbound Southbound Eastbound Westbound |
|
lane |
The lane type through this crossing to filter for. Must be one of: Unspecified Car Truck Bus Fast Nexus |
|
dg | Day |
The date grouping to use for results. Must be one of: Day DayOfWeek Month MonthOfYear Year All |
tg | Poll |
The time grouping to use for results. Must be one of: Poll Hour AmPm Day |
dow | 127 |
The days of the week to include in the results, represented as a bitmask of the
following values. For instance, to select all days, pass 127. To select just Thursday
and Friday, pass 48. Sunday– 1 Monday – 2 Tuesday – 4 Wednesday – 8 Thursday – 16 Friday – 32 Saturday – 64 |
moy | 4095 |
The months of the year to include in the results, represented as a bitmask of the
following values. For instance, to select all months, pass 4095. To select just
July and October, pass 576. January – 1 February – 2 March – 4 April – 8 May – 16 June – 32 July – 64 August – 128 September – 256 October - 512 November – 1024 December – 2048 |
format | Table |
The desired output format of the data. Must be one of the following values: Note: Table and Chart formats return their values as a formatted HTML page. |
Crossing Gate
A crossing gate is a specific lane within a Crossing. Lanes can be of type Unspecified, Car, Truck, Bus, Fast or Nexus. The data for the crossing gate can be retrieved in json or csv formats.
Crossing Gate Ids can be retrieved using the following call that will retrieve all active Crossing Gates:
/CrossingGate/?format=json
ExamplesTBD
Parameter DefinitionParameter | Default Value | Description |
---|---|---|
id | A valid crossing gate ID. Use the listing function to get valid IDs. | |
year |
The year to query. Must be a valid 4-digit number. Note: When year is provided, start, end, dg, tg, moy and dow parameters are ignored. |
|
month | The month to query. Only used if year is provided. Must be a valid 1- or 2-digit number (1 to 12). | |
day | The day of the month to query. Only used if year and month are provided. Must be a valid 1- or 2-digit number (1 to last day in the month). | |
start |
The date on which to start querying, inclusive. Must be in format: mm/dd/yyyy. Note: when providing this parameters, end parameter must also be provided. |
|
end |
The date on which to stop querying, inclusive. Must be in format: mm/dd/yyyy. Note: when providing this parameters, start parameter must also be provided. |
|
data | avg-vol |
The metrics and aggregations to return. Must be a comma-separated list of aggregation-metric pairs:
Aggregations:
Metrics: |
dg | Day |
The date grouping to use for results. Must be one of: Day DayOfWeek Month MonthOfYear Year All |
tg | Poll |
The time grouping to use for results. Must be one of: Poll Hour AmPm Day |
dow | 127 |
The days of the week to include in the results, represented as a bitmask of the
following values. For instance, to select all days, pass 127. To select just Thursday
and Friday, pass 48. Sunday– 1 Monday – 2 Tuesday – 4 Wednesday – 8 Thursday – 16 Friday – 32 Saturday – 64 |
moy | 4095 |
The months of the year to include in the results, represented as a bitmask of the
following values. For instance, to select all months, pass 4095. To select just
July and October, pass 576. January – 1 February – 2 March – 4 April – 8 May – 16 June – 32 July – 64 August – 128 September – 256 October - 512 November – 1024 December – 2048 |
format | Table |
The desired output format of the data. Must be one of the following values: Note: Table and Chart formats return their values as a formatted HTML page. |
Detector
Detector data can be queried for any active detector using query string parameters in the format of: /Detector?param1=value¶m2=value...
Detector Ids can be retrieved using the following call that will retrieve all active Detectors:
/Detector?format=json
ExamplesTBD
Parameter DefinitionParameter | Default Value | Description |
---|---|---|
id | A valid detector ID. Use the listing function to get valid IDs. | |
year |
The year to query. Must be a valid 4-digit number. Note: When year is provided, start, end, dg, tg, moy and dow parameters are ignored. |
|
month | The month to query. Only used if year is provided. Must be a valid 1- or 2-digit number (1 to 12). | |
day | The day of the month to query. Only used if year and month are provided. Must be a valid 1- or 2-digit number (1 to last day in the month). | |
start |
The date on which to start querying, inclusive. Must be in format: mm/dd/yyyy. Note: when providing this parameters, end parameter must also be provided. |
|
end |
The date on which to stop querying, inclusive. Must be in format: mm/dd/yyyy. Note: when providing this parameters, start parameter must also be provided. |
|
data | avg-vol |
The metrics and aggregations to return. Must be a comma-separated list of aggregation-metric pairs:
Aggregations:
Metrics: |
dg | Day |
The date grouping to use for results. Must be one of: Day DayOfWeek Month MonthOfYear Year All |
tg | Poll |
The time grouping to use for results. Must be one of: Poll Hour AmPm Day |
dow | 127 |
The days of the week to include in the results, represented as a bitmask of the
following values. For instance, to select all days, pass 127. To select just Thursday
and Friday, pass 48. Sunday– 1 Monday – 2 Tuesday – 4 Wednesday – 8 Thursday – 16 Friday – 32 Saturday – 64 |
moy | 4095 |
The months of the year to include in the results, represented as a bitmask of the
following values. For instance, to select all months, pass 4095. To select just
July and October, pass 576. January – 1 February – 2 March – 4 April – 8 May – 16 June – 32 July – 64 August – 128 September – 256 October - 512 November – 1024 December – 2048 |
format | Table |
The desired output format of the data. Must be one of the following values: Note: Table and Chart formats return their values as a formatted HTML page. |
Current Delay For Crossing
Returns the current delay reading for the given crossing
Format: /Crossing/CurrentDelay/{id}
Example: /Crossing/CurrentDelay/136?format=json
Parameter | Default Value | Description |
---|---|---|
id | A valid crossing ID. Use the listing function to get valid IDs. | |
format | json |
The desired output format of the data. Must be one of the following values:
|
Returned Record Counts
The number of returned records depends on the selection criteria and the date / time groupings. The data is available in 5 min increments meaning that there are 288 records per day. If a date / time grouping is selected the following record counts are expected.
Time Grouping | ||||
---|---|---|---|---|
Date Grouping | Poll | Hour | AmPm | Day |
Day | # of days * 288 | # of days * 24 | # of days * 2 | # of days |
DayOfWeek | up to 7 * 288 | up to 7 * 24 | up to 7 * 2 | up to 7 |
Month | # of months * 288 | # of months * 24 | # of months * 2 | # of months |
MonthOfYear | up to 12 * 288 | up to 12 * 24 | up to 12 * 2 | up to 12 |
Year | # of years * 288 | # of years * 24 | # of years * 2 | # of years |
All | 288 | 24 | 2 | 1 |
Returned Record Format
The returned record format depends on selected data points, aggregations and format.
JSON
The JSON output format has the following parts:
DataSources – description of each data points in the query.
GroupStarts – datetime that marks the beginning of each time grouping (Microsoft
DateTime format for JSON).
GroupPollCounts – number of records for each group starts.
Values – array of values for each data point / group start.
The following example demonstrates the JSON output for the following query (for
detector id =1, year 2009, get average volume, average occupancy, average speed
and average length)
Detector?id=1&year=2009&data=avg-vol,avg-occ,avg-spd,avg-len&format=json
Output for this query looks the following way:
{ "DataSources":[ { "ID":1,"Calculation":"Average","Metric":"VolumeVehiclesPerHour" }, { "ID":1,"Calculation":"Average","Metric":"OccupancyPercent" }, { "ID":1,"Calculation":"Average","Metric":"AverageSpeedKilometersPerHour" }, { "ID":1,"Calculation":"Average","Metric":"AverageVehicleLengthMeters" } ], "GroupStarts":[ "\/Date(1230786000000)\/","\/Date(1233464400000)\/","\/Date(1235883600000)\/", "\/Date(1238558400000)\/","\/Date(1241150400000)\/","\/Date(1243828800000)\/", "\/Date(1246420800000)\/","\/Date(1249099200000)\/","\/Date(1251777600000)\/", "\/Date(1254369600000)\/","\/Date(1257048000000)\/","\/Date(1259643600000)\/" ], "GroupPollCounts":[ 8928,8064,8928,8640,8928,8640,8928,8928,8640,8928,8640,8928 ], "Values":[ [32,30,31,31,31,34,33,34,33,31,30,29], [49,54,56,59,58,58,60,60,55,54,54,55], [7,7,7,7,7,7,7,7,7,5,5,4], [8.2932173607450466,8.6278466741826119,8.9191859453818143,9.0773754152823916, 9.00521099744245,9.23903321275897,9.2370565453137079,9.4125232841381337, 8.91880407911,7.8172772356422993,7.5242192921582269,7.4289251844046289] ] }
Where the Data Sources section describes all the data points requests (4 metrics)
Group Starts section returns 12 dates marking the start of each month.
Group Poll Counts describes the number of values for each group start (12 in total)
Values includes 4 arrays of values corresponding to each of the requested metrics. Each array has values corresponding to each group start. CSV
The CSV output returns the data in a format that includes the Group Start (date
time) and a column for each requested metric as a comma separated file. For the
same query as above the output is:
Group Starts,Avg(Volume),Avg(Occupancy),Avg(Avg Speed),Avg(Avg Vehicle Length)
2009-01-01 12:00:00,32,49,7,8.29321736074505
2009-02-01 12:00:00,30,54,7,8.62784667418261
2009-03-01 12:00:00,31,56,7,8.91918594538181
2009-04-01 12:00:00,31,59,7,9.07737541528239
2009-05-01 12:00:00,31,58,7,9.00521099744245
2009-06-01 12:00:00,34,58,7,9.23903321275897
2009-07-01 12:00:00,33,60,7,9.23705654531371
2009-08-01 12:00:00,34,60,7,9.41252328413813
2009-09-01 12:00:00,33,55,7,8.91880407911
2009-10-01 12:00:00,31,54,5,7.8172772356423
2009-11-01 12:00:00,30,54,5,7.52421929215823
2009-12-01 12:00:00,29,55,4,7.42892518440463