Collaboration for an Open311 Standard

Contents 1 Open 311 API 2 Description 2.1 city_id 2.2 Select Service 2.3 Create Request 2.4 Status Update 2.5 Error Codes

Open 311 API

Description

The Open311 API allows developers to build applications to report non-emergency issues such as graffiti, potholes, and street cleaning directly to government organizations like cities. The following organizations have adopted this API and allow access:

• City and County of San Francisco

city_id

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

Select Service

Purpose: provide a list of acceptable 311 services and associated service code
Method name: service_list
URL:https://open311.sfgov.org/dev/V1/service_list
Sample URL: https://open311.sfgov.org/dev/V1/service_list?api_key=xyz&city_id=sfgov.org
Formats: xml
HTTP Method: GET
Requires Authentication: false
Arguments:
• api_key
• city_id (for SF = sfgov.org)

Response:

list with the following:
• service_name
• service_code
• service_description

Example:

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

Create Request

Purpose: Create services
Method name: services
URL: https://open311.sfgov.org/dev/V1/create_request
Sample URL: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
Formats: xml
HTTP Method: GET
Requires Authentication: true
Arguments:
• api_key
• city_id
• service_code (obtained from method service_list)
• lat (WGS84) (required - either lat/lon or address string, both are preferred)
• lon (WGS84) (required - either lat/lon or address string, both are preferred)
• address_string (human entered description of location)(if no lat/lon must provide this information)
• customer_email (optional)
• device_id (optional)
• account_id (optional)
• first_name (optional)
• last_name (optional)
• phone_number (optional)
• description (free form limited to 4,000 characters) (optional)
• media_url (url to the page that contains the media)(optional)

Response:

• service_request_id
• service_level_agreement (may not be returned)
• account_id (may not be returned)
• error codes

Example:

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

Status Update

Purpose: provide a status update for service request
Method name: status_update
URL: https://open311.sfgov.org/dev/V1/status_update
Sample URL: https://open311.sfgov.org/dev/V1/status_update?api_key=xyz&city_id=sfgov.org&service_request_id=293450
Formats: xml
HTTP Method: GET
Requires Authentication: true
Arguments:
• api_key
• city_id
• service_request_id

Response:

• service_request_id
• status
• status_notes (may not be returned)
• service_name

Example:

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

Error Codes

1. service_list:
• 100 Missing API Key
• 101 Invalid APi Key
• 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)
2. create_request
• 200 Missing API Key
• 201 Invalid API Key
• 202 Missing service Code
• 203 Invalid Service Code
• 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)
3. status_update
• 300 Missing API key
• 301 Invalid API Key
• 302 Id not valid or you are attemting to search for a service request you did not create
• 302 General Service error ( anything captured during status_update processing. It will always have an error description ..Client will have to notify us)
4. HTTP error code: (from the browser). So far I have seen this
• 404 The UR L request is invalid or open311 service is not running or reachable. Client should notify us after checking URL