Open311 - User contributions [en]

Open311.org Draft Spec

2010-08-26T13:16:15Z

Absh1us: /* Case Studies */

== Abstract ==

The Open311 API provides a way to work with service requests between citizens, governments and non-governmental organizations.

Open311 is decentralized. There is no central registry to which a providing system is required to register. There is also no central authority that lists the responsible Open311 providers for a particular location or set of concerns.

Open311 is intended to be applicable every where for all languages. The spec has been initially written in English with English terms solely for the convenience of the authors. All attempts were made to provide for the API to work for all language locales.

Open311 uses only standard HTTP requests and responses.

The Open311 API is a RESTful service. All GET requests are idempotent, they have no side effect other then returning data in a response to the client.

It is expected that multiple versions of the Open311 API will exist and interoperate concurrently. The spec is designed to allow service providers of different versions to be able to communicate together.

== Case Studies ==

* [http://apps.sfgov.org/Open311API/ San Francisco API draft]
* [http://octolabs.pbworks.com/Open-311-API-v2-Documentation Washington DC API v2 draft]
* [http://docs.google.com/View?id=dc8k3dxw_45gcnhm4dp SeeClickFix API draft]
*[http://www.wa-liability-insurance.com/ Liability Insurance Washington]

== Terminology ==

===Provider or Service Provider===
The system on which the API calls are made. This is the system that is mapped to by the URIs that a client makes HTTP calls to.

===Client===
The entity or system from which API calls are made. This could be a citizen's browser, a third party computer system or another service provider.

===Issue===
A specific, geographically stationary, concern that has a concrete definable fix. Some common names include: service request, work order or ticket.

===Citizen===
Any natural person.

===Non-Governmental Organization===
An entity that is not a government.

===Government===
The organization that manages a political unit of any size.

===Latitude / Longitude===
All latitudes and longitude values MUST be WGS84 (World Geodetic System 1984) datum values expressed in decimal format. See http://en.wikipedia.org/wiki/WGS84

Example: 37.40320,-121.977521

==Schema==

You can use syntax highlighting to help display a schema, eg JSON. See the [[Help:Editing]] for more information. Content pulled from working doc: http://etherpad.com/Gg1kfcXQR3

'''Service Request'''
<pre class="brush:jscript">
-id (alpha-numeric)
-status ("submitted", "incomplete", "rejected", "open", "assigned", "closed","more info", "in progress")
-location (location type)
-data feed URL (atom feed subscription)
-List of:
-who (string)
-activity date (date timestamp)
-description (text blob)
</pre>

'''Location'''
<pre class="brush:jscript">
-jurisdiction returns acceptable location schema (lat/lng, human readable address, internal ID)
-location {
lat/lng: GS84 (or what ever is the standard)
human readable location (String blob?)
3rd party addressing scheme (defined in meta data returned by jurisdiction)
}
</pre>

'''Linking service requests''' ( serial/parallel ? )
<pre class="brush:jscript">
-id { [id:status] }
</pre>

Location Schema

== System Architecture ==
Please note that this illustrates a proposal and does not represent the current API specs being implemented in Washington D.C. or San Francisco.

# Service request (SR) data and location are entered from open311 app. App requests SR jurisdiction API URI from [[GeoWeb DNS]] (if not already cached).
# The jurisdiction API URI is returned (eg http://api.nyc.gov/311). If no URI is found, default to an adhoc SR service (an equivalent of FixMyStreet or SeeClickFix)
# A generic SR (core schema) is sent to the jurisdiction API
# If successful, check if the app and jurisdiction supports extensions for additional details. If so, additional details for the identified SR type are requested (sr_type.get)
# Additional details are sent to the jurisdiction by any app and any person (not necessarily the original reporter) at a later date.

[[Image:311-flowchart.png]]

Toronto

2010-08-26T13:15:41Z

Absh1us: /* Operations */

===General Description===
The Toronto 311 Contact Centre launched Thursday, September 24, 2009. Contains 15000 frequently asked questions within its knowledge database.

====Operations====
* 24/7 Call Centre
* twitter channel ([http://twitter.com/311Toronto @311toronto]) for general information and customer service feedback
* website ([http://www.toronto.ca/311 toronto.ca/311])
*[http://www.wa-liability-insurance.com/ Liability Insurance Washington]

====System====
* ECM: Lagan Enterprise Case Management
* Knowledge Base: Lagan
* Online Self-Serve: Customized webservice built into Lagan system ( launched publicly Feb 2, 2010)
** Currently 18 self-serve topics

API

2010-08-26T13:14:50Z

Absh1us: /* Clients (can send and view reports) */

=Open311 APIs=

==GeoReport v2==
===Spec: [[GeoReport v2]]===

===Servers (can receive reports)===
{| class="wikitable sortable"
! Name
! Status
! API Key
! Dev API
! Production API
|-
| '''San Francisco'''
| ''Development Ready''
| [http://apps.sfgov.org/Open311API/?page_id=486 Request Key]
| [https://open311.sfgov.org/dev/V2/ Dev URL]
| [https://open311.sfgov.org/v2 Production URL]
|-
| '''Washington D.C.'''
| ''Development Ready''
| [http://api.dc.gov/key Request Key]
| [http://api.dc.gov/open311/v2_dev/ Dev URL]
| [http://api.dc.gov/open311/v2/ Production URL]
|}

==GeoReport v1==
===Spec: [[GeoReport v1]]===

===Servers (can receive reports)===
{|
! Name
! Status
! API Key
! Dev API
! Production API
|-
| '''City of San Francisco'''
| ''Production Ready''
| [http://apps.sfgov.org/Open311API/?page_id=486 Request Key]
| [https://open311.sfgov.org/dev/V1 Dev URL]
| [https://open311.sfgov.org/V1 Production URL]
|}

===Clients (can send and view reports)===
* [http://seeclickfix.blogspot.com/2010/05/seeclickfix-integrates-data-with-san.html SeeClickFix]
* [http://www.wa-liability-insurance.com/ Liability Insurance Washington]
* [http://blog.citysourced.com/index.php/54/citysourced-integrates-san-franciscos-open-311-system/ CitySourced]
* [http://tweetmy311.org/ TweetMy311]

====Client Libraries====
* [http://github.com/mheadd/PHPOpen311 PHP Library] by Mark Head

=Inactive APIs=
* [http://octolabs.pbworks.com/Open-311-API DC Open 311 v1]

GeoWeb DNS

2010-08-26T13:13:07Z

Absh1us: /* No results */

GeoWebDNS is a service inspired by DNS and reverse-geocoding. Given a lat/long, what is the URI of the standardized API, protocol, or file for a given service namespace (eg 311 services). The GeoWebDNS servers would be decentralized and redundant, automatically mirroring one-another and propagating out changes much like DNS servers. All that the client would need to do would be to send the lat/long and request the URI for a given namespace. The server would then have to look at the polygon that contains that lat/long for that service namespace and return the URI associated with it.

== Reference Implementation ==
http://demo.geowebdns.org/

== Protocol ==

The service will use HTTP. It exists at one URL; in this document we will use the example <code>http://ns.geowebdns.org/service</code> as the API endpoint.

A query uses query string arguments:

<code>lat</code>: The latitude. (WGS84)

<code>long</code>: The longitude. (WGS84)

'''Note''': should lat/long be one value? This makes it easier to add new query types. It might be like: <code>point=100.1234%2035.1234</code> (i.e., space-separated), or just comma-separated (which doesn't need to be quoted).

<code>type</code>: The ''type'' of object to be returned; this will be a string/URI. This argument may be present multiple times, returning jurisdictions with any of the given types.

A query then looks like:

<pre class="brush:jscript">
GET /service?lat=100.1234&long=35.1234&type=http://ns.geowebdns.org/311/jurisdiction
</pre>

The ''only'' coordinate system supported is [http://en.wikipedia.org/wiki/WGS84 WGS 84] (latitude/longitude).

In this example <code>http://ns.geowebdns.org/311/jurisdiction</code> might be the URI identifying 311 jurisdictions. URIs act similar to how an [http://en.wikipedia.org/wiki/Xmlns XML namespace] works; it is an opaque string, but by convention maps to a URL describing the type.

'''Note''': should we accept a level of confidence, using the same scale as presented [http://code.google.com/apis/maps/documentation/geocoding/#GeocodingAccuracy in the Google geocode API]? A low confidence might mean we do a more fuzzy search.

The response is a JSON object like:

<pre class="brush:jscript">
Content-type: application/json

{"results": [
{"type": "http://ns.geowebdns.org/311/jursidiction",
"uri": "http://sfgov.org/311/api",
"name": "San Francisco 311",
"kml": "http://ns.geowebdns.org/kml/3940193"
}
]
}
</pre>

The return result JSON is an object with one key, <code>"results"</code> (other keys may be added later, for example to specifying caching semantics or paging). The <code>"results"</code> key has a value of a list of all results matching this location.

Each result is an object with several keys:

<code>"type"</code>: The "type" of the jurisdiction. If you specify multiple <code>type=...</code> in your query, you can use this to determine which specific type this result is.

<code>"uri"</code>: The destination URL.

'''Note''': should there be a kind of "id URL" in addition to this more explicit URL? For instance, if there are multiple APIs, they might each have a different "type" but still represent the same basic entity. These could all have the same id URI (e.g., <code>http://sfgov/311</code>) but still different specific endpoints.

<code>"name"</code>: The name of the entity, a readable string.

'''Note''': should this be translated or translatable? E.g., <code>{"en_US": "San Francisco 311 Information", "es": "San Fransisco 311 Informacion"}</code> ?

<code>"kml"</code>: This ''optional'' response value points to a KML document describing the entity.

'''Note''': would it make sense to inline [http://geojson.org/ GeoJSON]?

== No results ==

If there are absolutely no results, it will return <code>{"results": []}</code> with a 404 status code.
[http://www.wa-liability-insurance.com/ Liability Insurance Washington]

== Errors ==

If the request is malformed, a 400 Bad Request response is given. The text of this response will be a readable description of the problem.

The readable format is defined by the Content-Type header, but will probably be HTML. Clients that cannot or do not want to present HTML can strip all tags and will get a description that is still readable.

'''Note''': are there any predictable errors? E.g., a lat/long that is impossible?

== Source ==

Source is at http://bitbucket.org/slinkp/geowebdns

To get started, run:

$ wget http://bitbucket.org/slinkp/geowebdns/raw/tip/setup-layout.sh
$ chmod +x setup-layout.sh
$ ./setup-layout.sh geowebdns-app

This product uses [http://cloudsilverlining.org/ SilverLining] for deployment. The stack consists of PostGIS, GeoAlchemy, WebOb.

To bootstrap a database, you can run these scripts:

$ cd src/geowebdns/imports
$ mkdir data
$ ./getall.sh
$ export CONFIG_PG_SQLALCHEMY=postgres://postgres:password@localhost/geowebdns # use your postgres password here
$ ./importall.sh --commit