Events

Purpose

This document outlines the resource types, filters and fields supported by DriveBC's Open511 API. Use the tabs below to access information on what the API does, how to use it and the message formats you can expect in response to your queries. For further information please refer to our API Terms of Use. If you are using this API we suggest you request to be added to our Open511 API distribution list to stay informed of changes we may be making. Send your request to MOTIDriveBC@gov.bc.ca.

Overview

This API serves DriveBC's implementation of the Open511 Specification.

The tabs above give you access to documentation on five separate Open511 resources. Of these, only the 'Events' resource is truly dynamic, allowing you to select the subset of active events that should be returned. The other four resources return static content, the only exception being the dynamic inclusion of the DEU emergency message in the Jurisdiction resource output. All documents can be requested in XML or JSON format. The Open511 standard supports the provision of multiple languages, but the resources presented in this initial implementation are English only. Use of the Information provided by this API is governed by the Open Government Licence – British Columbia (“OGL-BC”).

Resource Descriptions

Discovery	The root (or discovery) resource is the single entry point of an open511 endpoint. By following links from the discovery resource, clients can find and gain access to all resources within an Open511 implementation. Access this resource at `https://api.open511.gov.bc.ca/`
Events	The event resource provides information about road events (accidents, construction, special events). The events resource is a list of event elements matching the filtering parameters if any are provided. See below for event filter usage cases `https://api.open511.gov.bc.ca/events`. By default 50 events are displayed. To display additional events (e.g., 100) use the following parameter - `https://api.open511.gov.bc.ca/events?limit=100`. This API has a maximum request limit of 500. If more than 500 events are required, pagination is supported via the `limit` and `offset` parameters. Pagination can also be used with smaller limits to improve the API's performance. The following are pagination examples: Get 300 records in 3 calls: `https://api.open511.gov.bc.ca/events?limit=100&offset=0` `https://api.open511.gov.bc.ca/events?limit=100&offset=100` `https://api.open511.gov.bc.ca/events?limit=100&offset=200`
Jurisdiction	The jurisdiction represents a government entity (city, state/province department of transportation, agency, etc.) publishing Open511 data. Access this resource at `https://api.open511.gov.bc.ca/jurisdiction`
Jurisdiction Geography	The jurisdiction geography contains the boundaries of the jurisdiction. Access this resource at `https://api.open511.gov.bc.ca/jurisdictiongeography`
Areas	A geographical area: a city, district, neighbourhood, etc. These are represented by a jurisdiction id and an area number, e.g. drivebc.ca/3. In BC there are 11 areas. Access this resource at `https://api.open511.gov.bc.ca/areas`

Usage cases for the Events resource

The table below presents example urls for each of the supported event filters. Browsing the results of these queries will help newcomers understand how the API operates. These filters can be combined in the query string of a single GET request to further refine the search. For full documentation for the Events resource click on the 'Events' tab above.

Filter	Usage Case
status	Returns all events with a status of ACTIVE. `https://api.open511.gov.bc.ca/events?status=ACTIVE`.
severity	Returns all events with a severity of MAJOR. `https://api.open511.gov.bc.ca/events?severity=MAJOR`
jurisdiction	Returns all events with the jurisdiction 'drivebc.ca'. As this is the only jurisdiction currently supported, this query returns all active events. `https://api.open511.gov.bc.ca/events?jurisdiction=drivebc.ca`
event_type	Returns all events with the event_type 'WEATHER_CONDITION'. `https://api.open511.gov.bc.ca/events?event_type=WEATHER_CONDITION`
event_subtype	Returns all events with the event_subtype 'ROAD_MAINTENANCE'. `https://api.open511.gov.bc.ca/events?event_subtype=ROAD_MAINTENANCE`
created	Returns all events with a created date greater than the ISO 8601 date/time 2013-12-01T12:00:00Z. `https://api.open511.gov.bc.ca/events?created=>2013-12-01T12:00:00Z`
updated	Returns all events with an updated date less than the ISO 8601 date/time 2013-12-01T12:00:00Z `https://api.open511.gov.bc.ca/events?updated=<2013-12-01T12:00:00Z`
road_name	Returns all events that take place on Highway 1. `https://api.open511.gov.bc.ca/events?road_name=Highway 1`
area_id	Returns all events that take place within the Rocky Mountain District. `https://api.open511.gov.bc.ca/events?area_id=drivebc.ca/3`
bbox	Returns all events that fall within the geographical bounding box for the Greater Vancouver Regional Area (defined by four comma separated coordinates: xmin, ymin, xmax, ymax). `https://api.open511.gov.bc.ca/events?bbox=-123.45,48.99,-122.45,49.49`
geography & tolerance	Returns all events that take place within 10km of the Lions Gate Bridge in Vancouver. (These two filters must be used together) `https://api.open511.gov.bc.ca/events?geography=POINT(49.315059 -123.138925)&tolerance=10000` Note: Requests exceeding a tolerance of 10,000 metres will be downgraded to 10,000 metres.
in_effect_on	Returns all events that take place between 2014-07-30 at Midnight and 2014-12-31 at 11:59pm. `https://api.open511.gov.bc.ca/events?in_effect_on=2014-07-30T00:00,2014-12-31T23:59`

Discovery

Example

Example of the XML and JSON representations of the discovery resource

XML
JSON

 1 <open511
 2     xml:lang="en"
 3     xml:base="https://api.open511.gov.bc.ca/"
 4     version="v1"
 5 >
 6   <jurisdictions>
 7     <jurisdiction>
 8       <id>drivebc.ca</id>
 9       <name>Government of British Columbia</name>
10       <link rel="self" href="/jurisdiction" />
11     </jurisdiction>
12   </jurisdictions>
13   <services>
14     <service>
15       <link rel="self" href="/events" />
16       <link rel="service_type" href="http://open511.org/services/events" />
17     </service>
18     <service>
19       <link rel="self" href="/areas" />
20       <link rel="service_type" href="http://open511.org/services/areas" />
21     </service>
22   </services>
23   <link rel="self" href="/"/>
24 </open511>

Data structure

The following table provides the data structure for the root (discovery) resource.

Note that the discovery resource follows the rules of an individual item in formatting guidelines and not of a list since it contains different types of items. There is no up link since the discovery is the upper level.

Field	Type	Description
jurisdictions	Collection of `jurisdiction`	*Mandatory, at least one `jurisdiction` element is mandatory* List all the jurisdictions that are supported by the endpoint. Most of the time there will be only one occurrence, except for multiple jurisdictions endpoints and aggregators.
— id	String	*Mandatory* ID of the jurisdiction.
— name	Free text	*Mandatory* Full text name of the jurisdiction.
— self/url	Link	*Mandatory* Link to the jurisdiction resource. In XML, the `rel` attribute needs the value `self`. An aggregator should always point to the original jurisdiction resource and not copy it locally.
services	Collection of `service`	*Mandatory* List all the services supported by the endpoint.
— service_type	Link	*Mandatory* A URL representing an Open511 service like Events or Areas. The URL follows the same logic as an XML namespace: it's a unique identifier for the service type, though clients will never need to visit that URL. It's recommended that the URL point to human-readable documentation for the service. All services that are part of this specification will have URLs starting with `http://open511.org/services/`. Other organizations may want to build services that are outside the current scope of this specification but otherwise fit in with the other Open511 services; such services will have URLs not on open511.org. Such services must follow the guidelines of this specification. Values for current Open511 services are: `http://open511.org/services/events/` `http://open511.org/services/areas/` `http://open511/services/cameras/`
— self/url	Link	*Mandatory* Link pointing to the resource. In XML, the `rel` attribute needs the value `self`. Even if the current endpoint supports multiple jurisdictions or is an aggregator, there is only one service resource that aggregates the data for all the jurisdictions.
—supported_versions	Collection of `supported_version`	Optional List all the versions supported by the current server.
— — supported_version	Enum	Optional Version identifier.

Events

Example

Example of event representations (XML and JSON) as presented in a list of events

XML
JSON

 1 <open511
 2     xmlns:gml="http://www.opengis.net/gml"
 3     xml:lang="en"
 4     xml:base="https://api.open511.gov.bc.ca/"
 5     version="v1"
 6 >
 7   <events>
 8     <event>
 9       <status>ACTIVE</status>
10       <link rel="self" href="/events/drivebc.ca/153307" />
11       <link rel="jurisdiction" href="/jurisdiction" />
12       <id>drivebc.ca/153307</id>
13       <headline>Bridge Wash Out</headline>
14       <description>Closed at Border of British Columbia and Yukon because of Bridge Wash Out. Updated on Fri Jan 3 at 9:34 am PST. (ID# 153307) (Data by www.DriveBC.ca).</description>
15       <ivr_message>Atlin Highway, Southbound. at Border of British Columbia and Yukon. The road is closed, because of a bridge wash out. Last updated on Friday January 3 at 9:34 am.</ivr_message>
16       <event_type>INCIDENT</event_type>
17       <event_subtypes>
18         <event_subtype>HAZARD</event_subtype>
19       </event_subtypes>
20       <severity>MAJOR</severity>
21       <created>2014-01-03T07:42:22-07:00</created>
22       <updated>2014-01-03T07:54:35-07:00</updated>
23       <areas>
24         <area>
25           <name>Bulkley Stikine District</name>
26           <id>drivebc.ca/10</id>
27           <link rel="self" href="http://www.geonames.org/8630133" />
28         </area>
29       </areas>
30       <geography>
31         <gml:Point srsName="EPSG:4326">
32           <gml:coordinates>-133.794711,60.000275</gml:coordinates>
33         </gml:LineString>
34       </geography>
35       <roads>
36         <road>
37           <name>Atlin Highway</name>
38           <from>Border of British Columbia and Yukon</from>
39           <to/>
40           <direction>BOTH</direction>
41           <state>CLOSED</state>
42           <delay xmlns="https://www.drivebc.ca/api/open511-extensions" />
43         </road>
44       </roads>
45       <schedule>
46         <intervals>
47           <interval>2014-01-03T07:42/</interval>
48         </intervals>
49       </schedule>
50     </event>
51   </events>
52   <pagination>
53     <offset>0</offset>
54     <link rel="next" href="/events?offset=1&limit=1"/>
55   </pagination>
56   <link rel="self" href="/events"/>
57   <link rel="up" href="/"/>
58 </open511>

 1 {
 2     "events": [
 3         {
 4             "url": "/events/drivebc.ca/153307",
 5             "id": "drivebc.ca/153307",
 6             "jurisdiction_url": "/jurisdiction",
 7             "headline": "Limited Visibility with Heavy Snowfall",
 8             "status": "ACTIVE",
 9             "description": "Closed at Border of British Columbia and Yukon because of Bridge Wash Out. Updated on Fri Jan 3 at 9:34 am PST. (ID# 153307) (Data by www.DriveBC.ca).",
10             "+ivr_message": "Atlin Highway, Southbound. at Border of British Columbia and Yukon. The road is closed, because of a bridge wash out. Last updated on Friday January 3 at 9:34 am.",
11             "schedule": {
12                 "intervals": [
13                     "2014-01-03T07:42/",
14                 ]
15             },
16             "event_type": "INCIDENT",
17             "event_subtypes": [
18                 "HAZARD"
19             ],
20             "updated": "2014-01-03T07:54:35-07:00",
21             "created": "2014-01-03T07:42:22-07:00",
22             "severity": "MAJOR",
23             "geography": {
24                 "type": "Point",
25                 "coordinates": [
26                     [
27                         -133.794711,
28                         60.000275
29                     ],
30                 ]
31             },
32             "roads": [
33                 {
34                     "direction": "BOTH",
35                     "from": "Border of British Columbia and Yukon",
36                     "name": "Atlin Highway",
37                     "to": "",
38                     "state": "CLOSED",
39                     "+delay": ""
40                 },
41             ],
42             "areas": [
43                 {
44                     "url": "http://www.geonames.org/8630133",
45                     "name": "Bulkley Stikine District",
46                     "id": "drivebc.ca/10"
47                 },
48             ]
49         }
50     ],
51     "pagination": {
52         "next_url": "/events?offset=1&limit=1",
53         "offset": 0
54     },
55     "meta": {
56         "url": "/events",
57         "version": "v1",
58         "up_url": "/"
59     }
60 }

Event item structure

When events are provided as a list, they are formatted following the list format guidelines. The structure below defines an individual event item.

Field	Type	Description
self	Link	*Mandatory* Self link to the current resource.
jurisdiction	Link	*Mandatory* Link to the jurisdiction publishing the event.
id	Open511 ID	*Mandatory* A globally unique ID for the event, following the Open511 ID format.
status	Enum	*Mandatory* Indicates whether the event is still relevant or is archived data. `ACTIVE` refers both to events that are ongoing and events that are planned for the future. The status field should be set to `ARCHIVED` once the event has ceased or is otherwise out-of-date or no longer valid. Value list: - ACTIVE - ARCHIVED
headline	Free text	*Mandatory* Title of the event. Should be shorter than 500 characters.
event_type	Enum	*Mandatory* Basic type of event. Value list - CONSTRUCTION : planned road work - SPECIAL_EVENT : special events (fair, sport event, etc.) - INCIDENT : accidents and other unexpected events - WEATHER_CONDITION : Weather condition affecting the road - ROAD_CONDITION : Status of the road that might affect travelers.
severity	Enum	*Mandatory* Severity of the event. Value list: `MINOR`: the event has very limited impact on traffic. `MODERATE`: the event will have a visible impact on traffic but should not create significant delay; if there is a delay, it should be small and local. `MAJOR`: the event will have a significant impact on traffic, probably on a large scale. `UNKNOWN`: the impact is unknown, for example in the case of an accident that has been recorded without any precise description.
geography	Geospatial	*Mandatory* Geographical information about the event. Can be Point or LineString.
created	DateTime	*Mandatory* When the event was initially created.
updated	DateTime	*Mandatory* When the content of the event last changed. Will be the same as `created` if no updates have occurred.
schedule	Collection of `recurring_schedule` or `interval` elements.	*Mandatory* The full `schedule` of the event.
description	Free text	Optional, but strongly recommended Description of the event. Plain text description of the event, the reason for the event and any other relevant information for travelers.
ivr_message	Free text	*Custom* Interactive Voice Response message. A representation of the text displayed in emergency_message that is optimized for machine reading.
event_subtypes	Collection of `event_subtype` elements	Optional List of values to provide more detail about the type of event.
— event_subtype	Enum	Optional `ACCIDENT` `SPILL` `OBSTRUCTION` `HAZARD` `ROAD_MAINTENANCE` `ROAD_CONSTRUCTION` `EMERGENCY_MAINTENANCE` `PLANNED_EVENT` `CROWD` `HAIL` `THUNDERSTORM` `HEAVY_DOWNPOUR` `STRONG_WINDS` `BLOWING_DUST` `SANDSTORM` `INSECT_SWARMS` `AVALANCHE_HAZARD` `SURFACE_WATER_HAZARD` `MUD` `LOOSE_GRAVEL` `OIL_ON_ROADWAY` `FIRE` `SIGNAL_LIGHT_FAILURE` `PARTLY_ICY` 2 wheels of a passenger vehicle are on bare surface and the other wheels are likely on ice `ICE_COVERED` All wheels of a passenger vehicle are on ice `PARTLY_SNOW_PACKED` 2 wheels of a passenger vehicle are on bare surface and the other wheels are likely on snow bonded on the road `SNOW_PACKED` All wheels of a passenger vehicle are on snow bonded on the road `PARTLY_SNOW_COVERED` 2 wheels of a passenger vehicle are on bare surface and the other wheels are likely on loose snow `SNOW_COVERED` All wheels of a passenger vehicle are on loose snow `DRIFTING_SNOW` Snow drifts may extend into the driving lanes (accumulation greater than 20cm) `POOR_VISIBILITY` At certain locations, conditions may reduce visibility to less than 250 meters `ALMOST_IMPASSABLE` `PASSABLE_WITH_CARE`
roads	Collection of road elements	Optional List of roads affected by the current event. One event can impact several roads. The only fields currently supported are `name`, `from`, `to`, `state` and `direction`. An custom field `delay` has also been added which indicates the current delay to traffic in minutes.
areas	Collections of area elements	Optional Areas affected by the event. The only fields currently supported are `link`, `area` and `name`

Jurisdiction

Example

Example of the XML and JSON representations of the jurisdiction resource

XML
JSON

 1 <open511
 2     xml:lang="en"
 3     xml:base="https://api.open511.gov.bc.ca/"
 4     version="v1"
 5 >
 6   <jurisdictions>
 7     <jurisdiction>
 8       <link rel="self" href="/jurisdiction" />
 9       <id>drivebc.ca</id>
10       <name>Drive BC</name>
11       <email>MOTIDriveBC@gov.bc.ca</email>
12       <phone>(250) 387 7767</phone>
13       <description>Official traffic data for the Government of British Columbia</description>
14       <link rel="description" href="/help" />
15       <timezone>America/Vancouver</timezone>
16       <link rel="geography" href="/jurisdictiongeography"/>
17       <link rel="license" href="http://www.data.gov.bc.ca/local/dbc/docs/license/OGL-vbc2.0.pdf"/>
18       <languages>
29         <language>en</language>
20       </languages>
21       <emergency_message xmlns="https://www.drivebc.ca/api/open511-extensions"><![CDATA[<p>AMBER ALERT Click here --> <a href="http://bc.rcmp-grc.gc.ca/ViewPage.action?siteNodeId=14&languageId=1&contentId=-1">http://bc.rcmp-grc.gc.ca/ViewPage.action?siteNodeId=14&languageId=1&contentId=-1</a></p>]]></emergency_message>
22       <ivr_message xmlns="https://www.drivebc.ca/api/open511-extensions">AMBER ALERT  for today More information at RCMP website in bc dot R C M P dash G R C doc G C dot C A</ivr_message>
23     </jurisdiction>
24   </jurisdictions>
25   <link rel="self" href="/jurisdiction" />
26   <link rel="up" href="/" />
27 </open511>

Jurisdiction data structure

The jurisdiction follows the formatting guidelines of an individual item.

Field	Type	Description
self	Link	*Mandatory* Self link to the current resource.
id	String	*Mandatory* Unique identifier for the jurisdiction. It’s expected to be unique across all Open511 implementations. It must take the form of a hostname within a domain owned by the government entity. The hostname doesn’t necessarily need to resolve in DNS; for example, if Roadsville owns `roadsville.gov`, it’s fine to create `agency1.roadsville.gov` and `agency2.roadsville.gov` jurisdictions, even if those don’t resolve to IP addresses.
name	Free text	*Mandatory* Name of the jurisdiction.
email	String	*Mandatory* Valid email that can be used to contact the department or person in charge of the data provided by the Open511 API
description	Link	Optional Link pointing to a human readable resource (web page, pdf file, etc) providing details about the Open511 service and the jurisdiction covered.
phone	String	Optional Phone number to contact the department or person in charge of the data provided by the Open511 API
description	Free text	Optional Free text that can be used by a client application to provide some information about the Open511 service and the jurisdiction covered.
geography	Link	*Mandatory* The geography field links an open511 `jurisdiction geography` resource providing the jurisdiction boundaries.
timezone	timezone	Optional The time zone of the jurisdiction; will be used as the default for events belonging to this jurisdiction. It should always be provided, except in cases where a jurisdiction spans multiple timezones.
license	Link	*Mandatory* Link to a resource containing the license covering the data provided in the API.
emergency_message	String	*Custom* Message describing an emergency situation, such as an amber alert, that is currently in effect. Blank if there is no emergency.
ivr_message	String	*Custom* Interactive Voice Response message. A representation of the text displayed in emergency_message that is optimized for machine reading.
languages	Collection of `language`	Optional List of languages supported by this endpoint. A `language` element should be provided for each language supported
— language	Enum	*Mandatory* Multiple occurrences supported. The values supported are the same as the language negotiation feature

Jurisdiction Geography

Example

Example of the XML and JSON representations of the jurisdiction resource

XML
JSON

 1 <open511
 2     xmlns:gml="http://www.opengis.net/gml"
 3     xml:lang="en"
 4     xml:base="https://api.open511.gov.bc.ca/"
 5     version="v1"
 6 >
 7   <geographies>
 8     <geography>
 9       <gml:Polygon srsName="EPSG:4326">
10         <gml:outerBoundaryIs>
11           <gml:LinearRing>
12             <gml:coordinates>-131.76187062273667,60.001464264775976 <Many points here> -131.76187062273667,60.001464264775976</gml:coordinates>
13           </gml:LinearRing>
14         </gml:outerBoundaryIs>
15       </gml:Polygon>
16     </geography>
17   </geographies>
18   <link rel="self" href="/jurisdictiongeography" />
19   <link rel="up" href="/" />
20 </open511>

Jurisdiction geometry data structure

Although the jurisdiction geography could have been integrated directly in the jurisdiction resource, this data can easily take several kilobytes or even megabytes for complex countries/states, so we include it as a separate resource.

Field	Type	Description
geography	Geospatial	*Mandatory* Boundaries of the jurisdiction; a Polygon or MultiPolygon.

Field

Type

Description

geography

Geospatial

Mandatory

Boundaries of the jurisdiction; a Polygon or MultiPolygon.

Areas

Example

Example of the XML and JSON representations of the area resource in the context of a list.

XML
JSON

 1 <open511
 2     xml:lang="en"
 3     xml:base="https://api.open511.gov.bc.ca/"
 4     version="v1"
 5 >
 6   <areas>
 7     <area>
 8       <name>Lower Mainland District</name>
 9       <id>gov.bc.ca/1</id>
10       <link rel="self" href="http://www.geonames.org/8630136" />
11     </area>
12     <area>
13       <name>Vancouver Island District</name>
14       <id>gov.bc.ca/2</id>
15       <link rel="self" href="http://www.geonames.org/8630140" />
16     </area>
17   </areas>
18   <pagination>
19     <offset>0</offset>
20   </pagination>
21   <link rel="self" href="/areas"/>
22   <link rel="up" href="/"/>
23 </open511>

Area item data structure

The areas resource is a list of items. (A single area is not assigned its own resource URL in Open511, though it has a URL at GeoNames.) So the overall data structure follows the list structure as defined in the formatting guidelines. What follows defines a single area item.

Field Type Description

Field	Type	Description
name	Free text	*Mandatory* The name of the area.
id	Open511 ID	*Mandatory* Unique identifier for the area. If the area is a standard political division (city, state, province, county, etc.) you must use the ID from the GeoNames database, in the form of e.g. `geonames.org/5323810`. (GeoNames already lists millions of places, and so it's extremely likely that any area you're interested in is there already, but it’s also possible to add to GeoNames areas not already in their database). If (and only if) the area is defined internally by your jurisdiction, and is neither a standard political division nor already in GeoNames, assign a unique ID within your own jurisdiction: `gov.bc.ca/3`.
self	Link	Optional URL to a human-readable Web page with information about the area. For GeoNames areas, use `http://geonames.org/{id}/`

name

Free text

Mandatory

The name of the area.

Open511 ID

Mandatory

Unique identifier for the area. If the area is a standard political division (city, state, province, county, etc.) you must use the ID from the GeoNames database, in the form of e.g. geonames.org/5323810. (GeoNames already lists millions of places, and so it's extremely likely that any area you're interested in is there already, but it’s also possible to add to GeoNames areas not already in their database).

If (and only if) the area is defined internally by your jurisdiction, and is neither a standard political division nor already in GeoNames, assign a unique ID within your own jurisdiction: gov.bc.ca/3.

self

Link

Optional

URL to a human-readable Web page with information about the area. For GeoNames areas, use http://geonames.org/{id}/

DriveBC Open511 API Guidelines

Purpose

Overview

Resource Descriptions

Usage cases for the Events resource