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 TRANBMClientRelations@gov.bc.ca.

Overview

This API serves DriveBC's implementation of the Open511 Specification. For a complete description of the specification including all technical details please refer to the Official Open511 Documentation.

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 http://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 http://api.open511.gov.bc.ca/events. By default 50 events are displayed. To display additional events (e.g., 100) use the following parameter - http://api.open511.gov.bc.ca/events?limit=100.

Jurisdiction

The jurisdiction represents a government entity (city, state/province department of transportation, agency, etc.) publishing Open511 data. Access this resource at http://api.open511.gov.bc.ca/jurisdiction

Jurisdiction Geography

The jurisdiction geography contains the boundaries of the jurisdiction. Access this resource at http://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 http://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.

FilterUsage Case
status

Returns all events with a status of ACTIVE.
http://api.open511.gov.bc.ca/events?status=ACTIVE.

severity

Returns all events with a severity of MAJOR.
http://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.
http://api.open511.gov.bc.ca/events?jurisdiction=drivebc.ca

event_type

Returns all events with the event_type 'WEATHER_CONDITION'.
http://api.open511.gov.bc.ca/events?event_type=WEATHER_CONDITION

event_subtype

Returns all events with the event_subtype 'ROAD_MAINTENANCE'.
http://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.
http://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
http://api.open511.gov.bc.ca/events?updated=<2013-12-01T12:00:00Z

road_name

Returns all events that take place on Highway 1.
http://api.open511.gov.bc.ca/events?road_name=Highway 1

area_id

Returns all events that take place within the Rocky Mountain District.
http://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).
http://api.open511.gov.bc.ca/events?bbox=-123.45,48.99,-122.45,49.49

geography
&
tolerance

Returns all events that take place within 50km of the Lions Gate Bridge in Vancouver. (These two filters must be used together)
http://api.open511.gov.bc.ca/events?geography=POINT(49.315059 -123.138925)&tolerance=50000

in_effect_on

Returns all events that take place between 2014-07-30 at Midnight and 2014-12-31 at 11:59pm.
http://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

 1 <open511
 2     xml:lang="en"
 3     xml:base="http://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.

FieldTypeDescription
jurisdictionsCollection 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

 1 <open511
 2     xmlns:gml="http://www.opengis.net/gml"
 3     xml:lang="en"
 4     xml:base="http://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="http://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.

FieldTypeDescription
selfLink

Mandatory

Self link to the current resource.

jurisdictionLink

Mandatory

Link to the jurisdiction publishing the event.

idOpen511 ID

Mandatory

A globally unique ID for the event, following the Open511 ID format.

statusEnum

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
headlineFree text

Mandatory

Title of the event. Should be shorter than 500 characters.

event_typeEnum

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

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.

geographyGeospatial

Mandatory

Geographical information about the event. Can be Point or LineString.

createdDateTime

Mandatory

When the event was initially created.

updatedDateTime

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.

descriptionFree 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_messageFree text

Custom

Interactive Voice Response message. A representation of the text displayed in emergency_message that is optimized for machine reading.

event_subtypesCollection 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
roadsCollection 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.

areasCollections 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

 1 <open511
 2     xml:lang="en"
 3     xml:base="http://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>TRANBMClientRelations@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="http://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="http://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": "TRANBMClientRelations@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.

FieldTypeDescription
selfLink

Mandatory

Self link to the current resource.

idString

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.

nameFree text

Mandatory

Name of the jurisdiction.

emailString

Mandatory

Valid email that can be used to contact the department or person in charge of the data provided by the Open511 API

descriptionLink

Optional

Link pointing to a human readable resource (web page, pdf file, etc) providing details about the Open511 service and the jurisdiction covered.

phoneString

Optional

Phone number to contact the department or person in charge of the data provided by the Open511 API

descriptionFree text

Optional

Free text that can be used by a client application to provide some information about the Open511 service and the jurisdiction covered.

geographyLink

Mandatory

The geography field links an open511 jurisdiction geography resource providing the jurisdiction boundaries.

timezonetimezone

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.

licenseLink

Mandatory

Link to a resource containing the license covering the data provided in the API.

emergency_messageString

Custom

Message describing an emergency situation, such as an amber alert, that is currently in effect. Blank if there is no emergency.

ivr_messageString

Custom

Interactive Voice Response message. A representation of the text displayed in emergency_message that is optimized for machine reading.

languagesCollection 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

 1 <open511
 2     xmlns:gml="http://www.opengis.net/gml"
 3     xml:lang="en"
 4     xml:base="http://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.

FieldTypeDescription
geographyGeospatial

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="http://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.

FieldTypeDescription
nameFree text

Mandatory

The name of the area.

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

selfLink

Optional

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