Reports

Resources

Common

Getting Started

Tools

Versions

1.0 (current)
0.9
History

Contribute

Drafts

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.

method

POST, 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

Field	Type	Description
jurisdiction	String	*Mandatory* ID of the jurisdiction to submit the report to.
lat	float	*Mandatory* Latitude of the report in WGS84 projection
long	float	*Mandatory* Longitude of the report in WGS84 projection
first_name	String	Optional First name of the person submitting the report
last_name	String	Optional Last name of the person submitting the report
email	String	*Mandatory* Email of the person submitting the report
phone	String	Optional Phone number of the person who submitted the event
device_id	String	*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
description	Free text	*Mandatory* Description provided by the person who submitted the report.
event_type	Enum	*Mandatory* Type of event declared by the person who submitted the report. Same value list as `event_type` on Event.
severity	Enum	Optional Severity of the event as judged by the person who submitted the report. Same value list as `severity` on Event.
media	binary	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.

Parameter	Required/optional	Description
status	optional	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.
bbox	optional	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

XML
JSON

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.

Field	Type	Description
jurisdiction	Link	*Mandatory* Jurisdiction to whom the report was submitted.
geography	geography field	*Mandatory* Location of the report. Only `Point` is supported.
description	Free text	*Mandatory* Description provided by the submitter of the report.
event_type	Enum	*Mandatory* Event type as provided by the submitter of the report. Same value list as `event_type` on Event.
severity	Enum	Optional Severity as provided by the submitter of the report. Same value list as `severity` on Event.
status	Enum	*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
created	DateTime (UTC)	*Mandatory* When the event was initially created.
updated	DateTime (UTC)	*Mandatory* Comment provided by the jurisdiction
related	Link	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.