Skip to content

Commit 4249be3

Browse files
tomschenkjrtomschenkjr
authored
Merge pull request #27 from Chicago/dev
v1.0.0-rc.1
2 parents ec6046a + 19d5358 commit 4249be3

5 files changed

Lines changed: 227 additions & 204 deletions

File tree

‎docs/api.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# API Documentation
2+
3+
## Submitting Patient Record
4+
5+
### Authentication
6+
7+
Submitting patient records to Lead Safe requires client credentials to retrieve a token, which is required for all API calls. City of Chicago will issue a client ID and a client secret ID which will be used to obtain a token.
8+
9+
10+
```bash
11+
GET --user CLIENT_ID:CLIENT_SECRET --data "grant_type=client_credentials" <url>/oauth/token
12+
```
13+
14+
Successful requests for a token will return a JSON file similar to this:
15+
16+
```json
17+
{"access_token":"TOKEN","token_type":"bearer","expires_in":3600}
18+
```
19+
20+
Tokens are set to expire every 3,600 seconds (1 hour) and a new token will need to be obtained.
21+
22+
To upload a patient record, the POST command must include a header called `Authorization: Bearer` followed by the TOKEN obtained in the previous steps.
23+
24+
An upload would look like:
25+
26+
```bash
27+
POST --header "Content-Type:application/json" --header "Authorization: Bearer TOKEN" FILE.JSON <url>/upload/insert/
28+
```
29+
30+
The format for `FILE.JSON` is described in the next section.
31+
32+
### Schema
33+
34+
Submit a patient record and retrieve the estimated risk of having elevated blood-lead levels.
35+
36+
37+
| Field | Format | Constraints | Notes |
38+
|-----------------|----------|------------------------------------|-------------------------------------------------------------------------------------------------------------------|
39+
| timestamp | TimeDate | yyyy-mm-dd hh:mm:ss.sss-hh:mm | Current timestamp (RFC 3339 compliant date) |
40+
| network_id | Text | <N/A\> | The parent entity of the submitting organization |
41+
| clinic_id | Text | <N/A\> | Organization ID |
42+
| location_id | Text | <N/A\> | Specific Location Abbreviation in Centricity |
43+
| patient_id | Text | <N/A\> | AlphaNumeric patient identifier |
44+
| address1 | Text | <N/A\> | Patient home address (street number, street direction, street name, street type) |
45+
| address2 | Text | <N/A\> | Patient home address (additional information, e.g. apartment number) |
46+
| city | Text | <N/A\> | Patient home address city |
47+
| state | Text | <N/A\> | Patient home address state |
48+
| zip | Text | <N/A\> | Patient home address zip code |
49+
| date_of_birth | Date | yyyy-mm-dd | Patient date of birth |
50+
| gender | Text | M/F/U | Patient gender |
51+
| race | Text | Code Values from Centricity | Standard ONC Race definitions <br /> <br /> **Code / description** <br /> 1002-5 / American Indian or Alaska Native <br /> 2028-9 / Asian <br /> 2054-5 / Black or African American <br /> 2076-8 / Native Hawaiian or Other Pacific Islander <br /> 2106-3 / White <br /> UNK / Unknown |
52+
| ethnicity | Text | Code Values from Centricity | Standard ONC Ethnicity definitions <br/> <br/> **Code / description** <br /> 2135-2 / Hispanic or Latino <br /> 2186-5 / Non-Hispanic or Latino <br /> UNK / Unknown |
53+
| VISIT ARRAY | | | _Optional_ May entirely omit the array if visit history does not exist or is unavailable. |
54+
| visit.visit_id | Numeric | 16 Digit GE ID | Unique GE ID for specific visit (DocumentID) |
55+
| visit.date | Date | yyyy-mm-dd hh:mm:ss.sss-hh:mm | Date of visit (RFC 3339 complient date) |
56+
| visit.location | Text | <N/A\> | Text Abbreviation for facility of visit location |
57+
| visit.provider | Text | <N/A\> | Full provider name, last name, or just NPI |
58+
| LAB ARRAY | | | _Optional_ May entirely omit the array if visit history does not exist or is unavailable. |
59+
| lab.lab_id | Numeric | 16 Digit GE ID | Unique GE ID for specific lab result (ObsID) |
60+
| lab.type | Text | "BLL" | Static BLL unless we identify additional labs to include |
61+
| lab.date | Date | yyyy-mm-dd | Date of lab results |
62+
| lab.sample_type | Text | V/C | "V" Venous <br /> "C" for Capillary |
63+
| lab.result | Text | <N/A\> | Several values are possible; integer, non-integer numeric, ranges indicated by alphanumeric text. |
64+
65+
```json
66+
{
67+
"timestamp": "2017-08-22 12:00:00.000-00:00",
68+
"network_id": "Alliance Health",
69+
"clinic_id": "EF",
70+
"location_id": "examp_loc",
71+
"patient_id": "9000",
72+
"address1": "333 S State St",
73+
"address2": "Ste 420",
74+
"city": "Chicago",
75+
"state": "IL",
76+
"zip": "60653",
77+
"date_of_birth": "2013-07-24",
78+
"gender": "F",
79+
"race": "2054-5",
80+
"ethnicity": "2186-5",
81+
"visit": [
82+
{"visit_id": 1234567891011121, "date": "2017-07-25 15:02:54.171-00:00", "location": "333 S State St", "provider": "John Doe"},
83+
{"visit_id": 1234567891011121, "date": "2017-07-25 15:02:54.171-00:00", "location": "333 S State St", "provider": "John Doe"},
84+
{"visit_id": 1234567891011121, "date": "2017-07-25 15:02:54.171-00:00", "location": "333 S State St", "provider": "John Doe"}
85+
],
86+
"lab": [
87+
{"lab_id": 1234567891011121, "type": "BLL", "date": "2016-07-29", "sample_type": "V", "result": "None Detected ug/dL"},
88+
{"lab_id": 1234567891011121, "type": "BLL", "date": "2015-08-21", "sample_type": "V", "result": "16.3"},
89+
{"lab_id": 1234567891011121, "type": "BLL", "date": "2015-02-27", "sample_type": "V", "result": "1"}]
90+
}
91+
```
92+
93+
### Response
94+
95+
#### Body
96+
97+
| Field | Format | Constraints | Notes/Questions |
98+
|------------------|----------|-------------------------------|--------------------------------------------------------------------------------------------|
99+
| version | Text | "0.3.0" | Follows Semantic Versioning 2.0.0 http://semver.org/spec/v2.0.0.html |
100+
| timestamp | TimeDate | yyyy-mm-dd hh:mm:ss.sss-hh:mm | Current Timestamp (RFC 3339 compliant date). |
101+
| network_id | Text | <N/A\> | Parent entity - same value as submitted to the API. |
102+
| clinic_id | Text | <N/A\> | Organization ID - same value as submitted to the API. |
103+
| location_id | Text | <N/A\> | Specific Location Abbreviation in Centricity - same value as submitted to the API. |
104+
| patient_id | Text | AlphaNumeric | Identifier for the patient - same value as submitted to the API. |
105+
| risk_score | Text | 9.99 | Currently expecting numeric, future may be phrased by stating an odds ratio with the risk score. |
106+
| risk_score_notes | Text | <N/A\> | Additional notes (referral, remediation funds, etc to be returned to provider ) |
107+
108+
```json
109+
{
110+
"version": "0.3.0",
111+
"timestamp": "2017-08-11 19:20:29.000-00:00",
112+
"network_id": "Alliance Health",
113+
"clinic_id": "EF",
114+
"location_id": "examp_loc",
115+
"patient_id": "9000",
116+
"risk_score": "0.309",
117+
"risk_score_notes": "Risk Score Notes"
118+
}
119+
```
120+
121+
#### Response Codes
122+
123+
The API will return codes to indicate whether the prediction encountered any errors. Often, error codes will be accompanied by a longer explanation of the error in addition to the brief explanations below.
124+
125+
| Status Class | Status Code | Status Message |
126+
|-----------------------------|:------------:|----------------------------------------------------------------------------------------------|
127+
| Success | 200 | No error. |
128+
| Missing data field | 400 | A required field was not included in the submission. |
129+
| Incorrect data type | 400 | A field contained an unexpected data type that does not match submission requirements. |
130+
| Incorrect date format | 400 | One of the date formats is incorrect. |
131+
| Invalid JSON | 400 | JSON structure was incomplete, contained unexpected characters, or was not properly closed. |
132+
| Invalid race/ethnicity code | 400 | Value used to encode race or ethnicity does not match an expected value. |
133+
| Unauthorized | 401 | Failed to provide authentication key or provided invalid key. |
134+
| Not Found | 404 | The URI requested is invalid or does not exist. |
135+
| Child over 1 years-old | 412 | The child is ineligible for Lead Safe. |
136+
| Address outside of Chicago | 412 | Address is outside of Chicago or address failed to be geocoded within Chicago. |
137+
138+
```json
139+
"errors":
140+
[
141+
{
142+
"message": "An error message which conveys details",
143+
"code": 400
144+
}
145+
]
146+
```
147+
148+
#### Header
149+
150+
| Field | Format | Constraints | Notes |
151+
|------------------|--------------|------------------|---------------------------------------------------------------------------------------------|
152+
| Date | Integer | <N/A\> | ID of the record submitted. |
153+
| Server | Text | "Apache" | The type of the server providing the results |
154+
| Content-Location | URL | <N/A\> | Permanent location to retrieve the results |
155+
| ETag | | <N/A\> | |
156+
| Content-Length | Integer | 225 | |
157+
| Content-Type | Text | application/json | Informs user that the content will be a JSON file |
158+
| Set-Cookie | Text | <N/A\> | |
159+
160+
```
161+
HTTP/1.1 200 OK
162+
Date: Tue, 22 Aug 2017 22:49:39 GMT
163+
Server: Apache
164+
Content-Location: https://webapps1int.cityofchicago.org/ords/cdph_lead_api/test_result/get/406
165+
ETag: "zi/wQ5GvoQFjvb4ej24v8f5PbHog14ZsjDSGJABXUxKxV3SxyOwBKrNJv7we9B5hnSs9WgeoA2h54/yVmIjcnA=="
166+
Content-Length: 225
167+
Content-Type: application/json
168+
Set-Cookie: BIGipServerwebapps1int.cityofchicago.org-443.app~webapps1int.cityofchicago.org-443_pool=339105802.47873.0000; Secure; HttpOnly; path=/; Httponly; Secure
169+
```
170+
171+
172+
## Retrieving Previous Predictions
173+
174+
When submitting a record for a prediction, a unique URL is given to the submission (not the individual) where the results can be retrieved in the future.
175+
176+
```bash
177+
GET <url>/get/{id}
178+
```
179+
180+
The response will be the [same as the original prediction](#body).
181+
182+
!!! note ""
183+
The prediction is only assigned when it is POST to the server. The score will only reflect the prediction given the data originally submitted and based on known information at that time. Retrieving old records will not update the prediction. To get a new prediction, submit a new record
184+
185+
186+
## Checking Status on All Submissions
187+
188+
Check the status on all submissions and whether results are available.
189+
190+
```bash
191+
GET <url>/get/
192+
```
193+
194+
### Response
195+
196+
| Field | Format | Constraints | Notes |
197+
|-------------|--------------|----------------|--------------------------------------------------------------------------------------------------|
198+
| id | Integer | <N/A\> | ID of the record submitted. |
199+
| processed | Text | "Y" or "N" | Whether the results are available. Results may be an error or blank if the record was incorrect. |
200+
201+
```json
202+
{"items":[
203+
{"id":133,"processed":"Y"},
204+
{"id":121,"processed":"Y"},
205+
{"id":120,"processed":"Y"},
206+
{"id":122,"processed":"Y"},
207+
{"id":123,"processed":"Y"}
208+
]
209+
}
210+
```
211+
212+
213+
## Interpreting Risk Levels
214+
215+
Elevated lead levels have severe impacts on a child's mental and physical development. When the API identifies elevated blood-lead levels, doctors are highly encouraged to conduct further blood tests
216+
217+
!!! info "Follow-up after the blood test"
218+
If elevated lead levels are confirmed by subsequent blood testing, the family has multiple options when deciding how to mitigate potential sources of lead poisoning: The City of Chicago has [limited grant funding](https://www.cityofchicago.org/city/en/depts/cdph/provdrs/inspections_and_permitting/svcs/apply_for_financialassistanceforleadabatement.html) to assist low-income homeowners and landlords of affordable housing to eliminate lead hazards. Local non-profits, such as (INSERT NAME OF NON-PROFITS). Families who rent their home from a landlord can also contact the City of Chicago for inspectors to inspect their homes for potential sources of lead poisoning. Families may dial 311 for further assistance.

‎docs/apply.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<p>If your institution is interested in participating in the Lead Safe program, please fill-out the following application to the Chicago Department of Public Health. All applications must have a clinician and technical contact identified before application, meet the <a href="/eligibility-criteria/">eligibility requirements</a> and agree to the <a href="/tos/">terms of service</a>. Clinicians must be licensed doctors who will help their health network use Lead Safe as part of the hospital's daily operations. The technical contact should be able to work to connect electronic medical records to the Lead Safe API. If you have any questions, please contact <a href="mailto:HealthyHomes@cityofchicago.org">HealthyHomes@cityofchicago.org</a>.</p>
1+
<p>If your institution is interested in participating in the Lead Safe program, please fill-out the following application to the Chicago Department of Public Health. All applications must have a clinician and technical contact identified before application, meet the <a href="../eligibility-criteria/">eligibility requirements</a> and agree to the <a href="../tos/">terms of service</a>. Clinicians must be licensed doctors who will help their health network use Lead Safe as part of the hospital's daily operations. The technical contact should be able to work to connect electronic medical records to the Lead Safe API. If you have any questions, please contact <a href="mailto:HealthyHomes@cityofchicago.org">HealthyHomes@cityofchicago.org</a>.</p>
22

33
<form method="POST" action="http://formspree.io/developers@cityofchicago.org">
44
<h3>Please select from one of the eligible health networks</h3>
@@ -62,12 +62,12 @@
6262

6363
<h3>Eligibility Criteria</h3>
6464

65-
<input type="checkbox" name="eligibility-criteria" value="certifies-eligibility">I have read the <a href="/eligibility-criteria/">eligibility criteria</a> and certify that this institution meets the minimum standards.
65+
<input type="checkbox" name="eligibility-criteria" value="certifies-eligibility">I have read the <a href="../eligibility-criteria/">eligibility criteria</a> and certify that this institution meets the minimum standards.
6666
<br />
6767

6868
<h3>Terms of Service</h3>
6969

70-
<input type="checkbox" name="accept-terms-of-service" value="accepts-terms-of-service">I accept the <a href="/tos/">Terms of Service</a><br />
70+
<input type="checkbox" name="accept-terms-of-service" value="accepts-terms-of-service">I accept the <a href="../tos/">Terms of Service</a><br />
7171
<br />
7272
<button type="submit" class="btn">SUBMIT</button>
7373
<input type="hidden" name="_subject" value="Test submission: Lead Safe API Request" />

0 commit comments

Comments
 (0)