diff --git a/docs/index.md b/docs/index.md index 3f37e5c..2d0bd9f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -"Lead Safe" is an API available to Chicago-area hospital and health networks to provide estimates on a child's potential exposure to elevated lead levels from household paint. Health network providers can provide information on the patient's demographics, address, and history on their past visits and blood-lead levels, the Lead Safe API will provide an estimate on the chance of elevated, unsafe blood-lead levels for children under 4 years-old. +"Lead Safe" is an API available to Chicago-area hospital and health networks to estimate the likelihood that a child will be exposed to lead-based paint hazards. Health network providers can provide information on the patient's demographics, address, and history on their past visits and blood-lead levels, the Lead Safe API will provide an estimate of the risk of elevated, unsafe blood-lead levels for children under 4 years-old. The API uses a predictive model developed by the University of Chicago[^1] that uses historical blood-lead level testing conducted by the State of Illinois. Data submitted through this API and subsequent testing conducted will improve the accuracy of the model, allowing for a more effective use of blood tests to prevent elevated lead levels. @@ -14,47 +14,49 @@ In order to integrate with Lead Safe, the health provider will need to make a RE ## API -### Submitting Prediction - -Submit a patient record and retrieved the estimated probability of having elevated blood-lead levels. +### Submitting Patient Record + +Submit a patient record and retrieve the estimated risk of having elevated blood-lead levels. ```bash POST {json file} /insert/ ``` -| Field | Format | Constraints | Notes/Questions | -|----------------|----------|------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| timestamp | TimeDate | yyyy-mm-dd hh:mm:ss.sss-hh.mm | Current Timestamp. RFC 3339 (ISO 8601 derivative). | -| clinic_id | Text | | Two Characted Organization ID (NN- NearNorth EF- ErieFamily) | -| location_id | Text | | Specific Location Abbreviation in Centricity | -| alliance_id | Text | AlphaNumeric | Uses CPS PatientProfile.patientID | -| address1 | Text | Address number, street direction, street name, street type | Patientprofile.address1 | -| address2 | Text | Additional address information, e.g. apartment number | patientprofile.address2 | -| city | Text | | patientprofile.city | -| state | Text | | patientprofile.state | -| zip | Text | 5 digit zip code | patientprofile.Zip | -| date_of_birth | Date | yyyy-mm-dd | | -| gender | Text | M/F/U | | -| race | Text | Code Values from Centricity | Standard ONC Race definitionsCode description1002-5 American Indian or Alaska Native2028-9 Asian 2054-5 Black or African American 2076-8 Native Hawaiian or Other Pacific Islander 2106-3 White UNK Unknown | -| ethnicity | Text | Code Values from Centricity | Standard ONC Ethnicity definitionsCode description2135-2 Hispanic or Latino 2186-5 Non Hispanic or Latino UNK Unknown | -| Visit Array | | | | -| visit.visit_id | Numeric | 16 Digit GE ID | Unique GE ID for specific visit (DocumentID) | -| visit.date | Date | yyyy-mm-dd | | -| visit.location | Text | | Text Abbreviation for facility of visit location | -| visit.provider | Text | | Full provider name, last name, or just NPI | -| Lab Array | | | | -| lab.lab_id | Numeric | 16 Digit GE ID | Unique GE ID for specific lab result (ObsID) | -| lab.type | Text | BLL | Static BLL unless we identify additional labs to include | -| lab.date | Date | yyyy-mm-dd | | -| lab.route | Text | V | *Always "V" Veinous for Alliance sites | -| lab.result | Text | | Several values are possible; integer, non-integer numeric, ranges indicated by alphanumeric text. We'll use previous examples to essentially construct a dictionary. | +| Field | Format | Constraints | Notes | +|-----------------|----------|------------------------------------|-------------------------------------------------------------------------------------------------------------------| +| timestamp | TimeDate | yyyy-mm-dd hh:mm:ss.sss-hh:mm | Current timestamp (RFC 3339 complient date) | +| network_id | Text | | The parent entity of the submitting organization | +| clinic_id | Text | | Organization ID | +| location_id | Text | | Specific Location Abbreviation in Centricity | +| patient_id | Text | | AlphaNumeric patient identifier | +| address1 | Text | | Patient home address (street number, street direction, street name, street type) | +| address2 | Text | | Patient home address (additional information, e.g. apartment number) | +| city | Text | | Patient home address city | +| state | Text | | Patient home address state | +| zip | Text | | Patient home address zip code | +| date_of_birth | Date | yyyy-mm-dd | Patient date of birth | +| gender | Text | M/F/U | Patient gender | +| race | Text | Code Values from Centricity | Standard ONC Race definitions

**Code / description**
1002-5 / American Indian or Alaska Native
2028-9 / Asian
2054-5 / Black or African American
2076-8 / Native Hawaiian or Other Pacific Islander
2106-3 / White
UNK / Unknown | +| ethnicity | Text | Code Values from Centricity | Standard ONC Ethnicity definitions

**Code / description**
2135-2 / Hispanic or Latino
2186-5 / Non Hispanic or Latino
UNK / Unknown | +| VISIT ARRAY | | | _Optional_ May entirely omit the array if visit history does not exist or is unavailable. | +| visit.visit_id | Numeric | 16 Digit GE ID | Unique GE ID for specific visit (DocumentID) | +| visit.date | Date | yyyy-mm-dd hh:mm:ss.sss-hh:mm | Date of visit (RFC 3339 complient date) | +| visit.location | Text | | Text Abbreviation for facility of visit location | +| visit.provider | Text | | Full provider name, last name, or just NPI | +| LAB ARRAY | | | _Optional_ May entirely omit the array if visit history does not exist or is unavailable. | +| lab.lab_id | Numeric | 16 Digit GE ID | Unique GE ID for specific lab result (ObsID) | +| lab.type | Text | "BLL" | Static BLL unless we identify additional labs to include | +| lab.date | Date | yyyy-mm-dd | Date of lab results | +| lab.sample_type | Text | V/C | "V" Venous
"C" for Capillary | +| lab.result | Text | | Several values are possible; integer, non-integer numeric, ranges indicated by alphanumeric text. | ```json { - "timestamp": "2017-08-22 12:00:00.000000", + "timestamp": "2017-08-22 12:00:00.000-00:00", + "network_id": "Alliance Health", "clinic_id": "EF", "location_id": "examp_loc", - "alliance_id": 9000, + "patient_id": "9000", "address1": "333 S State St", "address2": "Ste 420", "city": "Chicago", @@ -65,38 +67,14 @@ POST {json file} /insert/ "race": "2054-5", "ethnicity": "2186-5", "visit": [ - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"}, - {"date": "2017-07-25 15:02:54.171755", "visit_id": 1234567891011121, "location": "333 S State St", "provider": "John Doe"} + {"visit_id": 1234567891011121, "date": "2017-07-25 15:02:54.171-00:00", "location": "333 S State St", "provider": "John Doe"}, + {"visit_id": 1234567891011121, "date": "2017-07-25 15:02:54.171-00:00", "location": "333 S State St", "provider": "John Doe"}, + {"visit_id": 1234567891011121, "date": "2017-07-25 15:02:54.171-00:00", "location": "333 S State St", "provider": "John Doe"} ], "lab": [ - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 5.0, "result": "None Detected ug/dL", "date": "2016-07-29", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 5.0, "result": "1", "date": "2015-08-21", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 5.0, "result": "1", "date": "2015-02-27", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 5.0, "result": "1", "date": "2014-06-06", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "3", "date": "2014-09-29", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "4.1", "date": "2014-01-09", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "4.1", "date": "2013-06-28", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "6.3", "date": "2013-03-13", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "9.7", "date": "2012-10-02", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "16.3", "date": "2012-06-19", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "3", "date": "2016-09-16", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "3", "date": "2015-12-15", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "3", "date": "2015-06-09", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "13.6", "date": "2012-03-20", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "15", "date": "2012-02-21", "type": "BLL"}, - {"lab_id": 1234567891011121, "route": "V", "healthcenterid": 1.0, "result": "5", "date": "2011-08-19", "type": "BLL"}] + {"lab_id": 1234567891011121, "type": "BLL", "date": "2016-07-29", "sample_type": "V", "result": "None Detected ug/dL"}, + {"lab_id": 1234567891011121, "type": "BLL", "date": "2015-08-21", "sample_type": "V", "result": "16.3"}, + {"lab_id": 1234567891011121, "type": "BLL", "date": "2015-02-27", "sample_type": "V", "result": "1"}] } ``` @@ -104,37 +82,41 @@ POST {json file} /insert/ #### Body -| Field | Format | Constraints | Notes/Questions | -|------------------|--------------|---------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| -| version | Text | "0.3.0" | Follows Semantic Versioning 2.0.0 http://semver.org/spec/v2.0.0.html | -| timestamp | TimeDate | yyyy-mm-ddThh:mm:ss.sss-hh:mm | Current Timestamp. RFC 3339 (ISO 8601 derivative). | -| visit_date | Date | yyyy-mm-dd | Effective date of score | -| alliance_id | Text | AlphaNumeric | Return value provided by Feed | -| risk_score | AlphaNumeric | 9.99 | Currently expecting numeric, future may be phrased by stating an odds ratio with the risk score. | -| risk_score_notes | Text | Additional notes (referral, remediation funds, etc to be returned to provider ) | | +| Field | Format | Constraints | Notes/Questions | +|------------------|----------|-------------------------------|--------------------------------------------------------------------------------------------| +| version | Text | "0.3.0" | Follows Semantic Versioning 2.0.0 http://semver.org/spec/v2.0.0.html | +| timestamp | TimeDate | yyyy-mm-dd hh:mm:ss.sss-hh:mm | Current Timestamp (RFC 3339 complient date). | +| network_id | Text | | Parent entity - same value as submitted to the API. | +| clinic_id | Text | | Organization ID - same value as submitted to the API. | +| location_id | Text | | Specific Location Abbreviation in Centricity - same value as submitted to the API. | +| patient_id | Text | AlphaNumeric | Identifier for the patient - same value as submitted to the API. | +| risk_score | Text | 9.99 | Currently expecting numeric, future may be phrased by stating an odds ratio with the risk score. | +| risk_score_notes | Text | | Additional notes (referral, remediation funds, etc to be returned to provider ) | ```json { - "risk_score": "0.309", - "risk_score_notes": "Risk Score Notes", - "visit_date": "2017-07-25", "version": "0.3.0", - "alliance_id": 6425, - "timestamp": "2017-08-11 19:20:29" + "timestamp": "2017-08-11 19:20:29.000-00:00", + "network_id": "Alliance Health", + "clinic_id": "EF", + "location_id": "examp_loc", + "patient_id": "9000", + "risk_score": "0.309", + "risk_score_notes": "Risk Score Notes" } ``` #### Header -| Field | Format | Constraints | +| Field | Format | Constraints | Notes | |------------------|--------------|------------------|---------------------------------------------------------------------------------------------| -| Date | Integer | N/A | ID of the record submitted. | +| Date | Integer | | ID of the record submitted. | | Server | Text | "Apache" | The type of the server providing the results | -| Content-Location | URL | | Pernament location to retrieve the results | -| ETag | | | | +| Content-Location | URL | | Pernament location to retrieve the results | +| ETag | | | | | Content-Length | Integer | 225 | | | Content-Type | Text | application/json | Informs user that the content will be a JSON file | -| Set-Cookie | Text | | | +| Set-Cookie | Text | | | ``` HTTP/1.1 200 OK @@ -147,7 +129,6 @@ Content-Type: application/json Set-Cookie: BIGipServerwebapps1int.cityofchicago.org-443.app~webapps1int.cityofchicago.org-443_pool=339105802.47873.0000; Secure; HttpOnly; path=/; Httponly; Secure ``` - ### Retrieving Previous Predictions 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. @@ -172,9 +153,9 @@ GET /get/ ##### Response -| Field | Format | Constraints | +| Field | Format | Constraints | Notes | |-------------|--------------|----------------|--------------------------------------------------------------------------------------------------| -| id | Integer | N/A | ID of the record submitted. | +| id | Integer | | ID of the record submitted. | | processed | Text | "Y" or "N" | Whether the results are available. Results may be an error or blank if the record was incorrect. | ```json @@ -206,6 +187,6 @@ Thou shalt not... ## Acknowledgements -The "Lead Safe" API was developed by the [Chicago Department of Public Health](https://www.cityofchicago.org/city/en/depts/cdph.html), [University of Chicago's Center for Data Science and Public Policy](http://dsapp.uchicago.edu/), and the [Chicago Department of Innovation and Technology](https://www.cityofchicago.org/city/en/depts/doit.html). This project was made possible by a grant from the [Robert Wood Johnson Foundation](http://www.rwjf.org/). +The "Lead Safe" API was developed by the [Chicago Department of Public Health](https://www.cityofchicago.org/city/en/depts/cdph.html), University of Chicago's [Center for Data Science and Public Policy](http://dsapp.uchicago.edu/) and [Harris School of Public Policy](http://harris.uchicago.edu), and the [Chicago Department of Innovation and Technology](https://www.cityofchicago.org/city/en/depts/doit.html). This project was made possible by a grant from the [Robert Wood Johnson Foundation](http://www.rwjf.org/). [^1]: Potash _et al._ (2015) [Predictive Modeling for Public Health](ttps://dssg.uchicago.edu/wp-content/uploads/2016/01/p2039-potash.pdf). _Proceedings of the 21th ACM SIGKDD International Conference on Knowledge Discovery and Data Mining_ pp. 2039-2047. diff --git a/mkdocs.yml b/mkdocs.yml index d60aab4..ec59edd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ # Site Information -site_name: Lead Safe API v0.3.0 +site_name: Lead Safe API v0.4.0 site_author: City of Chicago site_description: Lead Free API Documentation site_url: http://dev.cityofchicago.org/docs/lead-free