BDW Header Image

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.

Crossing

A 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&param2=value...

Crossing Ids can be retrieved using the following call that will retrieve all active Crossings:

/Crossing/?format=json

Examples

Example 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:
avg (average)
min (minimum)
max (maximum)
sum (total or sum)
stdev (standard deviation)
var (variance)

Metrics:
delay (delay in minutes)
qmtr (queue length in meters)
qveh (queue length in vehicles)
rate (service rate in vehicles per hour)
vol (volume in vehicles per hour)
avail (data availability in number of samples)

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:
Table
Chart
JSON
CSV

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

Examples

TBD

Parameter Definition

Parameter 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:
avg (average)
min (minimum)
max (maximum)
sum (total or sum)
stdev (standard deviation)
var (variance)

Metrics:
delay (delay in minutes)
qmtr (queue length in meters)
qveh (queue length in vehicles)
rate (service rate in vehicles per hour)
vol (volume in vehicles per hour)
avail (data availability in number of samples)

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:
Table
Chart
JSON
CSV

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&param2=value...

Detector Ids can be retrieved using the following call that will retrieve all active Detectors:

/Detector?format=json

Examples

TBD

Parameter Definition

Parameter 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:
avg (average)
min (minimum)
max (maximum)
sum (total or sum)
stdev (standard deviation)
var (variance)

Metrics:
vol (volume in vehicles per hour)
occ (occupancy in percent)
spd (speed in kilometres per hour)
len (average vehicle length in meters)
avail (data availability in number of samples)

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:
Table
Chart
JSON
CSV

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:
JSON
CSV



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.

Example

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