DriveBC Open511 API Guidelines
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 |
| 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
This API has a maximum request limit of 500. If more than 500 events are required, pagination is supported via the |
| Jurisdiction | The jurisdiction represents a government entity (city, state/province department of transportation, agency, etc.) publishing Open511 data. Access this resource at |
| Jurisdiction Geography | The jurisdiction geography contains the boundaries of the jurisdiction. Access this resource at |
| 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 |
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. |
| severity | Returns all events with a severity of MAJOR. |
| jurisdiction | Returns all events with the jurisdiction 'drivebc.ca'. As this is the only jurisdiction currently supported, this query returns all active events. |
| event_type | Returns all events with the event_type 'WEATHER_CONDITION'. |
| event_subtype | Returns all events with the event_subtype 'ROAD_MAINTENANCE'. |
| created | Returns all events with a created date greater than the ISO 8601 date/time 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 |
| road_name | Returns all events that take place on Highway 1. |
| area_id | Returns all events that take place within the Rocky Mountain District. |
| 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). |
| geography & tolerance |
Returns all events that take place within 10km of the Lions Gate Bridge in Vancouver. (These two filters must be used together) |
| in_effect_on | Returns all events that take place between 2014-07-30 at Midnight and 2014-12-31 at 11:59pm. |
Discovery
Example
Example of the XML and JSON representations of the discovery resource
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>
1 {
2 "jurisdictions" : [
3 {
4 "id" : "drivebc.ca",
5 "name" : "Government of British Columbia",
6 "url" : "/jurisdiction"
7 },
8 ],
9 "services" : [
10 {
11 "service_type_url" : "http://open511.org/services/events",
12 "url" : "/events"
13 },
14 {
15 "service_type_url" : "http://open511.org/services/events",
16 "url" : "/areas"
17 }
18 ],
19 "meta": {
20 "version": "v1",
21 "url": "/"
22 }
23
24 }
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 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 |
|
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 Values for current Open511 services are:
|
|
— self/url | Link | Mandatory Link pointing to the resource. In XML, the |
|
—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
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 |
| 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 |
| severity | Enum | Mandatory Severity of the event. Value list:
|
| 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 |
| schedule | Collection of recurring_schedule or interval elements. |
Mandatory The full |
| 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
|
| 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 |
| areas | Collections of area elements | Optional Areas affected by the event. The only fields currently supported are |
Jurisdiction
Example
Example of the XML and JSON representations of the jurisdiction resource
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>
1 {
2 "jurisdictions": [
3 {
4 "id": "drivebc.ca",
5 "name": "Province of British Columbia",
6 "url": "/jurisdiction",
7 "description": "Official traffic data for the Government of British Columbia",
8 "description_url": "/help",
9 "geography_url": "/jurisdictiongeography",
10 "languages": [
11 "en"
12 ],
13 "phone": "(250) 387 7767",
14 "license_url": "http://www.data.gov.bc.ca/local/dbc/docs/license/OGL-vbc2.0.pdf",
15 "timezone": "America/Vancouver",
16 "email": "MOTIDriveBC@gov.bc.ca",
17 "+emergency_message": "<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>",
18 "+ivr_message": "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"
19 }
20 ],
21 "meta": {
22 "url": "/jurisdiction",
23 "version": "v1",
24 "up_url": "/"
25 }
26 }
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 |
| name | Free text | Mandatory Name of the jurisdiction. |
| 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 |
| 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 | 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
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>
1 {
2 "geographies": [
3 {
4 "type": "Polygon",
5 "coordinates": [
6 [ [-131.76187062273667,60.001464264775976], <Many points here >
7 [-131.76187062273667,60.001464264775976] ]
8 ]
9 }
10 ],
11 "meta": {
12 "version": "v1",
13 "url": "/jurisdictiongeography",
14 "up_url": "/"
15 }
16 }
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. |
Areas
Example
Example of the XML and JSON representations of the area resource in the context of a list.
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>
1 {
2 "areas": [
3 {
4 "url": "http://www.geonames.org/8630140",
5 "name": "Lower Mainland District",
6 "id": "gov.bc.ca/1"
7 },
8 {
9 "url": "http://geonames.org/8630140/",
10 "name": "Vancouver Island District",
11 "id": "gov.bc.ca/2"
12 }
13 ],
14 "pagination": {
15 "offset": 0
16 },
17 "meta": {
18 "url": "/areas",
19 "version": "v1",
20 "up_url": "/"
21 }
22 }
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 |
|---|---|---|
| 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. 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: |
| self | Link | Optional URL to a human-readable Web page with information about the area. For GeoNames areas, use |