This is a draft. It may be included in Open511 in the future, but is not currently a maintained part of the specification. If you're interested in using it or participating in its development, please get in touch.

Overview

purpose

Reports are road events reported by citizens/untrusted sources. The scope is the same as for the Event resorce, but the data are crowdsourced and unverified.

POST requests should be used to submit new reports.

GET requests will return a list of all the active reports.

methodPOST, GET

POST a report

Report data can be sent via the application/x-www-form-urlencoded or multipart/form-data content types. In general, the former is the better choice unless media are also being uploaded.

The URL to use for the post is the one defined in the discovery resource for the report service (the same to send GET requests)

POST data structure

Example of report POST with content type application/x-www-form-urlencoded:

POST /open511/reports/
Host: api.city.gov
Content-Type: application/x-www-form-urlencoded; charset=utf-8

jurisdiction=city.gov&lat=37.76524078&long=-122.4212043&device_id=tt222111&
first_name=John&last_name=Smith&phone=111111111&description=Major+accident+on+highway+680&
event_type=ACCIDENT&severity=2

POST data structure

FieldTypeDescription
jurisdictionString

Mandatory

ID of the jurisdiction to submit the report to.

latfloat

Mandatory

Latitude of the report in WGS84 projection

longfloat

Mandatory

Longitude of the report in WGS84 projection

first_nameString

Optional

First name of the person submitting the report

last_nameString

Optional

Last name of the person submitting the report

emailString

Mandatory

Email of the person submitting the report

phoneString

Optional

Phone number of the person who submitted the event

device_idString

Mandatory

Unique identifier for the device used to submit the report. It can be the MAC address of the network interface or use the getDeviceId() of Android devices or [UIDevice currentDevice].uniqueIdentifier for iPhone device

descriptionFree text

Mandatory

Description provided by the person who submitted the report.

event_typeEnum

Mandatory

Type of event declared by the person who submitted the report. Same value list as event_type on Event.

severityEnum

Optional

Severity of the event as judged by the person who submitted the report. Same value list as severity on Event.

mediabinary

Optional

Inline media data related to the event.

GET reports

Parameters

In addition to the filters described below, the events resource also supports format selection and language negotiation.

ParameterRequired/optionalDescription
statusoptional

By default, requests should return only reports that are OPEN or CONFIRMED. If this parameter is set to any of the valid status options, only reports with that status should be returned. If this parameter is set to ALL (case insensitive), all reports should be returned.

bboxoptional

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

Example

Example of the XML and JSON representations of the report resource as a list

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
<open511 
  xmlns:gml="http://www.opengis.net/gml" 
  xml:base="http://dev.open511.ca" 
  version="v1">
  <reports>
    <report xml:lang="en">
      <link rel="self" href="http://dev.open511.ca/api/report/1234/" />
      <link rel="jurisdiction" href="http://open511.ca/api/jurisdictions/mycity.gov/" />
      <geography>
          <gml:Point srsName="urn:ogc:def:crs:EPSG::4326">
            <gml:pos>47.33 -71.17</gml:pos>
          </gml:Point>
      </geography>    
      <description>Major accident on 8080E. Cars stopped in 2 lanes</description>
      <event_type>INCIDENT</event_type>
      <severity>2</severity>
      <status>OPEN</status>
      <created>2013-01-03T06:43:04+00:00</created>
      <updated>2013-01-09T21:31:04.967931+00:00</updated>
    </report>
  </reports>
  <pagination>
    <offset>0</offset>
    <link rel="next" href="/api/reports/?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
{
    "pagination": {
        "next_url": "/api/reports/?limit=20&offset=20", 
        "offset": 0
    }, 
    "meta": {
        "version": "v1"
    }, 
    "reports": [
        {
            "status": "OPEN", 
            "updated": "2013-01-09T21:31:04.967931+00:00", 
            "severity": 2, 
            "created": "2013-01-03T06:43:04+00:00", 
            "url": "http://dev.open511.ca/api/report/1234/", 
            "jurisdiction_url": "http://open511.ca/api/jurisdictions/mycity.gov/", 
            "event_type": "INCIDENT", 
            "geography": {
                "type": "Point", 
                "coordinates": [
                    -71.170000000000002, 
                    47.329999999999998
                ]
            }, 
            "description": "Major accident on 8080E. Cars stopped in 2 lanes"
        }
    ]
}

 

GET report data structure

The following table provide the general message structure of an individual report item. When provided in a list, the report resource follow the formatting guidelines for lists.

FieldTypeDescription
jurisdictionLink

Mandatory

Jurisdiction to whom the report was submitted.

geographygeography field

Mandatory

Location of the report. Only Point is supported.

descriptionFree text

Mandatory

Description provided by the submitter of the report.

event_typeEnum

Mandatory

Event type as provided by the submitter of the report. Same value list as event_type on Event.

severityEnum

Optional

Severity as provided by the submitter of the report. Same value list as severity on Event.

statusEnum

Mandatory

Status attributed by the jurisdiction. Value list:

  • OPEN - Default value. The report is active but not confirmed by the jurisdiction
  • CONFIRMED - The report is active and the jurisdiction has confirmed the report.
  • REJECTED - The jurisdiction has rejected the report
  • CLOSED - The report has been closed (either after being confirmed or not)
  • DUPLICATED - The report is considered as a duplicated of an existing event/report, which should be lined in the related field

createdDateTime (UTC)

Mandatory

When the event was initially created.

updatedDateTime (UTC)

Mandatory

Comment provided by the jurisdiction

relatedLink

Optional

Link pointing a related resource. As a general rule, the related link should used to point an official event that would replace the report.