The GeoReport Bulk data specification allows developers, researchers, and others to download issues which have been reported to government entities like cities for resolution. These interactions are often referred to as “service requests” or “calls for service” and have traditionally been handled by custom web forms or phone based call centers (sometimes using the 311 phone number or other short-code). The current specification is focused on location-based non-emergency issues such as graffiti, potholes, and street cleaning. It is designed to allow access to larger numbers of records (more than 1,000) that are impractical for a typical GeoReport_V2 API implementation to provide.

Many governments make service request data available in bulk form even if they do not offer a GeoReport API, however they do so in a highly inconsisent manner. For more information on how this specification was initially developed, see Untangling 311 Request Data. A mapping of more than 25 existing bulk data sources to the proposed specification is also available.

Status

Specification

Proposed: The GeoReport Bulk Spec has been researched and proposed, and is currently being piloted at the sites listed below.

Servers

Louisville, Kentucky, United States

Bloomington, Indiana, United States

San Diego, California, United States

Additional cities working to implement include:

Raleigh, NC

Kansas City, MO

Internationalization and Encoding

Date/time format

All date/time fields must be formatted in a common subset of ISO 8601 as per the w3 note. Timezone information (either Z meaning UTC, or an HH:MM offset from UTC) must be included.

Examples:

• 1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.
• 1994-11-05T13:15:30Z corresponds to the same instant.

Encoding

UTF-8 is required for all text responses, except when a DataPackage via an archive is provided.

All text provided by the server, whether in CSV, XML, JSON, or any other text-based content-type, MUST be encoded as UTF-8. Appropriate HTTP headers must be set, and the root element must be preceded with the XML declaration including the encoding=”UTF-8” attribute. All text received by the service from the client will be assumed to be UTF-8 and must be decoded accordingly. Examples of the HTTP content-type headers for each format are shown below under Format Support.

Format Support

The GeoReport Bulk data format is intended to be format-independent, though the most likely formats are those which include column/element identifiers such as CSV, JSON, and XML.

The HTTP content-type headers should be matched to the format in which the bulk data is to be transferred:

CSV: Content-Type: text/csv; charset=utf-8

XML: Content-Type: text/xml; charset=utf-8

JSON: Content-Type: application/json; charset=utf-8

CSV Support

CSV for the data should be Content-Type: text/csv. The CSV output must be compatible with RFC4180. Column headers MUST be included.

XML Support

XML for the data should be Content-Type: text/xml. The XML output currently defined is schemaless and without a namespace declaration. For now, extending the output with additional namespaces should be done at your own risk. To guarantee that all clients can support the XML output, it is recommended that you adhere to the specification strictly and do not include foreign tags or namespaces. It is also assumed that the default namespace is not specified, but if it must be specified, the XMLNS URI is the URL of the specification: http://wiki.open311.org/GeoReport_Bulk_v1

JSON Support

JSON for the data should be Content-Type: application/json. JSON support is based on a programmatic mapping of the XML format using the Spark Convention. This means that if you have an XML file, you can easily generate the JSON version with XSL. This can be done using a server side XSLT (php example).

Data Output

Fields

Example Outputs

• CSV
• XML
• JSON

"service_request_id","requested_datetime","updated_datetime","closed_date","status_description","status_notes","source","service_name","service_subtype","description","agency_responsible","address","lat","long"
"638344","2010-04-14T06:37:38-08:00",2010-04-14T06:37:38-08:00","2010-04-14T06:37:38-08:00","closed","Duplicate Request.","Phone","Sidewalk and Curb Issues","sample subtype","sample description","sample agency","8TH AVE and JUDAH ST","37.762221815","-122.4651145"

<?xml version="1.0" encoding="utf-8"?>
<service_requests>
    <request>
        <service_request_id>638344</service_request_id>
        <requested_datetime>2010-04-14T06:37:38-08:00</requested_datetime>
        <updated_datetime>2010-04-14T06:37:38-08:00</updated_datetime>
        <closed_datetime>2010-04-14T06:37:38-08:00</updated_datetime>
        <status_description>closed</status>
        <status_notes>Duplicate request.</status_notes>
        <source>Phone/source>
        <service_name>Sidewalk and Curb Issues</service_name>
        <service_subtype>sample subtype</service_subtype>
        <description>sample description</description>
        <agency_responsible>sample agency</agency_responsible>
        <address>8TH AVE and JUDAH ST</address>
        <lat>37.762221815</lat>
        <long>-122.4651145</long>
    </request>
</service_requests>

[
  {
    "service_request_id":638344,
    "requested_datetime":"2010-04-14T06:37:38-08:00",
    "updated_datetime":"2010-04-14T06:37:38-08:00",
    "closed_datetime":"2010-04-14T06:37:38-08:00",
    "status_description":"closed",
    "status_notes":"Duplicate request.",
    "source","Phone",
    "service_name":"Sidewalk and Curb Issues",
    "service_subtype":"sample subtype",
    "description":"sample description",
    "agency_responsible":"sample agency",
    "address":"8TH AVE and JUDAH ST",
    "lat":37.762221815,
    "long":-122.4651145
  }
]

Validators

The following list of validation tools can help you test whether your bulk output is compatible with the GeoReport Bulk Specification