|
|
| (23 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| − | === General Description ===
| + | '''Overview and revision history for San Francisco:''' |
| − | Notes from [http://etherpad.com/wCotZZ0OCE Open311 DevCamp Etherpad]: San Francisco currently supports 311 Twitter integration and they're exciting about participating in the Open311 API, which they've been considering for a while. They agree that an API should not just be for looking at service requests, but also disseminating other information. They're happy to focus just on requests for now, but then moving on to be able to answer questions through the API too. Their first draft API was modeled after the DC API and they're fast tracking development over the next few months. Currently, they're using the Lagan system to route to departments that do the work. They also have a middleware system, using Oracle, but thinking of changing that model. They want 311 to serve as a central hub and have other departments poll the system rather than pushing data out.
| + | |
| | | | |
| − | Here's the [http://apps.sfgov.org/Open311API/ Open311 section of San Francisco's website]
| + | Get API Keys: |
| | + | http://apps.sfgov.org/Open311API/?page_id=486 |
| | | | |
| | + | Current APIs |
| | + | * [[GeoReport v2]] |
| | + | * [[GeoReport v1]] |
| | | | |
| − | === Helping to Develop the API ===
| + | '''Implementation History''' |
| | | | |
| − | We hold regular conference calls to discuss the development of the API. These typically occur about once a month and will be announced on the blog and mailing list. The mailing list can also be used to facilitate discussion of the API.
| + | '''April 2011''' |
| | | | |
| − | === Proposed Architecture ===
| + | We've posted our Discovery service on the Open311 GeoReport v2 Servers page [http://wiki.open311.org/GeoReport_v2/Servers] |
| − | [[File:achitecture2010.jpg]] | + | |
| | | | |
| − | === <h2>Open 311 API</h2> ===
| + | We have added a few new services related to Blight, clarified services related to trees, and removed some that really should be called in to the center (like water main break!) |
| − | <h2>Description</h2>
| + | |
| − | Open311 will make public APIs for developers to build applications to report issues such as graffiti, potholes, and street cleaning directly to city departments.
| + | |
| − | <h3>Service Lifecycle</h3>
| + | |
| − | The following describes the user experience for submitting a 311 service request:
| + | |
| | | | |
| − | Service Request >> Select Location >> Service Details>> Citizen Information (optional): >> Service Request # and Service Level Agreement >> Status Update
| + | '''Feb 2011''' |
| | | | |
| − | <h3>city_id</h3>
| + | We have launched our own Facebook application using the Open311 API [http://www.facebook.com/SF311#!/SF311?sk=app_128760367192739] |
| − | As a means to allow this API to be used by multiple cities we've included a "city_id" which will be the unique identifier for cities. It has been suggested that we use the city's url as the "city_id". We have incorporated that suggestion into our design and the city_id for San Francisco = sfgov.org
| + | |
| | | | |
| − | <h3>Select Service</h3>
| + | '''Production API Keys have been issued to:''' |
| − | <ul><strong>Purpose:</strong> provide a list of acceptable 311 services and associated service code<br>
| + | *Blockboard[http://blockboard.org/] |
| − | <strong>Method name:</strong> service_list<br>
| + | *Citysourced[http://www.citysourced.com/default.aspx] |
| − | <strong>URL:</strong>https://open311.sfgov.org/dev/V1/service_list<br>
| + | *HeyGov[http://www.heygov.com/default.aspx?MapID=SanFran311] |
| − | <strong>Sample URL:</strong> https://open311.sfgov.org/dev/V1/service_list?api_key=xyz&city_id=sfgov.org<br>
| + | *Mojipage[http://mojipage.com/] |
| − | <strong>Formats: </strong>xml<br>
| + | *SeeClickFix[http://www.seeclickfix.com/] |
| − | <strong>HTTP Method: </strong>GET<br>
| + | *TweetMy311[http://tweetmy311.org/] |
| − | <strong>Requires Authentication: </strong>false<br>
| + | |
| − | <strong>Arguments: </strong><ul><li>api_key</li><li>city_id (for SF = sfgov.org)</li></ul><br>
| + | |
| − | <strong>Response:</strong> <ul><br>
| + | |
| − | list with the following:
| + | |
| − | <li>service_name</li>
| + | |
| − | <li>service_code</li>
| + | |
| − | <li>service_description</li></ul>
| + | |
| − | </ul>
| + | |
| − | <strong>Example:</strong><br>
| + | |
| − | | + | |
| − | <pre class="brush:xml">
| + | |
| − | | + | |
| − | <ServiceResponse>
| + | |
| − | <Open311ServiceList>
| + | |
| − | <service service_code="001" service_name="Cans left out 24x7" service_description="Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited. "/>
| + | |
| − | <service service_code="002" service_name="Construction plate shifted" service_description="Metal construction plate covering the street or sidewalk has been moved. "/>
| + | |
| − | <service service_code="003" service_name="Curb or curb ramp defect" service_description="Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb. "/>
| + | |
| − | <service service_code="004" service_name="Damaged city can" service_description="Damage to a city garbage receptacle such as missing parts (lid, door, liner) or other physical damage. "/>
| + | |
| − | <service service_code="005" service_name="Damaged side sewer vent cover" service_description="Damage to a side sewer vent cover with problems such as cracking, bending, rusting, or denting"/>
| + | |
| − | <service service_code="006" service_name="Damaged tree" service_description="Damage to a city maintained tree. To check whether a tree is city maintained: http://bit.ly/6hsDk1"/>
| + | |
| − | <service service_code="007" service_name="Graffiti on bike rack - not offensive" service_description="Graffiti on a bike rack that does not contain racial slurs, profanity, or gang related language"/>
| + | |
| − | <service service_code="008" service_name="Graffiti on news rack - not offensive" service_description="Graffiti on a news rack that does not contain racial slurs, profanity, or gang related language "/>
| + | |
| − | <service service_code="009" service_name="Graffiti on parking meter - not offensive" service_description="Graffiti on a parking meter that does not contain racial slurs, profanity, or gang related language "/>
| + | |
| − | <service service_code="010" service_name="Graffiti on pay phone - not offensive" service_description="Graffiti on a pay phone that does not contain racial slurs, profanity, or gang related language. "/>
| + | |
| − | <service service_code="011" service_name="Graffiti on private property - not offensive" service_description="Graffiti on a privately owned building or structure that does not contain racial slurs, profanity, or gang related language "/>
| + | |
| − | <service service_code="012" service_name="Graffiti on private property - offensive" service_description="Graffiti on a privately owned building or structure that contains racial slurs, profanity, or gang related language "/>
| + | |
| − | <service service_code="013" service_name="Graffiti on public property - offensive" service_description="Graffiti on public property (building, pole, sidewalk, hydrant, etc) with racial slurs, profanity, or gang related language "/>
| + | |
| − | <service service_code="014" service_name="Graffiti on public property- not offensive" service_description="Graffiti on public property (building, pole, sidewalk, hydrant, etc) without racial slurs, profanity, or gang related language "/>
| + | |
| − | <service service_code="015" service_name="Illegal dumping" service_description="Identify someone that has dumped or is dumping furniture or garbage onto the street or sidewalk. Violators will be cited "/>
| + | |
| − | <service service_code="016" service_name="Landscaping request" service_description="Request maintenance on public property (except on park property) such as lawn mowing, bush or strip trimming and removal "/>
| + | |
| − | <service service_code="017" service_name="Missed route - mechanical sweeping" service_description="Street cleaning sweeper did not show up as scheduled according to the street cleaning signs "/>
| + | |
| − | <service service_code="018" service_name="Missing side sewer vent cover" service_description="The 4" side sewer vent cover (http://bit.ly/57BlOv) is missing from the sidewalk "/>
| + | |
| − | <service service_code="019" service_name="Overflowing city receptacle or dumpster" service_description="City receptacle is overflowing and/or has garbage on and around the container "/>
| + | |
| − | <service service_code="020" service_name="Overgrown tree" service_description="Request that a city maintained tree (except on park property) be trimmed. To check whether a tree is city maintained: http://bit.ly/6hsDk1 "/>
| + | |
| − | <service service_code="021" service_name="Pothole in Street" service_description="Defect on the street such as broken, cracked, and sinking asphalt or concrete "/>
| + | |
| − | <service service_code="022" service_name="Sewage coming out of catch basin" service_description="Sewage or dirty water coming out of a catchbasin (located at the corner of intersections) "/>
| + | |
| − | <service service_code="023" service_name="Water coming from side sewer" service_description="Sewage or odor coming out of a 4" side sewer (http://bit.ly/57BlOv) located on the sidewalk "/>
| + | |
| − | <service service_code="024" service_name="Sidewalk cleaning" service_description="Have garbage or human waste removed from the sidewalk and/or request services such as steam cleaning of sidewalks "/>
| + | |
| − | <service service_code="025" service_name="Sidewalk defect" service_description="Defect on the sidewalk such as broken, cracked, and/or sinking concrete "/>
| + | |
| − | <service service_code="026" service_name="Street cleaning" service_description="Request to have garbage or human waste removed from the street "/>
| + | |
| − | <service service_code="027" service_name="Tree damaging property" service_description="Tree is damaging property (except for parks) or housing structure. City will address problem if it is a city maintained tree otherwise the property owner is notified to correct the issue "/>
| + | |
| − | <service service_code="028" service_name="Water main break" service_description="Street is flooding due to water coming from within the asphalt or from a catchbasin "/>
| + | |
| − | <service service_code="029" service_name="Graffiti on street sign" service_description="Graffiti on a street sign such as a stop sign, street name, and/or other parking and traffic signs "/>
| + | |
| − | <service service_code="030" service_name="Odor coming from Side Sewer" service_description="Odor coming out of a 4" side sewer (http://bit.ly/57BlOv) located on the sidewalk. "/>
| + | |
| − | <service service_code="031" service_name="Sewage coming out of manhole cover" service_description="Sewage or dirty water coming out of a manhole cover (typically located in the a street or alley) "/>
| + | |
| − | <service service_code="032" service_name="Sewage coming out of sewer vent" service_description="Sewage or dirty water coming out of a sewer vent (located on the sidewalk) "/>
| + | |
| − | <service service_code="033" service_name="Pothole in bike lane" service_description="Defect in the bike lane such as broken, cracked, and sinking asphalt or concrete. "/>
| + | |
| − | </Open311ServiceList>
| + | |
| − | <Open311Error/>
| + | |
| − | </ServiceResponse>
| + | |
| − | | + | |
| − | </pre>
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | <strong>
| + | |
| − | <h3>Create Request</h3> </strong>
| + | |
| − | <ul><strong>Purpose:</strong> Create services<br>
| + | |
| − | <strong>Method name:</strong> services<br>
| + | |
| − | <strong>URL:</strong> https://open311.sfgov.org/dev/V1/create_request<br>
| + | |
| − | <strong>Sample URL:</strong>https://open311.sfgov.org/dev/V1/create_request?api_key=xyz&city_id=sfgov.org&service_code=001&lat=37.76524078&lon=-122.4212043&address_string=xxxx 6thstreet&customer_email= smit333@sfgov.edu &device_id=tt222111&first_name=jo&last_name=smith&phone_number=111-111-1111&description=&media_url=http://okgogo.gogo </br>
| + | |
| − | <strong>Formats:</strong> xml<br>
| + | |
| − | <strong>HTTP Method:</strong> POST<br>
| + | |
| − | <strong>Requires Authentication:</strong> true<br>
| + | |
| − | <strong>Arguments:</strong>
| + | |
| − | <ul>
| + | |
| − | <li>api_key</li>
| + | |
| − | <li>city_id</li>
| + | |
| − | <li>service_code (obtained from method service_list)</li>
| + | |
| − | <li>lat [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)</li>
| + | |
| − | <li>lon [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)</li>
| + | |
| − | <li> address_string (human entered description of location)(if no lat/lon must provide this information)</li>
| + | |
| − | <li>customer_email (optional)</li>
| + | |
| − | <li>device_id (optional)</li>
| + | |
| − | <li>account_id (optional)</li>
| + | |
| − | <li>first_name (optional)</li>
| + | |
| − | <li>last_name (optional)</li>
| + | |
| − | <li>phone_number (optional)</li>
| + | |
| − | <li>description (free form limited to 4,000 characters) (optional)</li>
| + | |
| − | <li>media_url (url to the page that contains the media)(optional)</li>
| + | |
| − | </ul>
| + | |
| − | <strong>Response: </strong>
| + | |
| − | <ul><li>service_request_id</li>
| + | |
| − | <li>service_level_agreement (may not be returned)</li>
| + | |
| − | <li>account_id (may not be returned)</li>
| + | |
| − | <li>error codes</li>
| + | |
| − | </ul></ul>
| + | |
| − | <strong>Example:</strong><br>
| + | |
| − | | + | |
| − | <pre class="brush:xml">
| + | |
| − | | + | |
| − | <CreateResponse>
| + | |
| − | <Open311Error/>
| + | |
| − | | + | |
| − | <Open311Create>
| + | |
| − | <service_request_id>293944</service_request_id>
| + | |
| − | | + | |
| − | <service_level_agreement>
| + | |
| − | The City will inspect and require the responsible party to correct within 24 hours and/or issue a Correction Notice or Notice of Violation of the Public Works Code
| + | |
| − | </service_level_agreement>
| + | |
| − | | + | |
| − | <account_id/>
| + | |
| − | | + | |
| − | </Open311Create>
| + | |
| − | </CreateResponse>
| + | |
| − | | + | |
| − | | + | |
| − | </pre>
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | <h3>Status Update</h3>
| + | |
| − | <ul><strong>Purpose:</strong> provide a status update for service request<br>
| + | |
| − | <strong>Method name:</strong> status_update<br>
| + | |
| − | <strong>URL:</strong> https://open311.sfgov.org/dev/V1/status_update<br>
| + | |
| − | <strong>Sample URL:</strong> https://open311.sfgov.org/dev/V1/status_update?api_key=xyz&city_id=sfgov.org&service_request_id=293450 <br>
| + | |
| − | <strong>Formats: </strong>xml<br>
| + | |
| − | <strong>HTTP Method: </strong>GET<br>
| + | |
| − | <strong>Requires Authentication: </strong>true<br>
| + | |
| − | <strong>Arguments: </strong>
| + | |
| − | <ul><li>api_key</li><li>city_id</li>
| + | |
| − | <li>service_request_id</li>
| + | |
| − | </ul>
| + | |
| − | <strong>Response:</strong>
| + | |
| − | <ul><li>service_request_id</li>
| + | |
| − | <li>status</li>
| + | |
| − | <li>status_notes (may not be returned)</li>
| + | |
| − | <li>service_name</li></ul>
| + | |
| − | </ul>
| + | |
| − | <strong>Example:</strong><br>
| + | |
| − | | + | |
| − | <pre class="brush:xml">
| + | |
| − | | + | |
| − | <StatusResponse>
| + | |
| − | | + | |
| − | <Open311Status>
| + | |
| − | <service_request_id>293735</service_request_id>
| + | |
| − | <status>open</status>
| + | |
| − | <status_notes/>
| + | |
| − | <service_name>Graffiti on street sign</service_name>
| + | |
| − | </Open311Status>
| + | |
| − | | + | |
| − | <Open311Error/>
| + | |
| − | </StatusResponse>
| + | |
| − | | + | |
| − | </pre>
| + | |
| − | | + | |
| − | <h3>Error Codes</h3>
| + | |
| − | <ol><li> service_list:</li>
| + | |
| − | <ul><li> 100 Missing API Key </li>
| + | |
| − | <li> 101 Invalid APi Key </li>
| + | |
| − | <li> 102 General service error ( -- Missing service list file , anything that happens during service_list processing. It should be follow by an error description. The client will need to notify us) </li></ul>
| + | |
| − |
| + | |
| − | <li> create_request </li>
| + | |
| − | <ul><li> 200 Missing API Key </li>
| + | |
| − | <li> 201 Invalid API Key </li>
| + | |
| − | <li>202 Missing service Code </li>
| + | |
| − | <li> 203 Invalid Service Code </li>
| + | |
| − | <li> 204 General Service Error ( anything captured during create_request processing , Lagan WS is down , ....An error description will follow. Client will need to notify us) </li></ul>
| + | |
| − |
| + | |
| − | <li> status_update </li>
| + | |
| − | <ul> <li> 300 Missing API key </li>
| + | |
| − | <li> 301 Invalid API Key </li>
| + | |
| − | <li> 302 Id not valid or you are attemting to search for a service request you did not create </li>
| + | |
| − | <li> 302 General Service error ( anything captured during status_update processing. It will always have an error description ..Client will have to notify us) </li></ul>
| + | |
| − |
| + | |
| − | <li> HTTP error code: (from the browser). So far I have seen this </li>
| + | |
| − | <ul><li> 404 The UR L request is invalid or open311 service is not running or reachable. Client should notify us after checking URL </li></ul></ol>
| + | |
We have added a few new services related to Blight, clarified services related to trees, and removed some that really should be called in to the center (like water main break!)
