|
|
| (19 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| | + | '''Overview and revision history for San Francisco:''' |
| | | | |
| − | === <h1>Open 311 API</h1> ===
| + | Get API Keys: |
| − | <h2>Description</h2>
| + | http://apps.sfgov.org/Open311API/?page_id=486 |
| − | 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
| + | Current APIs |
| | + | * [[GeoReport v2]] |
| | + | * [[GeoReport v1]] |
| | | | |
| − | <h3>city_id</h3>
| + | '''Implementation History''' |
| − | 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>
| + | '''April 2011''' |
| − | <ul><strong>Purpose:</strong> provide a list of acceptable 311 services and associated service code<br>
| + | |
| − | <strong>Method name:</strong> service_list<br>
| + | |
| − | <strong>URL:</strong>https://open311.sfgov.org/dev/V1/service_list<br>
| + | |
| − | <strong>Sample URL:</strong> https://open311.sfgov.org/dev/V1/service_list?api_key=xyz&city_id=sfgov.org<br>
| + | |
| − | <strong>Formats: </strong>xml<br>
| + | |
| − | <strong>HTTP Method: </strong>GET<br>
| + | |
| − | <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">
| + | We've posted our Discovery service on the Open311 GeoReport v2 Servers page [http://wiki.open311.org/GeoReport_v2/Servers] |
| | | | |
| − | <ServiceResponse>
| + | 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!) |
| − | <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>
| + | '''Feb 2011''' |
| | | | |
| | + | We have launched our own Facebook application using the Open311 API [http://www.facebook.com/SF311#!/SF311?sk=app_128760367192739] |
| | | | |
| − | | + | '''Production API Keys have been issued to:''' |
| − | <strong>
| + | *Blockboard[http://blockboard.org/] |
| − | <h3>Create Request</h3> </strong>
| + | *Citysourced[http://www.citysourced.com/default.aspx] |
| − | <ul><strong>Purpose:</strong> Create services<br>
| + | *HeyGov[http://www.heygov.com/default.aspx?MapID=SanFran311] |
| − | <strong>Method name:</strong> services<br>
| + | *Mojipage[http://mojipage.com/] |
| − | <strong>URL:</strong> https://open311.sfgov.org/dev/V1/create_request<br>
| + | *SeeClickFix[http://www.seeclickfix.com/] |
| − | <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=xxxx6thstreet&customer_email=smit333@sfgov.edu&device_id=tt222111&first_name=jo&last_name=smith&phone_number=1111111111&description=&media_url=http://okgogo.gogo <br>
| + | *TweetMy311[http://tweetmy311.org/] |
| − | <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_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!)
