forked from straup/open311-simple
-
Notifications
You must be signed in to change notification settings - Fork 0
/
api-methods.json
217 lines (205 loc) · 15 KB
/
api-methods.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
{
"default_format": "xml",
"formats": [
"xml",
"json"
],
"methods": {
"open311.services.getList": {
"description": "Provide a list of acceptable 311 service request types and their associated service codes. These request types can be unique to the city/jurisdiction. Corresponds to [GET Service List](http://wiki.open311.org/GeoReport_v2#GET_Service_List) in GeoReport v2",
"enabled": 1,
"documented": 1,
"requires_auth": 0,
"paginated": 1,
"method": "GET",
"slug" : "services.{format}",
"parameters": [
{ "name": "jurisdiction_id", "description": "A valid jurisdiction_id to get information about.", "required": 1 }
],
"response": [
{"name": "services", "description": "Root element."},
{"name": "service", "description": "Container for service_code, service_name, description, metadata, type, keywords, group."},
{"name": "service_code", "description": "The unique identifier for the service request type."},
{"name": "service_name", "description": "The human readable name of the service request type."},
{"name": "description", "description": "A brief description of the service request type."},
{"name": "metadata", "description": "Possible values: true, false", "bullets":
[
"true: This service request type requires additional metadata so the client will need to make a call to the Service Definition method",
"false: No additional information is required and a call to the Service Definition method is not needed."
]
},
{"name": "type", "description": "Possible values: realtime, batch, blackbox", "bullets":
[
"realtime: The service request ID will be returned immediately after the service request is submitted.",
"batch: A token will be returned immediately after the service request is submitted. This token can then be later used to return the service request ID.",
"blackbox: No service request ID will be returned after the service request is submitted."
]
},
{"name": "keywords", "description": "A comma separated list of tags or keywords to help users identify the request type. This can provide synonyms of the service_name and group."},
{"name": "group", "description": "A category to group this service type within. This provides a way to group several service request types under one category such as \"sanitation\""}
],
"possible_errors": [
{"status_code": "404", "description": " jurisdiction_id provided was not found (specify in error response)."},
{"status_code": "400", "description": "jurisdiction_id was not provided (specify in error response)."},
{"status_code": "400", "description": "General service error (Anything that fails during service list processing. The client will need to notify us)."}
],
"example" : "file://./api-methods-examples/open311.services.getList.json"
},
"open311.services.getInfo": {
"description": "Defines attributes associated with a service code. These attributes can be unique to the city/jurisdiction. This call is only necessary if the Service selected has metadata set as true from the GET Services response. Corresponds to [GET Service Definition](http://wiki.open311.org/GeoReport_v2#GET_Service_Definition) in GeoReport v2",
"enabled": 1,
"documented": 1,
"requires_auth": 0,
"method": "GET",
"slug" : "services/{id}.{format}",
"parameters": [
{ "name": "service_code", "description": "A valid service_code to get information about.", "required": 1 },
{ "name": "jurisdiction_id", "description": "A valid jurisdiction_id to get information about.", "required": 1 }
],
"response": [
{"name": "service_definition", "description": "Root element."},
{"name": "service_code", "description": "Returns the service_code associated with the definition, the same one submitted for this call."},
{"name": "attributes", "description": "Container for attribute."},
{"name": "variable", "description": "Options: true, false", "bullets": [
"true denotes that user input is needed.",
"false means the attribute is only used to present information to the user within the description field."
]},
{"name": "code", "description": "A unique identifier for the attribute"},
{"name": "datatype", "description": "Denotes the type of field used for user input. Options: string, number, datetime, text, singlevaluelist, multivaluelist", "bullets": [
"string: A string of characters without line breaks. Represented in an HTML from using an <input> tag",
"number: A numeric value. Represented in an HTML from using an <input> tag",
"datetime: The input generated must be able to transform into a valid ISO 8601 date. Represented in an HTML from using <input> tags",
"text: A string of characters that may contain line breaks. Represented in an HTML from using an <textarea> tag",
"singlevaluelist: A set of predefined values (specified in this response) where only one value may be selected. Represented in an HTML from using the <select> and <option> tags",
"multivaluelist: A set of predefined values (specified in this response) where several values may be selected. Represented in an HTML from using the <select multiple=\"multiple\"> and <option> tags"
]},
{"name": "required", "description": "Setting true means that the value is required to submit service request. Options: true, false."},
{"name": "datatype_description", "description": "A description of the datatype which helps the user provide their input."},
{"name": "order", "description": "The sort order that the attributes will be presented to the user. 1 is shown first. Options: Any positive integer not used for other attributes in the same service_code."},
{"name": "description", "description": "A description of the attribute field with instructions for the user to find and identify the requested information."},
{"name": "values", "description": "A container for a list of predefined options for singlevaluelist or multivaluelist. Required if datatype is set to singlevaluelist or multivaluelist."},
{"name": "value", "description": "A container for a predefined option (key and name) for singlevaluelist or multivaluelist."},
{"name": "key", "description": "The unique identifier associated with an option for singlevaluelist or multivaluelist. This is analogous to the value attribute in an html option tag."},
{"name": "name", "description": "The human readable title of an option for singlevaluelist or multivaluelist. This is analogous to the innerhtml text node of an html option tag."}
],
"possible_errors": [
{"status_code": "404", "description": "service_code or jurisdiction_id provided were not found (specify in error response)."},
{"status_code": "400", "description": "service_code or jurisdiction_id was not provided (specify in error response)."},
{"status_code": "400", "description": "General service error (Anything that fails during service list processing. The client will need to notify us)."}
],
"example" : "file://./api-methods-examples/open311.services.getInfo.json"
},
"open311.statuses.getList": {
"description": "Return a list of valid statuses for incidents. The types of statuses and their meaning are left to the discretion of individual cities. **NOT represented** in GeoReport v2",
"enabled": 1,
"documented": 1,
"paginated": 1,
"method": "GET",
"slug": "{foo}",
"requires_auth": 0,
"example" : "file://./api-methods-examples/open311.incidents.getStatuses.json"
},
"open311.incidents.report": {
"description": "Create service requests. Corresponds to [POST Service Request](http://wiki.open311.org/GeoReport_v2#POST_Service_Request) in GeoReport v2",
"enabled": 1,
"documented": 1,
"method": "POST",
"slug" : "requests.{format}",
"requires_auth": 1,
"parameters": [
{ "name": "jurisdiction_id", "description": "A valid jurisdiction as defined by the city operating the Open311API", "required": 1 },
{ "name": "service_code", "description": "Obtained from open311.services.getInfo", "required": 1 },
{ "name": "location", "description": "Either lat & long or address_string or address_id must be submitted", "required": 1 },
{ "name": "attribute", "description": "An array of key/value responses based on Service Definitions. This takes the form of attribute[code]=value where multiple code/value pairs can be specified as well as multiple values for the same code in the case of a multivaluelist datatype (attribute[code1][]=value1&attribute[code1][]=value2&attribute[code1][]=value3) - see example. only required if the service_code requires a service definition with required fields.", "required": 0},
{"name": "lat", "description": "Latitude using the (WGS84) projection.", "required": 0},
{"name": "long", "description": "Longitude using the (WGS84) projection.", "required": 0},
{"name": "address_string", "description": "Human entered address or description of location. This should be written from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code. This is required if no lat/lon is provided.", "required": 0},
{"name": "address_id", "description": "The internal address ID used by a jurisdictions master address repository or other addressing system.", "required": 0},
{"name": "email", "description": "The email address of the person submitting the request.", "required": 0 },
{"name": "device_id", "description": "The unique device ID of the device submitting the request. This is usually only used for mobile devices. For example, Android devices use TelephonyManager.getDeviceId() and iPhone's use [UIDevice currentDevice].uniqueIdentifier", "required": 0},
{"name": "account_id", "description": "The unique ID for the user account of the person submitting the request.", "required": 0},
{"name": "first_name", "description": "The first name of the person submitting the request.", "required": 0},
{"name": "last_name", "description": "The family name of the person submitting the request.", "required": 0},
{"name": "phone", "description": "The phone number of the person submitting the request.", "required": 0},
{"name": "description", "description": "A full description of the request or report being submitted. This may contain line breaks, but not html or code. Otherwise, this is free form text limited to 4,000 characters.", "required": 0},
{"name": "media_url", "description": "A URL to media associated with the request, eg an image. A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.", "required": 0}
],
"response": [
{"name": "service_requests", "description": "Root element."},
{"name": "request", "description": "Container for service_request_id, token, service_notice, account_id."},
{"name": "service_request_id", "description": "The unique ID of the service request created. This will not be returned if token is returned."},
{"name": "token", "description": "If returned, use this to call GET request_id from a token This will not be returned if service_request_id is returned."},
{"name": "service_notice", "description": "Information about the action expected to fulfill the request or otherwise address the information reported. (may not be returned)."},
{"name": "account_id", "description": "The unique ID for the user account of the person submitting the request. (may not be returned)."}
],
"possible_errors": [
{"status_code": "404", "description": "service_code or jurisdiction_id was not found (specified in error response)."},
{"status_code": "400", "description": "service_code or jurisdiction_id was not provided (specified in error response)."},
{"status_code": "400", "description": "General Service Error (Any failure during create request processing, eg CRM is down. Client will need to notify us)."}
],
"notes": [
"All dates should be passed in using the [W3C DateTime format](http://www.w3.org/TR/NOTE-datetime) format.",
"All geographic data is expected to be using the unprojected [WGS84](http://spatialreference.org/ref/epsg/4326/) datum (read: plain old latitudes and longitudes)."
],
"example" : "file://./api-methods-examples/open311.incidents.report.json"
},
"open311.incidents.getInfo": {
"description": "Corresponds to [GET Service Requests](http://wiki.open311.org/GeoReport_v2#GET_Service_Requests) in GeoReport v2",
"enabled": 1,
"documented": 1,
"requires_auth": 0,
"method": "GET",
"slug" : "requests/{id}.{format}",
"parameters": [
{ "name": "incident_id", "description": "The unique ID of the incident to get information about.", "required": 1 }
],
"notes": [
"TODO: port documentation from GeoReport v2"
],
"example" : "file://./api-methods-examples/open311.incidents.getInfo"
},
"open311.incidents.getIdFromToken": {
"description": "Corresponds to [GET request_id from a token](http://wiki.open311.org/GeoReport_v2#GET_request_id_from_a_token) in GeoReport v2",
"enabled": 1,
"documented": 1,
"requires_auth": 0,
"method": "GET",
"slug" : "tokens/{token_id}.{format}",
"parameters": [
{ "name": "", "description": "", "required": 1 }
],
"notes": [
"TODO: port documentation from GeoReport v2",
"(seems like this could/should be rolled in to incidents.getInfo, w/ token as an optional parameter) --NG"
],
"example" : "file://./api-methods-examples/open311.incidents.getIdFromToken"
},
"open311.incidents.search": {
"description": "Returns a list of incidents matching a search criteria as defined by the API request. Corresponds to [GET Service Requests](http://wiki.open311.org/GeoReport_v2#GET_Service_Requests) in GeoReport v2",
"enabled": 1,
"documented": 1,
"paginated": 1,
"method": "GET",
"slug" : "requests.{format}",
"requires_auth": 0,
"parameters": [
{ "name": "", "description": "", "required": 0 }
],
"notes": [
"TO DO: port from GeoReport v2",
"GeoReport v2 does offer some of the functionality described in open311-simple.incidents.search, with the exception of 'where'"
],
"example": "file://./api-methods-examples/open311.incidents.search.json"
},
"open311.where.getList": {
"description": "Returns a list of geographic prefixes that may be used to query for incident reports using the 'open311.incidents.search' API method. **NOT represented** in GeoReport v2",
"enabled": 1,
"documented": 1,
"requires_auth": 0,
"paginated": 1,
"method": "GET",
"slug" : "{foo}",
"example" : "file://./api-methods-examples/open311.where.getList.json"
}
}
}