Merge pull request #1008 from cmu-delphi/krivard/covid_hosp-docs-update

Update covid_hosp endpoint documentation with August 2022 limitations

Author: krivard

docs/api/covid_hosp.md

@@ -11,11 +11,22 @@ Hospital Capacity by State" datasets provided by the US Department of
 Health & Human Services via healthdata.gov. The latter provides more frequent updates,
 so it is combined with the former to create a single dataset which is as recent as possible.
 
+HHS performs up to four days of forward-fill for missing values in the
+[facility-level data](covid_hosp_facility.md) which are aggregated to make this
+state-level dataset. This sometimes results in repeated values in the state-level data.
+A sequence of two repeated values is extremely common, and longer sequences are rare.
+Repeated values added in this way are sometimes updated if the underlying missing data can
+be completed at a later date.
+
+Starting October 1, 2022, some facilities are only required to report annually.
+
 For more information, see the
 [official description and data dictionary at healthdata.gov](https://healthdata.gov/Hospital/COVID-19-Reported-Patient-Impact-and-Hospital-Capa/g62h-syeh)
 for "COVID-19 Reported Patient Impact and Hospital Capacity by State Timeseries,"
 as well as the [official description](https://healthdata.gov/dataset/COVID-19-Reported-Patient-Impact-and-Hospital-Capa/6xf2-c3ie)
-for "COVID-19 Reported Patient Impact and Hospital Capacity by State."
+for "COVID-19 Reported Patient Impact and Hospital Capacity by State." The data elements,
+cadence, and how the data are being used in the federal response are documented in
+[a FAQ published by Health & Human Services](https://www.hhs.gov/sites/default/files/covid-19-faqs-hospitals-hospital-laboratory-acute-care-facility-data-reporting.pdf).
 
 General topics not specific to any particular data source are discussed in the
 [API overview](README.md). Such topics include:
@@ -65,7 +76,7 @@ If `issues` is not specified, then the most recent issue is used by default.
 | `epidata[].state` | state pertaining to this row | string |
 | `epidata[].date` | date pertaining to this row | integer |
 | `epidata[].issue` | the date on which the dataset containing this row was published | integer |
-| `epidata[].*` | see the [data dictionary](https://healthdata.gov/covid-19-reported-patient-impact-and-hospital-capacity-state-data-dictionary) |  |
+| `epidata[].*` | see the [data dictionary](https://healthdata.gov/Hospital/COVID-19-Reported-Patient-Impact-and-Hospital-Capa/g62h-syeh). Last synced: 2021-10-21 |  |
 | `message` | `success` or error message | string |
 
 # Example URLs
@@ -149,25 +160,31 @@ The following sample shows how to import the library and fetch MA on 2020-05-10
 ### Python
 
 Optionally install the package using pip(env):
-````bash
+```bash
 pip install delphi-epidata
-````
+```
 
 Otherwise, place `delphi_epidata.py` from this repo next to your python script.
 
-````python
+```python
 # Import
 from delphi_epidata import Epidata
 # Fetch data
 res = Epidata.covid_hosp('MA', 20200510)
 print(res['result'], res['message'], len(res['epidata']))
-````
+```
 
 # Repair Log
 
 If we ever need to repair the data record due to a bug in our code (not at the
 source), we will update the list below.
 
+## October 21, 2021
+
+All issues between 20210430 and 20211021 were re-uploaded to include new columns added by
+HHS. If you pulled these issues before October 21, the data you received was correct, but
+was missing the added columns.
+
 ## January 22, 2021
 
 The following issues were repaired:

docs/api/covid_hosp_facility.md

@@ -9,9 +9,16 @@ This data source is a mirror of the "COVID-19 Reported Patient Impact and
 Hospital Capacity by Facility" dataset provided by the US Department of Health
 & Human Services via healthdata.gov.
 
+HHS performs up to four days of forward-fill for missing values.
+
+Starting October 1, 2022, some facilities are only required to report annually.
+
 See the
 [official description and data dictionary at healthdata.gov](https://healthdata.gov/Hospital/COVID-19-Reported-Patient-Impact-and-Hospital-Capa/anag-cw7u)
-for more information.
+for more information. The data elements, cadence, and how the data are being used in the
+federal response are documented in
+[a FAQ published by Health & Human Services](https://www.hhs.gov/sites/default/files/covid-19-faqs-hospitals-hospital-laboratory-acute-care-facility-data-reporting.pdf).
+
 
 General topics not specific to any particular data source are discussed in the
 [API overview](README.md). Such topics include:
@@ -74,7 +81,7 @@ has been renamed here for clarity.
 | `epidata[].hospital_pk` | facility identified by this row | string |
 | `epidata[].collection_week` | Friday's date in the week pertaining to this row | integer |
 | `epidata[].publication_date` | the date on which the dataset containing this row was published | integer |
-| `epidata[].*` | see the [data dictionary](https://healthdata.gov/covid-19-reported-patient-impact-and-hospital-capacity-facility-data-dictionary) |  |
+| `epidata[].*` | see the [data dictionary](https://healthdata.gov/Hospital/COVID-19-Reported-Patient-Impact-and-Hospital-Capa/anag-cw7u) |  |
 | `message` | `success` or error message | string |
 
 # Example URLs

docs/api/covid_hosp_facility_lookup.md

@@ -54,10 +54,21 @@ supported.
 | --- | --- | --- |
 | `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
 | `epidata` | list of results | array of objects |
-| `epidata[].hospital_pk` | facility identified by this row | string |
-| `epidata[].*` | see the [data dictionary](https://healthdata.gov/covid-19-reported-patient-impact-and-hospital-capacity-facility-data-dictionary) |  |
+| `epidata[].hospital_pk` | unique identifier for this facility (will match CCN if CCN exists) | string |
+| `epidata[].state` | two-letter state code | string |
+| `epidata[].ccn` | CMS Certification Number for this facility | string |
+| `epidata[].hospital_name` | facility name | string |
+| `epidata[].address` | facility address | string |
+| `epidata[].city` | facility city | string |
+| `epidata[].zip` | 5-digit ZIP code | string |
+| `epidata[].hospital_subtype` | one of: Childrens Hospitals, Critical Access Hospitals, Long Term, Psychiatric, Rehabilitation, Short Term  | string |
+| `epidata[].fips_code` | 5-digit FIPS county code | string |
+| `epidata[].is_metro_micro` | 1 if this facility serves a metropolitan or micropolitan area, 0 otherwise | integer |
 | `message` | `success` or error message | string |
 
+Use the `hospital_pk` value when querying
+[the COVID-19 Reported Patient Impact and Hospital Capacity by Facility endpoint](covid_hosp_facility.md).
+
 # Example URLs
 
 ### Lookup facilities in the city of Southlake (TX)