Skip to content

Commit 3c78031

Browse files
tomschenkjrtomschenkjr
authored
Merge pull request #10 from Chicago/dev
v1.0.2
2 parents 3c91c9e + 707480d commit 3c78031

File tree

6 files changed

+89
-79
lines changed

6 files changed

+89
-79
lines changed

‎docs/index.md

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,18 @@ Visit the above URL to request an API key from the test Open311 system. Your req
3333

3434
Production API keys may only be requested after successfully testing with a test API key. The API Key application you submit will need to be reviewed and approved by City of Chicago Staff to ensure compliance with the [Terms of Service](tos/).
3535

36-
## Service Request Meta Data
36+
## Endpoints
37+
38+
Below are the API endpoints that can be used to access the Open311 API.
39+
40+
| Staging | API Endpoint |
41+
|------------|-------------------------------------------------|
42+
| Test | http://test311api.cityofchicago.org/open311/v2/ |
43+
| Production | http://311api.cityofchicago.org/open311/v2/ |
44+
45+
The API has two categories of information: metadata about the types of service requests and interacting with service requests.
46+
47+
### Service Request Metadata
3748

3849
Methods that expose data related to how Service Requests will be exposed in the API.
3950

@@ -42,7 +53,7 @@ Methods that expose data related to how Service Requests will be exposed in the
4253
| GET services.:format | **Service List**: Provide a list of acceptable 311 service request types and their associated service codes. |
4354
| GET services/:service_code.:format | **Service Definition**: Define attributes associated with a service code. |
4455

45-
## Service Request
56+
### Service Request
4657

4758
Methods that allow for reading and writing of Service Requests to the City database.
4859

‎docs/post_service_request.md

Lines changed: 23 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,36 @@
1-
# POST requests.:format
1+
# Create a New Service Request
22

33
Create a service request in the City's database. Once a service request has been processed by the City (this can take an undetermined amount of time), you should be able to call the GET service_request_id method (tokens/:token_id.:format) to get back the service_request_id for a SR. Therefore, it is nesseary to poll the GET service_request_id method until an SR id is returned. Because the Chicago endpoint may return service requests with no token and no service_reqeust_id in calls to GET service_requests while recently submitted SRs are still being processed by City systems, users of the GET service_requests method should ignore any service requests returned by the API until they have a service_request_id.
44

5-
| Resource Information | |
6-
|----------------------|----------------------|
7-
| Method Name | Post Service Request |
8-
| Requires API key? | No |
9-
| Response Formats | JSON, XML |
10-
| HTTP Methods | GET |
11-
| JSONP | POST |
5+
| Resource Information | |
6+
|----------------------|-----------------------|
7+
| Method | POST requests.:format |
8+
| Requires API key? | Yes |
9+
| Response Formats | JSON, XML |
10+
| HTTP Methods | POST |
1211

1312
## Arguments
1413

15-
| Argument | Required | Description |
16-
|--------------------|----------|-----------------------------------------------------------|
17-
| `jurisdiction_id` | optional | This is currently optional on Chicago's Open311 endpoint. |
18-
| `service_code` | required | This is obtained from GET Service List method. |
14+
| Argument | Required | Description |
15+
|--------------------|----------|------------------------------------------------------------------------------------------------------------------------|
16+
| `jurisdiction_id` | optional | Optional, but if it is included, it must be set to `cityofchicago.org` |
17+
| `service_code` | required | This is obtained from GET Service List method. |
1918
| `attribute` | required | 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. - This is only required if the service_code requires a service definition with required fields. |
2019
| `lat` | required | lat & long both need to be sent even though they are sent as two separate parameters. lat & long are required. |
2120
| `long` | required | lat & long both need to be sent even though they are sent as two separate parameters. lat & long are required. |
22-
| `address_string` | required | 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. |
23-
| `address_id` | optional | The internal address ID used by a jurisdiction's master address repository or other addressing system. |
24-
| `email` | optional | The email address of the person submitting the request. |
25-
| `device_id` | optional | The unique device ID of the device submitting the request. This is usually only used for mobile devices. |
26-
| `account_id` | optional | The unique ID for the user account of the person submitting the request. |
27-
| `first_name` | optional | The given name of the person submitting the request. |
28-
| `last_name` | optional | The family name of the person submitting the request. |
29-
| `phone` | optional | The phone number of the person submitting the request. |
30-
| `description` | optional | A full description of the request or report being submitted. |
31-
| `media_url` | optional | A URL to media associated with the request, eg an image. |
21+
| `address_string` | required | 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. |
22+
| `address_id` | optional | The internal address ID used by a jurisdiction's master address repository or other addressing system. |
23+
| `email` | optional | The email address of the person submitting the request. |
24+
| `device_id` | optional | The unique device ID of the device submitting the request. This is usually only used for mobile devices. |
25+
| `account_id` | optional | The unique ID for the user account of the person submitting the request. |
26+
| `first_name` | optional | The given name of the person submitting the request. |
27+
| `last_name` | optional | The family name of the person submitting the request. |
28+
| `phone` | optional | The phone number of the person submitting the request. |
29+
| `description` | optional | A full description of the request or report being submitted. |
30+
| `media_url` | optional | A URL to media associated with the request, eg an image. |
3231

3332
## Response Parameters
3433

35-
| Argument | Description |
36-
|----------|------------------------------------------------------------------------|
34+
| Argument | Description |
35+
|----------|------------------------------------------------------------------------------------------------------------------------------------------------------|
3736
| `token` | If returned, use this to call GET service_request_id from a token to discover what the service_request_id is after it is created by the City system. |

‎docs/service_definition.md

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,33 @@
1-
# GET services/:service_code.:format
1+
# Retrieve the Definitions for a Service Request
22

33
Define attributes associated with a service code.
44

5-
| Resource Information | |
6-
|----------------------|-----|
7-
| Method Name | Service Definition |
8-
| Requires API key? | No |
9-
| Response Formats | JSON, XML |
10-
| HTTP Methods | GET |
11-
| JSONP | callback=? |
5+
| Resource Information | |
6+
|----------------------|------------------------------------|
7+
| Method | GET services/:service_code.:format |
8+
| Requires API key? | No |
9+
| Response Formats | JSON, XML |
10+
| HTTP Methods | GET |
11+
| JSONP | callback=? |
1212

1313
## Arguments
1414

15-
| Argument | Required | Description |
16-
|-------------------|----------|-----------------------------------------------------------|
17-
| `jurisdiction_id` | optional | This is currently optional on Chicago's Open311 endpoint. |
15+
| Argument | Required | Description |
16+
|-------------------|----------|-------------------------------------------------------------------------------------------------|
17+
| `jurisdiction_id` | optional | Optional, but if it is included, it must be set to `cityofchicago.org` |
1818
| `service_code` | required | The service_code is specified in the main URL path rather than an added query string parameter. |
1919

2020
## Response Parameters
2121

2222
| Argument | Description |
2323
|----------------|------------------------------------------------------------------------|
24-
| `service_code` | Returns the service_code associated with the definition, the same one submitted for this call. |
25-
| `variable` | 'true' denotes that user input is needed. 'false' means the attribute is only used to present information to the user within the description field. |
26-
| `code` | A unique identifier for the attribute. |
27-
| `datatype` | Denotes the type of field used for user input. |
28-
| `required` | 'true' means that the value is required to submit service request. 'false' means that the value not required. |
24+
| `service_code` | Returns the service_code associated with the definition, the same one submitted for this call. |
25+
| `variable` | 'true' denotes that user input is needed. 'false' means the attribute is only used to present information to the user within the description field. |
26+
| `code` | A unique identifier for the attribute. |
27+
| `datatype` | Denotes the type of field used for user input. |
28+
| `required` | 'true' means that the value is required to submit service request. 'false' means that the value not required. |
2929
| `datatype_description` | A description of the datatype which helps the user provide their input. |
30-
| `order` | The sort order that the attributes will be presented to the user. 1 is shown first in the list. |
31-
| `description` | A description of the attribute field with instructions for the user to find and identify the requested information. |
32-
| `key` | The unique identifier associated with an option for singlevaluelist or multivaluelist. This is analogous to the value attribute in an html option tag. |
33-
| `name` | The human readable title of an option for singlevaluelist or multivaluelist. This is analogous to the innerhtml text node of an html option tag. |
30+
| `order` | The sort order that the attributes will be presented to the user. 1 is shown first in the list. |
31+
| `description` | A description of the attribute field with instructions for the user to find and identify the requested information. |
32+
| `key` | The unique identifier associated with an option for singlevaluelist or multivaluelist. This is analogous to the value attribute in an html option tag.|
33+
| `name` | The human readable title of an option for singlevaluelist or multivaluelist. This is analogous to the innerhtml text node of an html option tag. |

‎docs/service_list.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# GET services.:format
1+
# List Available Open311 Services
22

33
Provide a list of acceptable 311 service request types and their associated service codes.
44

5-
| Resource Information | |
6-
|----------------------|-----|
7-
| Method Name | Service List |
8-
| Requires API key? | No |
9-
| Response Formats | JSON, XML |
10-
| HTTP Methods | GET |
11-
| JSONP | callback=? |
5+
| Resource Information | |
6+
|----------------------|----------------------|
7+
| Method | GET services.:format |
8+
| Requires API key? | No |
9+
| Response Formats | JSON, XML |
10+
| HTTP Methods | GET |
11+
| JSONP | callback=? |
1212

1313
## Arguments
1414

15-
| Argument | Required | Description |
16-
|-------------------|----------|-----------------------------------------------------------|
17-
| `jurisdiction_id` | optional | This is currently optional on Chicago's Open311 endpoint. |
15+
| Argument | Required | Description |
16+
|-------------------|----------|------------------------------------------------------------------------|
17+
| `jurisdiction_id` | optional | Optional, but if it is included, it must be set to `cityofchicago.org` |
1818

1919
## Response Parameters
2020

‎docs/service_request.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# GET services/:service_code.:format
1+
# Retrieving an Individual Request
22

33
Define attributes associated with a service code.
44

5-
| Resource Information | |
6-
|----------------------|-----|
7-
| Method Name | Service Definition |
8-
| Requires API key? | No |
9-
| Response Formats | JSON, XML |
10-
| HTTP Methods | GET |
11-
| JSONP | callback=? |
5+
| Resource Information | |
6+
|----------------------|------------------------------------------|
7+
| Method | GET requests/:service_request_id.:format |
8+
| Requires API key? | No |
9+
| Response Formats | JSON, XML |
10+
| HTTP Methods | GET |
11+
| JSONP | callback=? |
1212

1313
## Arguments
1414

15-
| Argument | Required | Description |
16-
|-------------------|----------|-----------------------------------------------------------|
17-
| `jurisdiction_id` | optional | This is currently optional on Chicago's Open311 endpoint. |
15+
| Argument | Required | Description |
16+
|-------------------|----------|-------------------------------------------------------------------------------------------------|
17+
| `jurisdiction_id` | optional | Optional, but if it is included, it must be set to `cityofchicago.org` |
1818
| `service_code` | required | The service_code is specified in the main URL path rather than an added query string parameter. |
1919
| `extensions` | optional | The Chicago Open311 endpoint provides supplemental details about Service Requests that are in addition to the ones described in the standard specification. These data are nested in the 'extended_attributes' field in the Service Request response. In order to retrieve the new supplemental details, add the query parameter “extensions=true” to any Open 311 api request. |
2020

‎docs/service_requests.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# GET requests.:format
1+
# Query the Current Status of Multiple Requests
22

33
Query the current status of multiple requests. Because the Chicago endpoint may return service requests with no token and no service_reqeust_id in calls to GET service_requests while recently submitted SRs are still being processed by City systems, users of the GET service_requests method should ignore any service requests returned by the API until they have a service_request_id.
44

5-
| Resource Information | |
6-
|----------------------|-----|
7-
| Method Name | Service Definition |
8-
| Requires API key? | No |
9-
| Response Formats | JSON, XML |
10-
| HTTP Methods | GET |
11-
| JSONP | callback=? |
5+
| Resource Information | |
6+
|----------------------|----------------------|
7+
| Method | GET requests.:format |
8+
| Requires API key? | No |
9+
| Response Formats | JSON, XML |
10+
| HTTP Methods | GET |
11+
| JSONP | callback=? |
1212

1313
## Arguments
1414

1515
| Argument | Required | | Description |
1616
|----------------------|----------|--------------|----------------------------------------------------------|
17-
| `jurisdiction_id` | optional | | This is currently optional on Chicago's Open311 endpoint. |
17+
| `jurisdiction_id` | optional | | Optional, but if it is included, it must be set to `cityofchicago.org` |
1818
| `service_request_id` | optional | | To call multiple Service Requests at once, multiple service_request_id can be declared; comma delimited. |
1919
| `service_code` | optional | | Specify the service type by calling the unique ID(s) of the service_codes you wish to query. This defaults to all service codes when not declared; can be declared multiple times, comma delimited (no spaces). |
2020
| `start_date` | optional | | 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. Must use w3 format, eg 2010-01-01T00:00:00Z. |
@@ -34,13 +34,13 @@ Query the current status of multiple requests. Because the Chicago endpoint may
3434
|----------------|--------------|------------------------------------------------------------------------|
3535
| `service_request_id` | | The unique ID of the service request created. |
3636
| `service_code` | | Returns the service_code associated with the definition, the same one submitted for this call. |
37-
| `status` | The current status of the service request. |
37+
| `status` | | The current status of the service request. |
3838
| `status_notes` | |Explanation of why status was changed to current state or more details on current status than conveyed with status alone. |
3939
| `service_name` | | The human readable name of the service request type. |
4040
| `service_code` | | The unique identifier for the service request type. |
4141
| `description` | | A full description of the request or report submitted. |
4242
| `agency_responsible` | | The agency responsible for fulfilling or otherwise addressing the service request. | |
43-
| `service_notice` | Information about the action expected to fulfill the request or otherwise address the information reported. |
43+
| `service_notice` | | Information about the action expected to fulfill the request or otherwise address the information reported. |
4444
| `requested_datetime` | | The date and time when the service request was made. |
4545
| `updated_datetime` | Non-standard | TBD: The Chicago implementation uses updated_datetime in a manner that differs from Open311. Documentation is still being compiled. |
4646
| `expected_datetime` | | 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. |

0 commit comments

Comments
 (0)