Skip to content

Commit 3bd01e9

Browse files
authored
Merge pull request #124 from cmu-delphi/covidcast-geos
Further expand/improve COVIDcast API docs
2 parents 50ed5aa + d968398 commit 3bd01e9

File tree

2 files changed

+40
-17
lines changed

2 files changed

+40
-17
lines changed

docs/api/covidcast.md

Lines changed: 36 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ The COVIDcast API is based on HTTP GET queries and returns data in JSON form.
2828
The base URL is https://delphi.cmu.edu/epidata/api.php.
2929

3030
Several [API clients are available](#api-clients) for common programming
31-
languages, so you do not need to construct API calls yourself.
31+
languages, so you do not need to construct API calls yourself. Alternately, [see
32+
below](#example-urls) for example API URLs and query responses.
3233

3334
See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
3435

@@ -45,8 +46,6 @@ select set of these data signals.
4546

4647
### Parameters
4748

48-
#### Required
49-
5049
| Parameter | Description | Type |
5150
| --- | --- | --- |
5251
| `data_source` | name of upstream data source (e.g., `doctor-visits` or `fb-survey`; [see full list](covidcast_signals.md)) | string |
@@ -57,7 +56,7 @@ select set of these data signals.
5756
| `geo_value` | unique code for each location, depending on `geo_type` (county -> FIPS 6-4 code, HRR -> HRR number, MSA -> CBSA code, DMA -> DMA code, state -> two-letter [state](../../labels/states.txt) code), or `*` for all | string |
5857

5958
The current set of signals available for each data source is returned by the
60-
[`covidcast_meta`](covidcast_meta.md) endpoint.
59+
[`covidcast_meta`](covidcast_meta.md) endpoint.
6160

6261
### Response
6362

@@ -84,24 +83,27 @@ requests for smaller time intervals.
8483
## Geographic Coding
8584

8685
The `geo_value` field specifies the geographic location whose estimate is being
87-
reported. County-level estimates are reported by the county FIPS code. All FIPS
88-
codes are reported using pre-2015 FIPS code assignments, *except* for FIPS codes
89-
used by the `jhu-csse` source. These are reported exactly as JHU reports their
90-
data; see below.
91-
92-
Other possible `geo_type`s include:
86+
reported. Estimates are available for several possible `geo_type`s:
9387

88+
* `county`: County-level estimates are reported by the county's five-digit [FIPS
89+
code](https://en.wikipedia.org/wiki/FIPS_county_code). All FIPS codes are
90+
reported using pre-2015 FIPS code assignments, *except* for FIPS codes used by
91+
the `jhu-csse` source. These are reported exactly as JHU reports their data;
92+
[see below](#fips-exceptions-in-jhu-data).
9493
* `hrr`: Hospital Referral Region, units designed to represent regional health
9594
care markets. There are roughly 300 HRRs in the United States. A map is
9695
available
97-
[here](https://hub.arcgis.com/datasets/fedmaps::hospital-referral-regions).
96+
[here](https://hub.arcgis.com/datasets/fedmaps::hospital-referral-regions). We
97+
report HRRs by their number (non-consecutive, between 1 and 457).
9898
* `msa`: Metropolitan Statistical Area, as defined by the Office of Management
9999
and Budget. The Census Bureau provides [detailed definitions of these
100-
regions](https://www.census.gov/programs-surveys/metro-micro/about.html).
100+
regions](https://www.census.gov/programs-surveys/metro-micro/about.html). We
101+
report MSAs by their CBSA ID number.
101102
* `dma`: Designated Market Areas represent geographic regions with their own
102103
media markets, as [defined by
103104
Nielsen](https://www.nielsen.com/us/en/intl-campaigns/dma-maps/).
104-
* `state`: The 50 states.
105+
* `state`: The 50 states, identified by their two-digit postal abbreviation (in
106+
lower case). Estimates for Puerto Rico are available as state `pr`; Washington, D.C. is available as state `dc`.
105107

106108
Some signals are not available for all `geo_type`s, since they may be reported
107109
from their original sources with different levels of aggregation.
@@ -208,7 +210,7 @@ properly.
208210

209211
## Example URLs
210212

211-
### Delphi's COVID-19 Surveillance Streams from Facebook Survey CLI on 2020-04-06 to 2010-04-10 (county 06001)
213+
### Facebook Survey CLI on 2020-04-06 to 2010-04-10 (county 06001)
212214

213215
https://delphi.cmu.edu/epidata/api.php?source=covidcast&data_source=fb-survey&signal=raw_cli&time_type=day&geo_type=county&time_values=20200406-20200410&geo_value=06001
214216

@@ -230,10 +232,29 @@ https://delphi.cmu.edu/epidata/api.php?source=covidcast&data_source=fb-survey&si
230232
}
231233
```
232234

233-
### Delphi's COVID-19 Surveillance Streams from Facebook Survey CLI on 2020-04-06 (all counties)
235+
### Facebook Survey CLI on 2020-04-06 (all counties)
234236

235237
https://delphi.cmu.edu/epidata/api.php?source=covidcast&data_source=fb-survey&signal=raw_cli&time_type=day&geo_type=county&time_values=20200406&geo_value=*
236238

239+
```json
240+
{
241+
"result": 1,
242+
"epidata": [
243+
{
244+
"geo_value": "01000",
245+
"time_value": 20200406,
246+
"direction": null,
247+
"value": 1.1693378,
248+
"stderr": 0.1909232,
249+
"sample_size": 1451.0327
250+
},
251+
...
252+
],
253+
"message": "success"
254+
}
255+
```
256+
257+
237258
## API Clients
238259

239260
Libraries are available for

docs/api/covidcast_signals.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -222,5 +222,7 @@ map](https://covidcast.cmu.edu/):
222222
| Symptoms in Community (Facebook) | `fb-survey` | `smoothed_hh_cmnty_cli` |
223223
| Search Trends (Google) | `ght` | `smoothed_search` |
224224
| Combined | `indicator-combination` | `nmf_day_doc_fbc_fbs_ght` |
225-
| Cases (JHU) | `jhu-csse` | `confirmed_incidence_prop` |
226-
| Deaths (JHU) | `jhu-csse` | `deaths_incidence_prop` |
225+
| Cases | `jhu-csse` | `confirmed_incidence_num` |
226+
| Cases per capita | `jhu-csse` | `confirmed_incidence_prop` |
227+
| Deaths | `jhu-csse` | `deaths_incidence_num` |
228+
| Deaths per capita | `jhu-csse` | `confirmed_incidence_prop` |

0 commit comments

Comments
 (0)