Open 311 API

 

API is launched, see http://api.dc.gov 

 

Description:

Open 311 API will allow to programmatically submit and query service requests to Mayor's Call Center (311)

 

Open 311 API will support variety of types of service requests (e.g. broken signal, trash pickup, pothole, etc.) Each service request will have list of fields describing the service request, some of them are mandatary (e.g. location field, tied to DC GIS MAR), some of them will be optional (e.g. description, link to service request info in external system (such us future community website, built as part of Apps for Democracy))

 

List of SR types and field definitions are coming soon.

 

Technical Info:

NOTE:Right now we modelling our API based on Sunlight Labs http://wiki.sunlightlabs.com/Sunlight_API_Documentation as a good example of API used by a similar community.

 

Our API is RESTful with support of JSON 

 

http://api.dc.gov/api_name/version/method.format?apikey=YOUR_KEY&params - this GET call is for read-only methods

api_name - name of the API
version - version of the API
method - name of the method
format - json, xml, etc
YOUR_KEY - API key issued to you (get your key at http://api.dc.gov/key)
param - appropriate params corresponding to called method

 

Methods:

Open 311 will provide two separate APIs one will handle submission and query of 311 service requests and another will have supporting role in providing geocoding facility (valid District address required for most of the tickets to be submitted)

 

open311 API (API name - open311)

Methods for submitting and querying 311 service requests

 

submit

submits service request to 311 system and return temporary token 

   arguments: 

   servicecode - service code based on via meta_getTypesList

   aid - address id of location of the service request    

   arg1...argx - argument names based on service request type (obtained via meta_getTypeDefinition method)    

   description - free form description limited to 1024 characters (may change in the future) 

example: http://api.dc.gov/open311/dev/submit.json - Development environment (integrated with QC 311 env), feel free to test on it

example: http://api.dc.gov/open311/v1/submit.json - Production environment, no tests allowed after July 1st

 

POST should use Content-type application/x-www-form-urlencoded

 

getFromToken

returns service request ID based on temporary token 

   arguments: 

   token - temporary token (obtained via submit method) 

example: http://api.dc.gov/open311/v1/getFromToken.json?token=12345 

get

returns service request based on service request ID 

   arguments: 

   servicerequestid - service request ID (obtained via getFromToken method) 

example: http://api.dc.gov/open311/v1/get.json?servicerequestid=2116063 

 

meta_getTypesList

returns list of service request types 

   arguments: 

   no arguments required 

example: http://api.dc.gov/open311/v1/meta_getTypesList.json 

 

meta_getTypeDefinition

return list of all fields in requested SR type 

   arguments: 

   servicecode - service code corresponding to the service request type (obtained via meta_getTypesList method) 

example: http://api.dc.gov/open311/v1/meta_getTypeDefinition.json?servicecode=S0000 

 

geocoding API (API name - geocoding)

Methods for geocoding addresses inside of Washington, DC

 

search

returns matching addresses from MAR based on fuzzy search 

   arguments: 

   address - Washington, DC street address, must have at least building number and street name 

example: http://api.dc.gov/geocoding/v1/search.json?address=441 4th str, nw

 

getFromLatLong

returns closest address from MAR based on lat/long coordinates 

   arguments: 

   lat - latitude of the location (must be inside Washington, DC) 

   long - longitude of the location (must be inside Washington, DC) 

example: http://api.dc.gov/geocoding/v1/getFromLatLong.json?lat=38.89544591&long=-77.01565221

 

get

returns address from MAR based on MAR address ID 

   arguments: 

   aid - MAR address ID (obtained via search or getFromLatLong methods) 

example: http://api.dc.gov/geocoding/v1/get.json?aid=285552