-
Notifications
You must be signed in to change notification settings - Fork 8
/
open311-georeporter.yaml
560 lines (537 loc) · 20.7 KB
/
open311-georeporter.yaml
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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
swagger: '2.0'
info:
version: "2.0"
title: Open311 GeoReport API
description: Open311 allows you to get/post civic information of cities via a unified interface. The GeoReport part allows you to submit and view issues at the public local space
termsOfService: (depends on server instance for example NYC http://dev.cityofchicago.org/docs/api/tos)
contact:
name: Open311 community
url: http://wiki.open311.org/GeoReport_v2/
email: discuss@lists.open311.org
license:
name: CC BY 3.0
url: http://creativecommons.org/licenses/by/3.0/
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
- text/xml
securityDefinitions:
api_key:
type: apiKey
name: api_key
in: query
definitions:
Service:
description: A single service (type) offered via Open311
required:
- service_code
- service_name
- type
properties:
service_code:
type: string
format: uid
description: unique identifier for the service request type
service_name:
type: string
description: human readable name of the service request type
description:
type: string
metadata:
type: boolean
description: Are there additional form fields for this service type? If true use GET service definition for that one
type:
type: string
description: Possible values realtime, batch, blackbox
enum:
- realtime
- batch
- blackbox
keywords:
type: array
items:
type: string
description: list of keywords or tags seperated by comma
group:
type: string
description: Category or group to cluster different request types e.g. “sanitation”
ServiceDefinition:
description: Attributes associated with a service code. These attributes can be unique to the city/jurisdiction.
required:
- service_code
- attributes #todo How to make sure it's not empty?
properties:
service_code:
type: string
format: uid
description: unique identifier for the service request type
attributes:
type: array
items:
$ref: '#/definitions/ServiceAttribute'
ServiceAttribute:
description: A single attribute extension for a service
required:
- variable
- code
- datatype
- required
properties:
variable:
type: boolean
description: If only used to present information to the user within the description field or if that user input is needed
code:
type: string
format: uid
description: Unique identifier for the attribute #<?>why and limitations
datatype:
type: string
enum:
- string
- number
- datetime
- text
- singlevaluelist
- multivaluelist
description: Type of field used for user input. According widgets will be picked for user inputs
required:
type: boolean
description: If attributes value required to submit service request
datatype_description:
type: string
description: Description of the datatype which helps the user provide their input
order:
type: integer
format: uint
description: Sort order that the attributes will be presented to the user. 1 is shown first in the list.
description:
type: string
description: description of the attribute field with instructions for the user to find and identify the requested information
values:
type: array
items:
$ref: '#/definitions/AttributeValue'
AttributeValue:
description: Possible value for ServiceAttribute that defines lists
required:
- key
- name
properties:
key:
type: string
format: uid
description: Unique identifier associated with an option for singlevaluelist or multivaluelist (analogous to the value attribute in an html option tag).
name:
type: string
description: Human readable title of an option for singlevaluelist or multivaluelist (analogous to the innerhtml text node of an html option tag).
Request:
description: Issues that have been reported as service requests. Location is submitted via lat/long or address or address_id
required:
- service_request_id
- status
- service_code
- requested_datetime
properties:
service_request_id:
type: string
format: uid
description: Unique ID of the service request created.
status:
type: string
enum:
- open
- closed
description: Current status of the service request.
status_notes:
type: string
description: Explanation of why status was changed to current state or more details on current status than conveyed with status alone.
service_name: #todo Generalization and linking
type: string
description: The human readable name of the service request type.
service_code:
type: string
format: uid
description: The unique identifier for the service request type
description:
type: string
description: A full description of the request or report submitted.
agency_responsible:
type: string
description: Agency responsible for fulfilling or otherwise addressing the service request.
service_notice:
type: string
description: Information about the action expected to fulfill the request or otherwise address the information reported.
requested_datetime:
type: string
format: date-time
description: Date and time when the service request was made.
updated_datetime:
type: string
format: date-time
description: Date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed.
expected_datetime:
type: string
format: date-time
description: The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement.
address:
type: string
description: Human readable address or description of location. This should be provided from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code.
address_id:
#<?> optional or required?
type: string
description: Internal address ID used by a jurisdictions master address repository or other addressing system.
zipcode:
#<?> Already mentioned in address descr?
type: string
description: postal code for the location of the service request. (Redundant and field might be removed as it should be part of adress string)
lat: #Generalisation with
type: number
format: double
description: latitude using the (WGS84) projection.
long:
type: number
format: double
description: longitude using the (WGS84) projection.
media_url:
type: string
format: uri
#<?> so we write we don't know how to submit
description: 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 much like Twitter.com does. 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.
RequestResponse:
description: Details for tracking an created service request
properties: #todo service_requests array?
service_request_id:
type: string
format: uid
description: Unique ID of the service request created.
token:
type: string
format: uid
description: Use this to call GET service_request_id from a token.
service_notice:
type: string
description: Information about the action expected to fulfill the request or otherwise address the information reported.
account_id:
type: string
format: uid
description: Unique ID for the user account of the person submitting the request.
TokenResponse:
description: Resolves temporary token to ID of the request
properties: #todo service_requests array?
service_request_id: #todo general request ID concept
type: string
format: uid
description: Unique ID of the service request created.
token:
type: string
format: uid
description: Use this to call GET service_request_id
parameters:
jurisdiction_id:
name: jurisdiction_id
in: query
description: <?>
required: true
type: string
format: uid
response_format:
name: response_format
in: path
required: true
type: string
format: uid
paths:
#todo extract service_code?
#todo extract an error model for responses?
/requests.{response_format}:
get:
summary: requests
description: Query the current status of multiple requests.
parameters:
- $ref: '#/parameters/response_format'
- $ref: '#/parameters/jurisdiction_id'
- name: service_request_id
in: query
description: To call multiple Service Requests at once, multiple service_request_id can be declared; comma delimited.This overrides all other arguments.
required: false
type: string
format: uid
- name: service_code
in: query
description: Specify the service type by calling the unique ID of the service_code.
required: false
type: string
- name: start_date
in: query
description: Earliest datetime to include in search. When provided with end_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days.
required: false
type: string
format: date-time
- name: end_date
in: query
description: Latest datetime to include in search. When provided with start_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days.
required: false
type: string
format: date-time
- name: status
in: query
description: Allows one to search for requests which have a specific status. This defaults to all statuses; can be declared multiple times, comma delimited.
required: false
type: string
enum:
- open
- closed
responses:
200:
description: List of matching requests (Default query limit is a span of 90 days or first 1000 requests returned, whichever is smallest).
schema:
type: array
items:
$ref: '#/definitions/Request'
examples:
application/xml:
request:
service_request_id: 638344
status: closed
status_notes: Duplicate request.
service_name: Sidewalk and Curb Issues
service_code: 006
description:
agency_responsible:
service_notice:
requested_datetime: 2010-04-14T06:37:38-08:00
updated_datetime: 2010-04-14T06:37:38-08:00
expected_datetime: 2010-04-15T06:37:38-08:00
address: 8TH AVE and JUDAH ST
address_id: 545483
zipcode: 94122
lat: 37.762221815
long: -122.4651145
media_url: http://city.gov.s3.amazonaws.com/requests/media/638344.jpg
application/json:
request:
service_request_id: 638349
status: open
status_notes:
service_name: Sidewalk and Curb Issues
service_code: 006
description:
agency_responsible:
service_notice:
requested_datetime: 2010-04-19T06:37:38-08:00
updated_datetime: 2010-04-19T06:37:38-08:00
expected_datetime: 2010-04-19T06:37:38-08:00
address: 8TH AVE and JUDAH ST
address_id: 545483
zipcode: 94122
lat: 37.762221815
long: -122.4651145
media_url: http://city.gov.s3.amazonaws.com/requests/media/638344.jpg
400:
description: jurisdiction_id was not provided (specified in error response) or General Service error (Any failure during service query processing. Client will have to notify us)
401:
description: jurisdiction_id not found (specified in error response)
post:
summary: Create service request
description: Submit a new request for with specific details of a single service. Must provide a location via lat/long or address_string or address_id
security:
- api_key: []
parameters:
- $ref: '#/parameters/response_format'
- $ref: '#/parameters/jurisdiction_id'
- name: service_code
in: query
description: <?>
required: true
type: string
format: uid
- name: lat
in: query
description: WGS-84 latitude
required: false
type: number
format: double
- name: long
in: query
description: WGS-84 longitude
required: false
type: number
format: double
- name: address_string #todo any formal definition?
in: query
required: false
type: string
- name: address_id #todo any formal definition?
in: query
required: false
type: string
format: uid
- name: attribute
in: query
description: array of key/value responses based on Service Definitions.
required: false
type: array
items:
type: string #todo $ref: '#/definitions/ServiceAttribute'
collectionFormat: multi
responses:
200:
description: success returns an tracking-id
schema:
type: array
items:
$ref: "#/definitions/RequestResponse"
examples:
application/xml:
service_requests:
service_request_id: 293944
service_notice: 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
account_id:
/request/{service_request_id}.{response_format}:
get:
summary: current status
description: Query the current status of an individual request
parameters:
- $ref: '#/parameters/response_format'
- $ref: '#/parameters/jurisdiction_id'
- name: service_request_id
in: path
description: Is specified in the main URL path rather than an added query string parameter.
required: true
type: string
format: uid
responses:
200:
description: success returns request details
schema:
$ref: "#/definitions/Request"
examples:
application/xml:
request:
service_request_id: 638344
status: closed
status_notes: Duplicate request.
service_name: Sidewalk and Curb Issues
service_code: 006
description:
agency_responsible:
service_notice:
requested_datetime: 2010-04-14T06:37:38-08:00
updated_datetime: 2010-04-14T06:37:38-08:00
expected_datetime: 2010-04-15T06:37:38-08:00
address: 8TH AVE and JUDAH ST
address_id: 545483
zipcode: 94122
lat: 37.762221815
long: -122.4651145
media_url: http://city.gov.s3.amazonaws.com/requests/media/638344.jpg
/services.{response_format}:
get:
summary: service types
description: List acceptable service request types and their associated service codes. These request types can be unique to the city/jurisdiction.
parameters:
- $ref: '#/parameters/jurisdiction_id'
- $ref: '#/parameters/response_format'
responses:
200:
description: ok
schema:
type: array
items:
$ref: '#/definitions/Service'
examples:
application/xml:
services:
- service:
service_code: 001
service_name: Cans left out 24x7
description: Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited.
metadata: true
type: realtime
keywords: lorem, ipsum, dolor
group: sanitation
- service:
service_code: 002
service_name: Construction plate shifted
description: Metal construction plate covering the street or sidewalk has been moved.
metadata: true
type: realtime
keywords: lorem, ipsum, dolor
group: street
- service:
service_code: 003
service_name: Curb or curb ramp defect
description: Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb.
metadata: true
type: realtime
keywords: lorem, ipsum, dolor
group: street
400:
description: The URL request is invalid or service is not running or reachable. Client should notify us after checking URL
404:
description: jurisdiction_id provided was not found (specify in error response).
/services/{service_code}.{response_format}:
get:
summary: (extended) definition of a service type
description: Define attributes associated with a service code. These attributes can be unique to the city/jurisdiction.
parameters:
- $ref: '#/parameters/jurisdiction_id'
- $ref: '#/parameters/response_format'
- name: service_code
in: path
required: true
type: string
format: uid
responses:
200:
description: returns ServiceDefinition for the Service
schema:
$ref: '#/definitions/ServiceDefinition'
examples:
application/xml:
service_definition:
service_code: DMV66
attributes:
attribute:
variable: true
code: WHISHETN
datatype: singlevaluelist
required: true
datatype_description:
order: 1
description: What is the ticket/tag/DL number?
values:
- value:
key: 123
name: Ford
- value:
key: 124
name: Chrysler
400:
description: service_code or jurisdiction_id provided were not found (specify in erraddor response)
404:
description: service_code or jurisdiction_id provided were not found (specify in error response)
/tokens/{token_id}.{response_format}:
get:
summary: Id of service_request via token
description: Get the service_request_id from a temporary token. This is unnecessary if the response from creating a service request does not contain a token.
parameters:
- $ref: '#/parameters/jurisdiction_id'
- $ref: '#/parameters/response_format'
- name: token_id #todo link with POST Service req
in: path
required: true
type: string
format: uid
responses:
200:
description: returns tuple request ID, token
schema:
$ref: '#/definitions/TokenResponse'
examples:
application/xml:
service_requests:
request:
service_request_id: 638344
token: 12345