Skip to content

Commit 14df264

Browse files
JavierMtzRdzJavierMtzRdz
committed
docs: Add complete header and code samples to missing endpoints
1 parent e4e3958 commit 14df264

File tree

13 files changed

+1338
-240
lines changed

13 files changed

+1338
-240
lines changed

‎docs/api/01meta.md‎

Lines changed: 75 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,4 +108,78 @@ https://api.delphi.cmu.edu/epidata/meta/
108108

109109
# Code Samples
110110

111-
<!-- TODO: fix -->
111+
Libraries are available for [R](https://cmu-delphi.github.io/epidatr/) and [Python](https://cmu-delphi.github.io/epidatpy/).
112+
The following samples show how to import the library and fetch API metadata.
113+
114+
### R
115+
116+
```R
117+
library(epidatr)
118+
# Fetch data
119+
res <- pub_meta()
120+
print(res)
121+
```
122+
123+
### Python
124+
125+
Install the package using pip:
126+
```bash
127+
pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
128+
```
129+
130+
```python
131+
# Import
132+
from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
133+
# Fetch data
134+
epidata = EpiDataContext()
135+
res = epidata.pub_meta()
136+
print(res)
137+
```
138+
139+
### JavaScript (in a web browser)
140+
141+
The JavaScript client is available [here](https://github.com/cmu-delphi/delphi-epidata/blob/main/src/client/delphi_epidata.js).
142+
143+
```html
144+
<!-- Imports -->
145+
<script src="delphi_epidata.js"></script>
146+
<!-- Fetch data -->
147+
<script>
148+
EpidataAsync.meta().then((res) => {
149+
console.log(res.result, res.message, res.epidata != null ? res.epidata.length : 0);
150+
});
151+
</script>
152+
```
153+
154+
### Legacy Clients
155+
156+
We recommend using our modern client libraries: [epidatr](https://cmu-delphi.github.io/epidatr/) for R and [epidatpy](https://cmu-delphi.github.io/epidatpy/) for Python. Legacy clients are also available for [Python](https://pypi.org/project/delphi-epidata/) and [R](https://github.com/cmu-delphi/delphi-epidata/blob/dev/src/client/delphi_epidata.R).
157+
158+
#### R (Legacy)
159+
160+
Place `delphi_epidata.R` from this repo next to your R script.
161+
162+
```R
163+
source("delphi_epidata.R")
164+
# Fetch data
165+
res <- Epidata$meta()
166+
print(res$message)
167+
print(length(res$epidata))
168+
```
169+
170+
#### Python (Legacy)
171+
172+
Optionally install the package using pip(env):
173+
```bash
174+
pip install delphi-epidata
175+
```
176+
177+
Otherwise, place `delphi_epidata.py` from this repo next to your python script.
178+
179+
```python
180+
# Import
181+
from delphi_epidata import Epidata
182+
# Fetch data
183+
res = Epidata.meta()
184+
print(res['result'], res['message'], len(res['epidata']))
185+
```

‎docs/api/README.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -117,32 +117,32 @@ The parameters available for each source are documented in each linked source-sp
117117
| [`flusurv`](flusurv.md) | FluSurv | FluSurv-NET data (flu hospitaliation rates) from CDC. | no |
118118
| [`fluview`](fluview.md) | FluView | Influenza-like illness (ILI) from U.S. Outpatient Influenza-like Illness Surveillance Network (ILINet). | no |
119119
| [`fluview_meta`](fluview_meta.md) | FluView Metadata | Summary data about [`fluview`](fluview.md). | no |
120-
| [`fluview_clinical`](fluview_clinical.md) | FluView Clinical | ... <!-- TODO --> | no |
120+
| [`fluview_clinical`](fluview_clinical.md) | FluView Clinical | Clinical flu data. | no |
121121
| [`gft`](gft.md) | Google Flu Trends | Estimate of influenza activity based on volume of certain search queries. Google has discontinued Flu Trends, and this is now a static endpoint. | no |
122122
| [`ght`](ght.md) | Google Health Trends | Estimate of influenza activity based on volume of certain search queries. | yes |
123123
| [`kcdc_ili`](kcdc_ili.md) | KCDC ILI | KCDC ILI data from KCDC website. | no |
124124
| [`meta`](meta.md) | API Metadata | Metadata for `fluview`, `twitter`, `wiki`, and `delphi`. | no |
125125
| [`nidss_flu`](nidss_flu.md) | NIDSS Flu | Outpatient ILI from Taiwan's National Infectious Disease Statistics System (NIDSS). | no |
126126
| [`nowcast`](nowcast.md) | ILI Nearby | A nowcast of U.S. national, regional, and state-level (weighted) percent ILI, available seven days (regionally) or five days (state-level) before the first ILINet report for the corresponding week. | no |
127127
| [`quidel`](quidel.md) | Quidel | Data provided by Quidel Corp., which contains flu lab test results. | yes |
128-
| [`sensors`](sensors.md) | Delphi's Digital Surveillance Sensors | ... <!-- TODO --> | no |
128+
| [`sensors`](sensors.md) | Delphi's Digital Surveillance Sensors | Digital surveillance signals for influenza. | no |
129129
| [`twitter`](twitter.md) | Twitter Stream | Estimate of influenza activity based on analysis of language used in tweets from [HealthTweets](http://HealthTweets.org/). | yes |
130130
| [`wiki`](wiki.md) | Wikipedia Access Logs | Number of page visits for selected English, Influenza-related wikipedia articles. | no |
131131

132132
### Dengue Data
133133

134134
| Endpoint | Name | Description | Restricted? |
135135
| --- | --- | --- | --- |
136-
| [`dengue_nowcast`](dengue_nowcast.md) | Delphi's Dengue Nowcast | ... <!-- TODO --> | ... <!-- TODO --> |
137-
| [`dengue_sensors`](dengue_sensors.md) | Delphi's Dengue Digital Surveillance Sensors | ... <!-- TODO --> | ... <!-- TODO --> |
136+
| [`dengue_nowcast`](dengue_nowcast.md) | Delphi's Dengue Nowcast | Nowcast of dengue in Puerto Rico and other regions. |... <!-- TODO --> |
137+
| [`dengue_sensors`](dengue_sensors.md) | Delphi's Dengue Digital Surveillance Sensors | Digital surveillance signals for dengue. | ... <!-- TODO --> |
138138
| [`nidss_dengue`](nidss_dengue.md) | NIDSS Dengue | Counts of confirmed dengue cases from Taiwan's NIDSS. | no |
139-
| [`paho_dengue`](paho_dengue.md) | PAHO Dengue | ... <!-- TODO --> | ... <!-- TODO --> |
139+
| [`paho_dengue`](paho_dengue.md) | PAHO Dengue | Dengue cases reported by PAHO. | ... <!-- TODO --> |
140140

141141
### Norovirus Data
142142

143143
| Endpoint | Name | Description | Restricted? |
144144
| --- | --- | --- | --- |
145-
| [`meta_norostat`](meta_norostat.md) | NoroSTAT Metadata | ... <!-- TODO --> | ... <!-- TODO --> |
145+
| [`meta_norostat`](meta_norostat.md) | NoroSTAT Metadata | Metadata for NoroSTAT data. | ... <!-- TODO --> |
146146
| [`norostat`](norostat.md) | NoroSTAT | Suspected and confirmed norovirus outbreaks reported by state health departments to the CDC. | ... <!-- TODO --> |
147147

148148
### Deprecated

‎docs/api/cdc.md‎

Lines changed: 141 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,37 @@ nav_order: 2
66
---
77

88
# CDC
9+
{: .no_toc}
910

10-
This is the API documentation for accessing the CDC (`cdc`) endpoint of
11-
[Delphi](https://delphi.cmu.edu/)'s epidemiological data.
11+
12+
| Attribute | Details |
13+
| :--- | :--- |
14+
| **Source Name** | `cdc` |
15+
| **Data Source** | CDC influenza surveillance data |
16+
| **Geographic Coverage** | National, HHS regions, Census divisions, and US states |
17+
| **Temporal Resolution** | Weekly (Epiweek) |
18+
| **Update Frequency** | Inactive - No longer updated |
19+
| **Earliest Date** | 2013w02 (2013-01-06) |
20+
21+
<!-- | **License** | | -->
22+
23+
## Overview
24+
{: .no_toc}
25+
26+
This data source provides CDC-collected influenza surveillance data from various sources.
1227

1328
General topics not specific to any particular endpoint are discussed in the
1429
[API overview](README.md). Such topics include:
1530
[contributing](README.md#contributing), [citing](README.md#citing), and
1631
[data licensing](README.md#data-licensing).
1732

18-
## CDC Data
33+
## Table of contents
34+
{: .no_toc .text-delta}
35+
36+
1. TOC
37+
{:toc}
38+
1939

20-
... <!-- TODO -->
2140

2241
# The API
2342

@@ -33,21 +52,130 @@ See [this documentation](README.md) for details on specifying epiweeks, dates, a
3352
| --- | --- | --- |
3453
| `auth` | password | string |
3554
| `epiweeks` | epiweeks | `list` of epiweeks |
36-
| `locations` | locations | `list` of [region](https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/regions.txt)/[state](https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/states.txt) labels <!-- TODO: check --> |
55+
| `locations` | locations | `list` of location codes: `nat` (national), HHS regions (`hhs1`-`hhs10`), Census divisions (`cen1`-`cen9`), or state codes (see [Geographic Codes](geographic_codes.html#us-regions-and-states)) |
3756

3857
## Response
3958

40-
| Field | Description | Type |
41-
|-----------|-----------------------------------------------------------------|------------------|
42-
| `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
43-
| `epidata` | list of results | array of objects |
44-
| ... | ... | ... | <!-- TODO -->
45-
| `message` | `success` or error message | string |
59+
| Field | Description | Type |
60+
|-----------------------|-----------------------------------------------------------------|------------------|
61+
| `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
62+
| `epidata` | list of results | array of objects |
63+
| `epidata[].location` | location label | string |
64+
| `epidata[].epiweek` | epiweek | integer |
65+
| `epidata[].num1` | number of hits for datasource 1 | integer |
66+
| `epidata[].num2` | number of hits for datasource 2 | integer |
67+
| `epidata[].num3` | number of hits for datasource 3 | integer |
68+
| `epidata[].num4` | number of hits for datasource 4 | integer |
69+
| `epidata[].num5` | number of hits for datasource 5 | integer |
70+
| `epidata[].num6` | number of hits for datasource 6 | integer |
71+
| `epidata[].num7` | number of hits for datasource 7 | integer |
72+
| `epidata[].num8` | number of hits for datasource 8 | integer |
73+
| `epidata[].total` | total page hits across all datasources | integer |
74+
| `epidata[].value` | computed value (may be null) | float or null |
75+
| `message` | `success` or error message | string |
4676

4777
# Example URLs
4878

49-
<!-- TODO: fix -->
79+
### CDC Page Hits on 2015w01 (national)
80+
https://api.delphi.cmu.edu/epidata/cdc/?auth=...&locations=nat&epiweeks=201501
81+
82+
```json
83+
{
84+
"result": 1,
85+
"epidata": [
86+
{
87+
"location": "nat",
88+
"epiweek": 201501,
89+
"num1": 91858,
90+
"num2": 81121,
91+
"num3": 89511,
92+
"num4": 52278,
93+
"num5": 16219,
94+
"num6": 87327,
95+
"num7": 38310,
96+
"num8": 51461,
97+
"total": 4252190,
98+
"value": null
99+
}
100+
],
101+
"message": "success"
102+
}
103+
```
50104

51105
# Code Samples
52106

53-
<!-- TODO: fix -->
107+
Libraries are available for [R](https://cmu-delphi.github.io/epidatr/) and [Python](https://cmu-delphi.github.io/epidatpy/).
108+
The following samples show how to import the library and fetch CDC data for national level for epiweek `201501`.
109+
110+
### R
111+
112+
```R
113+
library(epidatr)
114+
# Fetch data
115+
res <- pvt_cdc(auth = 'auth_token', locations = 'nat', epiweeks = 201501)
116+
print(res)
117+
```
118+
119+
### Python
120+
121+
Install the package using pip:
122+
```bash
123+
pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
124+
```
125+
126+
```python
127+
# Import
128+
from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
129+
# Fetch data
130+
epidata = EpiDataContext()
131+
res = epidata.pvt_cdc(auth='auth_token', locations=['nat'], epiweeks=[201501])
132+
print(res)
133+
```
134+
135+
### JavaScript (in a web browser)
136+
137+
The JavaScript client is available [here](https://github.com/cmu-delphi/delphi-epidata/blob/main/src/client/delphi_epidata.js).
138+
139+
```html
140+
<!-- Imports -->
141+
<script src="delphi_epidata.js"></script>
142+
<!-- Fetch data -->
143+
<script>
144+
EpidataAsync.cdc('auth_token', [201501], 'nat').then((res) => {
145+
console.log(res.result, res.message, res.epidata != null ? res.epidata.length : 0);
146+
});
147+
</script>
148+
```
149+
150+
### Legacy Clients
151+
152+
We recommend using our modern client libraries: [epidatr](https://cmu-delphi.github.io/epidatr/) for R and [epidatpy](https://cmu-delphi.github.io/epidatpy/) for Python. Legacy clients are also available for [Python](https://pypi.org/project/delphi-epidata/) and [R](https://github.com/cmu-delphi/delphi-epidata/blob/dev/src/client/delphi_epidata.R).
153+
154+
#### R (Legacy)
155+
156+
Place `delphi_epidata.R` from this repo next to your R script.
157+
158+
```R
159+
source("delphi_epidata.R")
160+
# Fetch data
161+
res <- Epidata$cdc(auth = "auth_token", epiweeks = list(201501), locations = list("nat"))
162+
print(res$message)
163+
print(length(res$epidata))
164+
```
165+
166+
#### Python (Legacy)
167+
168+
Optionally install the package using pip(env):
169+
```bash
170+
pip install delphi-epidata
171+
```
172+
173+
Otherwise, place `delphi_epidata.py` from this repo next to your python script.
174+
175+
```python
176+
# Import
177+
from delphi_epidata import Epidata
178+
# Fetch data
179+
res = Epidata.cdc('auth_token', [201501], ['nat'])
180+
print(res['result'], res['message'], len(res['epidata']))
181+
```

0 commit comments

Comments
 (0)