Overview

purpose

The event resource provides information about road events (accidents, constructions, special events). The events resource is a list of event elements matching the filtering parameters if any are provided.

methodGET

Parameters

In addition to the filters described below, some URL parameters are common to all resources: format, version, accept-language, and limit.

ParameterRequired/optionalDescription
statusoptional

By default the API should only send events where the status field is ACTIVE. Supported filter values:

  • ACTIVE Default value, returns only active events.
  • ARCHIVED Returns only archived events
  • ALL Returns both active and archived events.

in_effect_onoptional

Show only events that are, according to their schedules, in effect at a specific time, or during a specific time period.

Can be either a single datetime, or a start and end datetime joined by a comma. Uses complete ISO 8601 datetimes, including both a date and a time (hh:mm, no seconds or milliseconds), with or without a timezone.

So to find, for example, all events in effect at some point on June 20th, you would ask for events between 00:00 and 23:59:
in_effect_on=2013-06-20T00:00,2013-06-20T23:59

Or, to find events in effect within the next two hours, you'd get the current UTC timestamp — let's say it's 2013-06-20T17:40Z — and then request ?in_effect_on=2013-06-20T17:40Z,2013-06-20T19:40Z.

If no timezone is provided, as in the first example, the server searches according to the local time as entered in the event. For example, if highways are closed for an hour at midnight on January 1st in both London and LA, ?in_effect_on=2014-01-01T00:00 would return both events (even though there's no single moment in time when the roads are closed in both cities), whereas the timezone-aware ?in_effect_on=2014-01-01T00:00Z would return only the London event.

Using an in_effect_on filter implies ?status=ACTIVE. That is, queries wih an in_effect_on filter should never return archived events.

The server must consider the entirety of an event's schedules in determining whether it's in effect at a given time -- which days a schedule covers, the start_time and end_time, any specific_dates, etc.

If this argument is not provided, the API should not perform any filtering based on the event schedules.

severityoptional

Filter by the value of the severity field. OR queries are possible via a comma-separated list: ?severity=MINOR,MODERATE.

bboxoptional

Filter events by geographical bounding box. Four comma-separated coordinates, xmin, ymin, xmax, ymax.

geographyoptional

Filtering near a point or linestring. The geography value should be provided as a WKT string in WGS84 latitude/longitude. Example:
...geography=POINT (-73.64 45.52).
The geography must be used in conjuction with the tolerance filter.

toleranceconditional

Provide a tolerance of radius in meters around if a POINT or LINESTRING is used as filtering parameter. For example ...geography=POINT+(-73.64+45.52)&tolerance=50 would retrieve all the events within a circle of 50m radius around the selected point.

jurisdictionoptional

The ID of a jurisdiction, in order to show only events from a given jurisdiction. Use a comma-separated list to make OR queries.

Example: jurisdiction=mycity.gov.

event_typeoptional

Filter events using the event_type value list. Use a comma-separated list to make OR queries.

event_subtypeoptional

Filter events using the event_subtype value list. Use a comma-separated list to make OR queries.

createdoptional

Filter events based on the creation date and time.

This parameter can (and generally will) be preceded with one of the following operators: < <= > >=. These allow searches for events created before or after a supplied time, e.g. created=>2013-05-10T12:00Z.

updatedoptional

Filter events based on the last update timestamp. Accepts the same < <= > >= operators as created.

Note: by default, the servers should only return ACTIVE events. When using the updated filter, in order to get events going from ACTIVE to ARCHIVED, the client must ask for all events: ...?status=ALL

road_nameoptional

Shows only events containing a road element with the provided name. Case-sensitive exact match. Use a comma-separated list to make OR queries.

roadoptional

Shows only events containing a road element linking to a road element with the provided id. Use a comma-separated list to make OR queries.

areaoptional

Shows only events containing a area element with the provided id. Use a comma-separated list to make OR queries.

Example

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
<open511
    xmlns:gml="http://www.opengis.net/gml"
    xml:lang="en"
    xml:base="http://api.open511.info/"
    version="v1"
>
  <events>
    <event>
      <status>ACTIVE</status> 
      <link rel="self" href="/events/my.city.gov/23948/" />
      <link rel="jurisdiction" href="http://my.city.gov/open511/jurisdiction/my.city.gov/" />
      <id>my.city.gov/23948</id>
      <headline>Urgent rebuilding of sewer pipes</headline> 
      <headline xml:lang="fr">Réfection d'urgence d'une conduite d'égout</headline> 
      <description>The City inform you that broadway street will be closed between 1st and 4th avenue during the month of april due to an emergency sewer rebuilding. Local circulation will be permitted on one lane East bound.</description>
      <description xml:lang="fr">La Ville de Montréal vous informe que la Grande avenue sera fermée à la circulation entre la 1ère et la 4ème avenue pour le mois d'avril pour cause de travaux d'urgence sur une conduite d'égouts. La circulation locale en direction de l'est sera permise sur une voie.</description>
      <event_type>CONSTRUCTION</event_type> 
      <event_subtypes>
        <event_subtype>EMERGENCY_MAINTENANCE</event_subtype>
      </event_subtypes>
      <severity>MODERATE</severity> 
      <created>2012-05-23T20:33:10Z</created>
      <updated>2012-05-24T10:00:10Z</updated>
      <grouped_events>
          <link rel="related" href="/events/my.city.gov/345832" /> 
          <link rel="related" href="/events/my.city.gov/433452" />         
      </grouped_events>
      <detour>Take Sherbrooke travelling east, and Wellington travelling west.</detour>
      <areas>
        <area> 
          <name>A City</name>
          <id>geonames.org/123456</id>
          <link rel="self" href="http://geonames.org/123456/" />  
        </area>
        <area> 
          <name>A County</name>
          <id>geonames.org/98765</id>
          <link rel="self" href="http://geonames.org/98765/" />  
        </area>     
      </areas>
      <geography>
        <gml:LineString srsName="urn:ogc:def:crs:EPSG::4326">
          <gml:posList>47.33 -71.17 47.36 -71.15 47.35 -71.1 47.4 -71.2</gml:posList>
        </gml:LineString>
      </geography>
      <roads>
        <road>
          <name>Broadway</name>
          <from>1st Avenue</from>
          <to>4th Avenue</to>
          <direction>E</direction>
          <state>SOME_LANES_CLOSED</state>
          <lanes_open>1</lanes_open>        
          <impacted_systems>
            <impacted_system>ROAD</impacted_system>
            <impacted_system>PARKING</impacted_system>
          </impacted_systems>
          <restrictions>
            <restriction>
              <restriction_type>SPEED</restriction_type>
              <value>35</value>
            </restriction>
          </restrictions>
        </road>
        <road>
          <name>Broadway</name>
          <from>1st Avenue</from>
          <to>4th Avenue</to>
          <direction>W</direction>  
          <state>CLOSED</state>
          <impacted_systems>
            <impacted_system>ROAD</impacted_system>
            <impacted_system>PARKING</impacted_system>
          </impacted_systems>
        </road>      
      </roads>
      <schedule>
        <recurring_schedules>
          <recurring_schedule>
            <daily_start_time>12:00</daily_start_time>
            <start_date>2014-09-01</start_date>
            <end_date>2014-09-30</end_date>
            <daily_end_time>15:00</daily_end_time>
          </recurring_schedule>
        </recurring_schedules>
        <exceptions>
          <exception>2014-09-15 09:00-13:00</exception>
          <exception>2014-09-16</exception>
        </exceptions>
      </schedule>
      <attachments>
        <link rel="related" title="Detour map" type="application/pdf" length="200345" href="http://my.city.gov/trafic/advisory/39473/com.pdf" hreflang="en" />
      </attachments>
    </event>
  </events>
  <pagination>
    <offset>0</offset>
    <link rel="next" href="/api/events/?limit=20&amp;offset=20"/>
  </pagination>
</open511>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
{
    "events": [
        {
            "url": "/events/my.city.gov/23948/", 
            "id": "my.city.gov/23948", 
            "jurisdiction_url": "http://my.city.gov/open511/jurisdiction/my.city.gov/",
            "headline": "Urgent rebuilding of sewer pipes", 
            "description": "The City inform you that broadway street will be closed between 1st and 4th avenue during the month of april due to an emergency sewer rebuilding. Local circulation will be permitted on one lane East bound.", 
            "status": "ACTIVE", 
            "event_type": "CONSTRUCTION", 
            "event_subtypes": [
                "EMERGENCY_MAINTENANCE"
            ], 
            "updated": "2012-05-24T10:00:10Z", 
            "created": "2012-05-23T20:33:10Z", 
            "severity": "MODERATE", 
            "detour": "Take Sherbrooke travelling east, and Wellington travelling west.", 
            "grouped_events": [
                "/events/my.city.gov/345832", 
                "/events/my.city.gov/433452"
            ], 
            "attachments": [
                {
                    "url": "http://my.city.gov/trafic/advisory/39473/com.pdf", 
                    "length": "200345", 
                    "type": "application/pdf", 
                    "title": "Detour map",
                    "hreflang": "en"
                }
            ], 
            "geography": {
                "type": "LineString", 
                "coordinates": [
                    [
                        -71.170000000000002, 
                        47.329999999999998
                    ], 
                    [
                        -71.150000000000006, 
                        47.359999999999999
                    ], 
                    [
                        -71.099999999999994, 
                        47.350000000000001
                    ], 
                    [
                        -71.200000000000003, 
                        47.399999999999999
                    ]
                ]
            }, 
            "schedule": {
                "recurring_schedules": [
                    {
                        "start_date": "2014-09-01",
                        "end_date": "2014-09-30",
                        "daily_start_time": "12:00",
                        "daily_end_time": "15:00"
                    }
                ],
                "exceptions": [
                    "2014-09-15 09:00-13:00",
                    "2014-09-16"
                ]
            },
            "roads": [
                {
                    "restrictions": [
                        {
                            "restriction_type": "SPEED", 
                            "value": 35
                        }
                    ], 
                    "direction": "E", 
                    "from": "1st Avenue", 
                    "name": "Broadway", 
                    "impacted_systems": [
                        "ROAD", 
                        "PARKING"
                    ], 
                    "to": "4th Avenue", 
                    "state": "SOME_LANES_CLOSED", 
                    "lanes_open": 1
                }, 
                {
                    "direction": "W", 
                    "from": "1st Avenue", 
                    "name": "Broadway", 
                    "impacted_systems": [
                        "ROAD", 
                        "PARKING"
                    ], 
                    "to": "4th Avenue", 
                    "state": "CLOSED"
                }
            ], 
            "areas": [
                {
                    "url": "http://geonames.org/123456/", 
                    "name": "A City", 
                    "id": "geonames.org/123456"
                }, 
                {
                    "url": "http://geonames.org/98765/", 
                    "name": "A County", 
                    "id": "geonames.org/98765"
                }
            ]
        }
    ],
    "pagination": {
        "next_url": "/api/events/?limit=20&offset=20", 
        "offset": 0
    }, 
    "meta": {
        "version": "v1"
    }
}

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. Must be an absolute URL.

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, MultiPoint, LineString, MultiLineString, or Polygon.

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.

More specifically, must be the time at which the current version of this event first became available via this Open511 API. Clients are likely to poll for changes via requests like ?status=ALL&updated=>2013-10-01T15:10Z where the timestamp is the last time they made such a request. Because of this, implementors need to be certain that an event version with an updated field of 2013-10-01T15:10Z was indeed accessible to API requests at that time.

scheduleSchedule element

Mandatory

Indicates the dates and times when the event is active.

timezonetimezone

Optional

Timezone to be used for this event, e.g. America/Montreal. If not provided, the event is assumed to be in the default timezone of its jurisdiction.

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.

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
certaintyEnum

Optional

Degree of certainty of the event. Should only be used for unplanned events (e.g incidents, weather conditions and pavement conditions events).

Value list

- OBSERVED
- LIKELY
- POSSIBLE
- UNKNOWN
grouped_eventsCollection of links

Optional

This structure is used to group events together. In specific situations (for example complex construction projects), several events might be related together. This field should be used to point a related event.

— related

Link

Optional

Link pointing to another event resource related to the current event.

detourFree text

Optional

Description of a detour route to avoid this event.

roadsCollection of road elements

Optional

List of roads affected by the current event. One event can impact several roads.

areasCollections of area elements

Optional

Areas affected by the event

attachmentsCollection of attachment links

Optional

Collection of attachments providing additional information about the event (PDFs, images, etc.)

— related

Link

Optional

Link to an attachment. While only the URL is mandatory, more information may be provided via type, length, title, and hreflang, with semantics as in Atom.

Road structure

The road data format is used to provide information about the road(s) affected by an event.

FieldTypeDescription
nameFree text

Mandatory

Name of the road affected by the event. Ideally, road names should be formatted in accordance with national or regional standards, and the same road should be named consistently in different events.

self / urlLink

Optional

Link to the Road resource for this road.

fromFree text

Optional (mandatory if to is provided)

Approximate start point of the event on the road. It can be an intersection with another street or it can be a mileage indication.

This value should not be used to determine the exact start point since it can be an approximation. The geometry field should be considered as the reference for exact location.

If no to field is provided, this field means "nearby".

toFree text

Optional

Approximate end point of the event on the road. It can be an intersection with another street or it can be a distance indication.

stateEnum

Optional

Whether the road segment is closed or not.

Value list:

- CLOSED (road closed in the given direction)
- SOME_LANES_CLOSED (but the road remains open)
- SINGLE_LANE_ALTERNATING (a single lane alternates between both directions of traffic)
- ALL_LANES_OPEN
directionEnum

Conditional: mandatory if state is provided

Direction of the road that is affected by the event.

Value list:

- N
- NW
- W
- SW
- S
- SE
- E
- NE
- NONE (only in the rare case of a road which can't be given a
direction; if direction is simply unknown, omit this field)

- BOTH
lanes_openInteger

Optional; allowed only if state is SOME_LANES_CLOSED and direction is not BOTH

Number of lanes in the given direction remaining open during this event.

lanes_closedInteger

Optional; allowed only if state is SOME_LANES_CLOSED and direction is not BOTH

Number of lanes in the given direction closed during this event.

impacted_systemsCollection of impacted_system elements

Optional

Allows provision of information about other systems that can be affected

— impacted_system

Enum

Optional

Value list of systems:

ROAD
SIDEWALK
BIKELANE
PARKING
restrictionsCollection of restriction elements

Optional

Some events may come with some restrictions affecting vehicles using the road (speed, weight).

Restriction structure

FieldTypeDescription
restriction_typeEnum

Mandatory

Type of restriction that affects vehicles. Value list:

  • SPEED: Limitation of the speed of vehicles. Unit is in kilometers/hour, unless the jurisdiction's distance_unit is miles, in which case it's miles/hour.
  • WIDTH: Width limitation, mainly for trucks. Unit is meters.
  • HEIGHT: Height limitation, mainly for trucks. Unit is meters
  • WEIGHT: Weight limitation for vehicles. Unit is metric tons.
  • AXLE_WEIGHT: Weight limitation per axle for truck. Unit is metric tons.

valuefloat

Mandatory

Value of the limitation. For example a speed limitation of 60km/h will have a value of 60 with a restriction_type set to SPEED

Schedule structure

Note that the schedule format has changed significantly since version 0.9.

FieldTypeDescription
recurring_schedulesCollection of recurring_schedule elements

One (and only one) of recurring_schedules or intervals is required

The recurring_schedule structure expresses repeating schedules, like "Every day starting December 4th", or "Mondays 9 to 11 from September 1 to October 30." An event can include multiple recurring_schedule elements inside this recurring_schedules tag; exception elements can override them.

— start_date

Date

Mandatory in each recurring_schedule

Start date of this schedule.

— end_date

Date

Optional

End date of this schedule. If a start date but no end date is provided, the schedule continues indefinitely.

— daily_start_time

Time

Optional

Daily start time of the event, as HH:mm, e.g. 13:00. Applies to each day in this recurring_schedule.

— daily_end_time

Time

Mandatory if daily_start_time is provided, not allowed otherwise

Daily end time of the event, as HH:mm, e.g. 17:30. Applies to each day in this recurring_schedule.

— days

Collection of day elements

Optional

Contains a day tag for every day of the week during which this recurring_schedule is active. Days are indicated with an integer, with (following the ISO standard) Monday being 1 and Sunday 7. So, for an event active on Monday and Wednesday, <days><day>1</day><day>3</day></days>. If omitted, the schedule is active every day between its start and end dates.

exceptionsCollection of exception elements

Optional; if present, there must be a recurring_schedules element (and no intervals)

Exceptions override recurring schedules.

— exception

Custom time format

An exception provides the definitive schedule for a specific date. It overrides any recurring_schedule information for that date.

An exception of the form YYYY-MM-DD indicates that this event is not in effect for the given date.

An exception of the form YYYY-MM-DD HH:mm-HH:mm indicates that, on that date, the event is in effect only between the provided start and end time. If there are multiple disjoint periods on that day, more than one start-end period can be included: YYYY-MM-DD HH:mm-HH:mm HH:mm-HH:mm.

intervalsCollection of interval elements

One (and only one) of recurring_schedules or intervals is required

Represent an event's schedule as a list of explicit periods. An event must use either recurring_schedules or intervals, not both.

If this contains more than one interval, their time periods may not overlap. This also implies that no more than one can omit an end time.

— interval

Custom time format, largely a subset of ISO8601 intervals

Defines a specific period of time during which the schedule is in effect; two datetimes (without timezone offset) joined with a /. For example, a period from 9 p.m. September 1 to 8 a.m. September 2 would be 2014-09-01T21:00/2014-09-02T08:00.

The second datetime, after the slash, may be omitted. So, to indicate a period from 9 p.m. September 1 until further notice, use: 2014-09-01T21:00/