+
+
-### JavaScript (in a web browser)
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pub_fluview(regions="nat", epiweeks=EpiRange(201501, 201510))
+print(res)
+```
+
+
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pub_fluview(regions = "nat", epiweeks = epirange(201501, 201510))
+print(res)
+```
+
-````html
+
+
+The JavaScript client is available [here](https://github.com/cmu-delphi/delphi-epidata/blob/main/src/client/delphi_epidata.js).
+
+```html
-````
+ EpidataAsync.fluview('nat', [EpidataAsync.range(201501, 201510)]).then((res) => {
+
+
+### Legacy Clients
+
+We recommend using the modern client libraries mentioned above. Legacy clients are also available for [Python](https://pypi.org/project/delphi-epidata/), [R](https://github.com/cmu-delphi/delphi-epidata/blob/dev/src/client/delphi_epidata.R), and [JavaScript](https://github.com/cmu-delphi/delphi-epidata/blob/dev/src/client/delphi_epidata.js).
-### 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.fluview(['nat'], [201440, Epidata.range(201501, 201510)])
+res = Epidata.fluview(['nat'], [Epidata.range(201501, 201510)])
print(res['result'], res['message'], len(res['epidata']))
-````
+```
+
-### R
+
-````R
-# Import
-source('delphi_epidata.R')
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
# Fetch data
-res <- Epidata$fluview(list('nat'), list(201440, Epidata$range(201501, 201510)))
-cat(paste(res$result, res$message, length(res$epidata), "\n"))
-````
+res <- Epidata$fluview(regions = list("nat"), epiweeks = list(Epidata$range(201501, 201510)))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+
+```html
+
+
+
+
+```
+
+
+
diff --git a/docs/api/fluview_clinical.md b/docs/api/fluview_clinical.md
index ca2b7b801..d37a438cc 100644
--- a/docs/api/fluview_clinical.md
+++ b/docs/api/fluview_clinical.md
@@ -2,139 +2,228 @@
title: FluView Clinical
parent: Data Sources and Signals
grand_parent: Other Endpoints (COVID-19 and Other Diseases)
-nav_order: 1
+nav_order: 2
---
# FluView Clinical
+{: .no_toc}
-This is the API documentation for accessing the FluView Clinical
-(`fluview_clinical`) endpoint of [Delphi](https://delphi.cmu.edu/)'s
-epidemiological data.
+
+| Attribute | Details |
+| :--- | :--- |
+| **Source Name** | `fluview_clinical` |
+| **Data Source** | [United States Centers for Disease Control and Prevention (CDC)](http://gis.cdc.gov/grasp/fluview/fluportaldashboard.html) |
+| **Geographic Levels** | National, Department of Health & Human Services (HHS) Regions, Census Divisions, State (see [Geographic Codes](geographic_codes.md#us-regions-and-states)) |
+| **Temporal Granularity** | Weekly (Epiweek) |
+| **Reporting Cadence** | Weekly (typically Fridays) |
+| **Temporal Scope Start** | 2016w40 |
+| **License** | [Publicly Accessible US Government](https://www.usa.gov/government-works) |
+
+
+## Overview
+{: .no_toc}
+
+This data source provides age-stratified clinical data based on laboratory-confirmed influenza reports from the US FluView dashboard.
General topics not specific to any particular endpoint are discussed in the
[API overview](README.md). Such topics include:
[contributing](README.md#contributing), [citing](README.md#citing), and
[data licensing](README.md#data-licensing).
-## FluView Clinical Data
+## Table of contents
+{: .no_toc .text-delta}
+
+1. TOC
+{:toc}
+
+## Estimation
+
+Values are sourced directly from the CDC's NREVSS (National Respiratory and Enteric Virus Surveillance System) clinical laboratories.
+
+The metrics consist of weekly counts of influenza specimens (total tested and total positive for types A and B) and their corresponding positivity rates. Unlike the syndromic ILI data in the [FluView](fluview.html) endpoint, these metrics provide laboratory confirmation of influenza circulation.
+
+### Percentages
+
+The CDC calculates three percentage metrics:
-...
+* **`percent_positive`**: Percentage of total specimens that tested positive for influenza (A or B)
+* **`percent_a`**: Percentage of total specimens that tested positive for influenza A
+* **`percent_b`**: Percentage of total specimens that tested positive for influenza B
-# The API
+
-The base URL is: https://api.delphi.cmu.edu/epidata/fluview_clinical/
+## Lag and Backfill
-See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
+The data is preliminary and subject to revision. Clinical labs may report data late or correct previously reported data. The `issues` and `lag` parameters allow access to historical versions of the data.
-## Parameters
+## The API
-### Required
+The base URL is:
+
+
+### Parameters
+
+#### Required
| Parameter | Description | Type |
| --- | --- | --- |
-| `epiweeks` | epiweeks | `list` of epiweeks |
-| `regions` | regions | `list` of [region](https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/regions.txt) labels |
+| `epiweeks` | epiweeks (see [Date Formats](date_formats.md)) | `list` of epiweeks |
+| `regions` | regions | `list` of region labels: `nat`, states, `hhs1`-`hhs10`, `cen1`-`cen9` (see [Geographic Codes](geographic_codes.md#us-regions-and-states)) |
-### Optional
+#### Optional
| Parameter | Description | Type |
|-----------|--------------------------------------------|--------------------|
-| `issues` | issues | `list` of epiweeks |
+| `issues` | issues (see [Date Formats](date_formats.md)) | `list` of epiweeks |
| `lag` | # weeks between each epiweek and its issue | integer |
-Notes:
-- If both `issues` and `lag` are specified, only `issues` is used.
-If neither is specified, the current issues are used.
+{: .note}
+> **Notes:**
+> - If both `issues` and `lag` are specified, only `issues` is used.
+> - If neither is specified, the current issues are used.
-## Response
+### Response
| Field | Description | Type |
|------------------------------|-----------------------------------------------------------------|------------------|
| `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
| `epidata` | list of results | array of objects |
-| `epidata[].release_date` | | string |
-| `epidata[].region` | | string |
-| `epidata[].issue` | | integer |
-| `epidata[].epiweek` | | integer |
-| `epidata[].lag` | | integer |
-| `epidata[].total_specimens` | | integer |
-| `epidata[].total_a` | | integer |
-| `epidata[].total_b` | | integer |
-| `epidata[].percent_positive` | | float |
-| `epidata[].percent_a` | | float |
-| `epidata[].percent_b` | | float |
+| `epidata[].release_date` | date when data was released | string |
+| `epidata[].region` | region identifier | string |
+| `epidata[].issue` | epiweek of publication | integer |
+| `epidata[].epiweek` | epiweek for which data is valid | integer |
+| `epidata[].lag` | number of weeks between epiweek and issue | integer |
+| `epidata[].total_specimens` | total number of specimens tested | integer |
+| `epidata[].total_a` | total specimens positive for influenza A | integer |
+| `epidata[].total_b` | total specimens positive for influenza B | integer |
+| `epidata[].percent_positive` | percentage of specimens testing positive for influenza | float |
+| `epidata[].percent_a` | percentage of specimens testing positive for influenza A | float |
+| `epidata[].percent_b` | percentage of specimens testing positive for influenza B | float |
| `message` | `success` or error message | string |
-# Example URLs
+## Example URLs
### FluView Clinical on 2020w01 (national)
-https://api.delphi.cmu.edu/epidata/fluview_clinical/?regions=nat&epiweeks=202001
+
```json
{
"result": 1,
"epidata": [
{
- "release_date": "2020-04-10",
+ "release_date": "2021-10-08",
"region": "nat",
- "issue": 202014,
+ "issue": 202139,
"epiweek": 202001,
- "lag": 13,
- "total_specimens": 64980,
- "total_a": 5651,
- "total_b": 9647,
- "percent_positive": 23.5426,
- "percent_a": 8.69652,
- "percent_b": 14.8461
- },
- ...
+ "lag": 91,
+ "total_specimens": 65177,
+ "total_a": 5645,
+ "total_b": 9664,
+ "percent_positive": 23.4883,
+ "percent_a": 8.66103,
+ "percent_b": 14.8273
+ }
],
"message": "success"
}
```
+## Code Samples
+
+Libraries are available for [R](https://cmu-delphi.github.io/epidatr/) and [Python](https://cmu-delphi.github.io/epidatpy/).
+The following samples show how to import the library and fetch national FluView Clinical data for epiweeks `201601-201701`.
+
+
+
+
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+res = Epidata.fluview_clinical(['nat'], [Epidata.range(201601, 201701)])
+print(res['result'], res['message'], len(res['epidata']))
+```
+
+
+
-# Code Samples
+```R
+library(epidatr)
+# Fetch data
+res <- pub_fluview_clinical(regions = "nat", epiweeks = epirange(201601, 201701))
+print(res)
+```
+
-Libraries are available for [JavaScript](https://github.com/cmu-delphi/delphi-epidata/blob/main/src/client/delphi_epidata.js), [Python](https://pypi.org/project/delphi-epidata/), and [R](https://github.com/cmu-delphi/delphi-epidata/blob/dev/src/client/delphi_epidata.R).
-The following samples show how to import the library and fetch national FluView Clinical data for epiweeks `201940` and `202001-202010` (11 weeks total).
+
+
+
+
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.
+Place `delphi_epidata.py` from this repo next to your python script.
-````python
+```python
# Import
from delphi_epidata import Epidata
# Fetch data
-res = Epidata.fluview_clinical(['nat'], [201940, Epidata.range(202001, 202010)])
+res = Epidata.fluview_clinical(['nat'], [Epidata.range(201601, 201701)])
print(res['result'], res['message'], len(res['epidata']))
-````
+```
+
-### R
+
-````R
-# Import
-source('delphi_epidata.R')
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
# Fetch data
-res <- Epidata$fluview_clinical(list('nat'), list(201940, Epidata$range(202001, 202010)))
-cat(paste(res$result, res$message, length(res$epidata), "\n"))
-````
+res <- Epidata$fluview_clinical(regions = list("nat"), epiweeks = list(Epidata$range(201601, 201701)))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+
+ ```html
+
+
+
+
+ ```
+
+
+
+
+
+
+
+```python
+# Import
+from epidatpy import EpiDataContext
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pub_fluview_meta()
+print(res)
+```
+
+
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pub_fluview_meta()
+print(res)
+```
+
+
+
+
+
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pub_gft(locations='nat', epiweeks=EpiRange(201501, 201510))
+print(res)
+```
+
+
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pub_gft(locations = 'nat', epiweeks = epirange(201501, 201510))
+print(res)
+```
+
-### 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.gft(['nat'], [201440, Epidata.range(201501, 201510)])
+res = Epidata.gft(['nat'], Epidata.range(201501, 201510))
print(res['result'], res['message'], len(res['epidata']))
-````
+```
+
-### R
+
-````R
-# Import
-source('delphi_epidata.R')
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
# Fetch data
-res <- Epidata$gft(list('nat'), list(201440, Epidata$range(201501, 201510)))
-cat(paste(res$result, res$message, length(res$epidata), "\n"))
-````
+res <- Epidata$gft(locations = list("nat"), epiweeks = Epidata$range(201501, 201510))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+
+```html
+
+
+
+
+```
+
+
+
+Click to expand full list of valid queries
+
+* `/m/0cycc`
+* `influenza type a`
+* `flu duration`
+* `flu fever`
+* `treating flu`
+* `fever flu`
+* `flu recovery`
+* `braun thermoscan`
+* `oscillococcinum`
+* `treating the flu`
+* `cold or flu`
+* `flu versus cold`
+* `flu remedies`
+* `contagious flu`
+* `type a influenza`
+* `flu or cold`
+* `duration of flu`
+* `cold versus flu`
+* `flu cough`
+* `flu headache`
+* `thermoscan`
+* `influenza incubation period`
+* `flu lasts`
+* `length of flu`
+* `flu stomach`
+* `cold vs flu`
+* `flu and fever`
+* `getting over the flu`
+* `influenza a`
+* `treatment for flu`
+* `flu length`
+* `treatment for the flu`
+* `influenza symptoms`
+* `over the counter flu`
+* `flu complications`
+* `cold and flu symptoms`
+* `influenza incubation`
+* `treatment of flu`
+* `human temperature`
+* `low body`
+* `flu contagious`
+* `robitussin ac`
+* `flu how long`
+* `ear thermometer`
+* `flu contagious period`
+* `treat flu`
+* `cough flu`
+* `low body temperature`
+* `expectorant`
+* `flu and cold`
+* `rapid flu`
+* `flu vs. cold`
+* `how to treat the flu`
+* `how long does the flu last?`
+* `viral pneumonia`
+* `flu in kids`
+* `type a flu`
+* `influenza treatment`
+* `fighting the flu`
+* `flu relief`
+* `treat the flu`
+* `flu medicine`
+* `dangerous fever`
+* `what is influenza`
+* `tussin`
+* `low body temp`
+* `flu care`
+* `flu in infants`
+* `flu dizziness`
+* `feed a fever`
+* `flu vs cold`
+* `flu vomiting`
+* `bacterial pneumonia`
+* `flu activity`
+* `flu chills`
+* `anas barbariae`
+* `flu germs`
+* `tylenol cold`
+* `how to get over the flu`
+* `flu in children`
+* `influenza a and b`
+* `duration of the flu`
+* `cold symptoms`
+* `flu report`
+* `rapid flu test`
+* `flu relapse`
+* `get over the flu`
+* `flu during pregnancy`
+* `flu recovery time`
+* `cure for flu`
+* `tamiflu and breastfeeding`
+* `flu chest pain`
+* `flu treatment`
+* `flu nausea`
+* `remedies for the flu`
+* `tamiflu in pregnancy`
+* `side effects of tamiflu`
+* `how to treat flu`
+* `viral bronchitis`
+* `flu how long contagious`
+* `flu remedy`
+
+
+
+### Response
+
+| Field | Description | Type |
+|-----------------------|-----------------------------------------------------------------|------------------|
+| `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
+| `epidata` | list of results | array of objects |
+| `epidata[].location` | location label | string |
+| `epidata[].epiweek` | epiweek | integer |
+| `epidata[].query` | search query | string |
+| `epidata[].value` | search volume | float |
+| `message` | `success` or error message | string |
+
+## Example URLs
+
+### Google Health Trends for "how to get over the flu" on 2015w01 (US)
+
+
+```json
+{
+ "result": 1,
+ "epidata": [
+ {
+ "location": "US",
+ "epiweek": 201501,
+ "value": 9.113
+ }
+ ],
+ "message": "success"
+}
+```
+
+## Code Samples
+
+Libraries are available for [R](https://cmu-delphi.github.io/epidatr/) and [Python](https://cmu-delphi.github.io/epidatpy/).
+The following samples show how to import the library and fetch GHT data for "how to get over the flu" in the US for epiweek `201501`.
+
+
+
+
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.ght('auth_token', ['US'], [201501], 'how to get over the flu')
+print(res['result'], res['message'], len(res['epidata']))
+```
+
+
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pvt_ght(auth = 'auth_token', locations = 'US', epiweeks = 201501,
+ query = "how to get over the flu")
+print(res)
+```
+
+
+
+
+
+
+
+Optionally install the package using pip(env):
+```bash
+pip install delphi-epidata
+```
+
+Otherwise, place `delphi_epidata.py` from this repo next to your python script.
+
+```python
+# Import
+from delphi_epidata import Epidata
+# Fetch data
+res = Epidata.ght('auth_token', ['US'], [201501], 'how to get over the flu')
+print(res['result'], res['message'], len(res['epidata']))
+```
+
+
+
+
+Place `delphi_epidata.R` from this repo next to your R script.
-## Response
+```R
+source("delphi_epidata.R")
+# Fetch data
+res <- Epidata$ght(auth = "auth_token", locations = list("US"), epiweeks = list(201501), query = "how to get over the flu")
+print(res$message)
+print(length(res$epidata))
+```
+
-| Field | Description | Type |
-|-----------|-----------------------------------------------------------------|------------------|
-| `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
-| `epidata` | list of results | array of objects |
-| ... | ... | ... |
-| `message` | `success` or error message | string |
+
-# Example URLs
-
-# Code Samples
+```html
+
+
+
+
+```
+
-
+
+
+
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pub_nowcast(locations=['nat'], epiweeks=EpiRange(202001, 202010))
+print(res)
+```
+
-### Python
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pub_nowcast(locations = 'nat', epiweeks = epirange(202001, 202010))
+print(res)
+```
+
+
+
+
+
+
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.nowcast(['nat'], [201940, Epidata.range(202001, 202010)])
+res = Epidata.nowcast(['nat'], Epidata.range(202001, 202010))
print(res['result'], res['message'], len(res['epidata']))
-````
+```
+
-### R
+
-````R
-# Import
-source('delphi_epidata.R')
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
# Fetch data
-res <- Epidata$nowcast(list('nat'), list(201940, Epidata$range(202001, 202010)))
-cat(paste(res$result, res$message, length(res$epidata), "\n"))
-````
+res <- Epidata$nowcast(locations = list("nat"), epiweeks = Epidata$range(202001, 202010))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+
+```html
+
+
+
+
+```
+
+
+
+
-## Response
+
-| Field | Description | Type |
-|-----------|-----------------------------------------------------------------|------------------|
-| `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
-| `epidata` | list of results | array of objects |
-| ... | ... | ... |
-| `message` | `success` or error message | string |
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
-# Example URLs
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pub_kcdc_ili(regions=['ROK'], epiweeks=[202001, 202002])
+print(res)
+```
+
-
+
-# Code Samples
+```R
+library(epidatr)
+# Fetch data
+res <- pub_kcdc_ili(regions = 'ROK', epiweeks = c(202001, 202002))
+print(res)
+```
+
+
+
+
+
+
+
+Optionally install the package using pip(env):
+```bash
+pip install delphi-epidata
+```
+
+Otherwise, place `delphi_epidata.py` from this repo next to your python script.
+
+```python
+# Import
+from delphi_epidata import Epidata
+# Fetch data
+res = Epidata.kcdc_ili(['ROK'], [202001, 202002])
+print(res['result'], res['message'], len(res['epidata']))
+```
+
+
+
+
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
+# Fetch data
+res <- Epidata$kcdc_ili(regions = list("ROK"), epiweeks = list(202001, 202002))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+
+```html
+
+
+
+
+```
+
-
+
+
+
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pub_nidss_dengue(locations=['nationwide'], epiweeks=EpiRange(201501, 201510))
+print(res)
+```
+
+
+
-### Python
+```R
+library(epidatr)
+# Fetch data
+res <- pub_nidss_dengue(locations = 'nationwide', epiweeks = epirange(201501, 201510))
+print(res)
+```
+
+
+
+
+
+
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.nidss_dengue(['nationwide'], [201440, Epidata.range(201501, 201510)])
+res = Epidata.nidss_dengue(['nationwide'], Epidata.range(201501, 201510))
print(res['result'], res['message'], len(res['epidata']))
-````
+```
-### R
+# Source and Licensing
-````R
-# Import
-source('delphi_epidata.R')
+The full text of the NIDSS Dengue license information is available on the Taiwan Digital Development Department's [website](https://data.gov.tw/license).
+
+
+
+
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
# Fetch data
-res <- Epidata$nidss_dengue(list('nationwide'), list(201440, Epidata$range(201501, 201510)))
-cat(paste(res$result, res$message, length(res$epidata), "\n"))
-````
+res <- Epidata$nidss_dengue(regions = list("nationwide"), epiweeks = Epidata$range(201501, 201510))
+print(res$message)
+print(length(res$epidata))
+```
+
-# Source and Licensing
+
+
+
+
+```html
+
+
+
+
+```
+
-The full text of the NIDSS Dengue license information is available on the Taiwan Digital Development Department's [website](https://data.gov.tw/license).
\ No newline at end of file
+
+
+
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pub_nidss_flu(regions=['nationwide'], epiweeks=EpiRange(201501, 201510))
+print(res)
+```
+
+
+
-### Python
+```R
+library(epidatr)
+# Fetch data
+res <- pub_nidss_flu(regions = 'nationwide', epiweeks = epirange(201501, 201510))
+print(res)
+```
+
+
+
+
+
+
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.nidss_flu(['nationwide'], [201440, Epidata.range(201501, 201510)])
+res = Epidata.nidss_flu(['nationwide'], Epidata.range(201501, 201510))
print(res['result'], res['message'], len(res['epidata']))
-````
+```
+
+# Source and Licensing
-### R
+The full text of the NIDSS Flu license information is available on the Taiwan Digital Development Department's [website](https://data.gov.tw/license).
+
-````R
-# Import
-source('delphi_epidata.R')
+
+
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
# Fetch data
-res <- Epidata$nidss_flu(list('nationwide'), list(201440, Epidata$range(201501, 201510)))
-cat(paste(res$result, res$message, length(res$epidata), "\n"))
-````
+res <- Epidata$nidss_flu(regions = list("nationwide"), epiweeks = Epidata$range(201501, 201510))
+print(res$message)
+print(length(res$epidata))
+```
+
-# Source and Licensing
+
+
+
+
+```html
+
+
+
+
+```
+
-The full text of the NIDSS Flu license information is available on the Taiwan Digital Development Department's [website](https://data.gov.tw/license).
\ No newline at end of file
+
+
-# The API
+
-The base URL is: https://api.delphi.cmu.edu/epidata/norostat/
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
-See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pvt_norostat(auth='auth_token', locations=['Minnesota, Ohio, Oregon, Tennessee, and Wisconsin'], epiweeks=[201501])
+print(res)
+```
+
-## Parameters
+
-### Required
+```R
+library(epidatr)
+# Fetch data
+res <- pvt_norostat(auth = 'auth_token', locations = 'Minnesota, Ohio, Oregon, Tennessee, and Wisconsin', epiweeks = 201501)
+print(res)
+```
+
-
+
+
-
+
-# Code Samples
+Optionally install the package using pip(env):
+```bash
+pip install delphi-epidata
+```
+
+Otherwise, place `delphi_epidata.py` from this repo next to your python script.
+
+```python
+# Import
+from delphi_epidata import Epidata
+# Fetch data
+res = Epidata.norostat('auth_token', ['Minnesota, Ohio, Oregon, Tennessee, and Wisconsin'], [201501])
+print(res['result'], res['message'], len(res['epidata']))
+```
+
+
+
+
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
+# Fetch data
+res <- Epidata$norostat(auth = "auth_token", locations = list("Minnesota, Ohio, Oregon, Tennessee, and Wisconsin"), epiweeks = list(201501))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+
+```html
+
+
+
+
+```
+
-
+
+
+
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pvt_meta_norostat(auth='auth_token')
+print(res)
+```
+
+
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pvt_meta_norostat(auth = 'auth_token')
+print(res)
+```
+
+
+
+
+
+
+
+Optionally install the package using pip(env):
+```bash
+pip install delphi-epidata
+```
+
+Otherwise, place `delphi_epidata.py` from this repo next to your python script.
+
+```python
+# Import
+from delphi_epidata import Epidata
+# Fetch data
+res = Epidata.meta_norostat('auth_token')
+print(res['result'], res['message'], len(res['epidata']))
+```
+
+
+
+
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
+# Fetch data
+res <- Epidata$meta_norostat(auth = "auth_token")
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+
+```html
+
+
+
+
+```
+
-
+
*Note: Data availability varies by country.* |
+| **Temporal Granularity** | Weekly (Epiweek) |
+| **Reporting Cadence** | Inactive - No longer updated since 2020w31 |
+| **Temporal Scope Start** | 2014w01 |
+| **License** | This was scraped from a publicly-accessible website, but no explicit license terms were found. |
+
+## Overview
+{: .no_toc}
+
+This endpoint provides weekly dengue case counts for countries and territories in the Americas, as reported by the Pan American Health Organization (PAHO).
General topics not specific to any particular endpoint are discussed in the
[API overview](README.md). Such topics include:
[contributing](README.md#contributing), [citing](README.md#citing), and
[data licensing](README.md#data-licensing).
-## PAHO Dengue Data
+## Table of contents
+{: .no_toc .text-delta}
+
+1. TOC
+{:toc}
+
+## Estimation
+
+Data is scraped from PAHO epidemiological reports. The endpoint exposes cumulative counts per calendar year for each country.
+
+The available indicators include:
+* **`num_dengue`**: Total cumulative cases of dengue.
+* **`num_severe`**: Cumulative cases of severe dengue.
+* **`num_deaths`**: Cumulative dengue-related deaths.
+* **`incidence_rate`**: Incidence rate per 100,000 population, calculated as `(num_dengue / total_pop) * 100` (where `total_pop` is in thousands).
+
+No additional smoothing or statistical adjustments are applied by Delphi.
+
+## Lag and Backfill
+
+* **Lag:** Historically, data was updated weekly but with varying reporting lags depending on the country or territory.
+* **Backfill:** Historical values were subject to revisions by PAHO as more laboratory confirmations were finalized. Delphi tracks these via the `issue` and `release_date`.
+
+## Limitations
+
+* Not all countries report all metrics (e.g., severe cases or deaths) consistently every week.
+
+
+
+## The API
+
+The base URL is:
+
+
+### Parameters
+
+#### Required
+
+| Parameter | Description | Type |
+| --- | --- | --- |
+| `epiweeks` | epiweeks (see [Date Formats](date_formats.md)) | `list` of epiweeks |
+| `regions` | regions | `list` of region labels (see [Geographic Codes](geographic_codes.md#paho-dengue)) |
-...
+### Response
-# The API
+| Field | Description | Type |
+|------------------------------|-----------------------------------------------------------------|------------------|
+| `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
+| `epidata` | list of results | array of objects |
+| `epidata[].release_date` | date when data was released | date (YYYY-MM-DD)|
+| `epidata[].region` | region label (ISO 3166-1 alpha-2 code) | string |
+| `epidata[].serotype` | dengue serotype information | string |
+| `epidata[].issue` | epiweek when data was issued | integer |
+| `epidata[].epiweek` | epiweek for the data point | integer |
+| `epidata[].lag` | number of weeks between epiweek and issue | integer |
+| `epidata[].total_pop` | total population (in thousands) | integer |
+| `epidata[].num_dengue` | total number of dengue cases | integer |
+| `epidata[].num_severe` | number of severe dengue cases | integer |
+| `epidata[].num_deaths` | number of dengue-related deaths | integer |
+| `epidata[].incidence_rate` | incidence rate per 100,000 population | float |
+| `message` | `success` or error message | string |
-The base URL is: https://api.delphi.cmu.edu/epidata/paho_dengue/
+## Example URLs
-See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
+### PAHO Dengue on 2015w01 (Canada)
+
-## Parameters
+```json
+{
+ "result": 1,
+ "epidata": [
+ {
+ "release_date": "2020-08-07",
+ "region": "CA",
+ "serotype": " ",
+ "issue": 202032,
+ "epiweek": 201501,
+ "lag": 291,
+ "total_pop": 0,
+ "num_dengue": 0,
+ "num_severe": 0,
+ "num_deaths": 0,
+ "incidence_rate": 0.0
+ }
+ ],
+ "message": "success"
+}
+```
-### Required
+## Code Samples
-
+Libraries are available for [R](https://cmu-delphi.github.io/epidatr/) and [Python](https://cmu-delphi.github.io/epidatpy/).
+The following samples show how to import the library and fetch PAHO Dengue data for Canada for epiweek `201501`.
-## Response
+
+
-# Example URLs
+
-
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
-# Code Samples
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pub_paho_dengue(regions=['ca'], epiweeks=[201501])
+print(res)
+```
+
-
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pub_paho_dengue(regions = 'ca', epiweeks = 201501)
+print(res)
+```
+
+
+
+
+
+
+
+Place `delphi_epidata.py` from this repo next to your python script.
+
+```python
+# Import
+from delphi_epidata import Epidata
+# Fetch data
+res = Epidata.paho_dengue(['ca'], [201501])
+print(res['result'], res['message'], len(res['epidata']))
+```
+
+
+
+
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
+# Fetch data
+res <- Epidata$paho_dengue(regions = list("ca"), epiweeks = list(201501))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+
+```html
+
+
+
+
+```
+
+
+
+
+
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pvt_quidel(auth='auth_token', locations=['hhs1'], epiweeks=EpiRange(201535, 202001))
+print(res)
+```
+
+
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pvt_quidel(auth = 'auth_token', locations = 'hhs1', epiweeks = epirange(201535, 202001))
+print(res)
+```
+
+
+
+
+
+
+
+Optionally install the package using pip(env):
+```bash
+pip install delphi-epidata
+```
+
+Otherwise, place `delphi_epidata.py` from this repo next to your python script.
+
+```python
+# Import
+from delphi_epidata import Epidata
+# Fetch data
+res = Epidata.quidel('auth_token', ['hhs1'], Epidata.range(201535, 202001))
+print(res['result'], res['message'], len(res['epidata']))
+```
+
+
+
+
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
+# Fetch data
+res <- Epidata$quidel(auth = "auth_token", locations = list("hhs1"), epiweeks = Epidata$range(201535, 202001))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
-## Response
+```html
+
+
+
+
+```
+
-| Field | Description | Type |
-|-----------|-----------------------------------------------------------------|------------------|
-| `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
-| `epidata` | list of results | array of objects |
-| ... | ... | ... |
-| `message` | `success` or error message | string |
\ No newline at end of file
+
+
+
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pvt_twitter(auth='auth_token', locations=['nat'], time_type="week", time_values=[201501])
+print(res)
+```
+
+
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pvt_twitter(auth = 'auth_token', locations = 'nat',
+ time_type = "week", time_values = 201501)
+print(res)
+```
+
+
+
+
+
+
+
+Optionally install the package using pip(env):
+```bash
+pip install delphi-epidata
+```
+
+Otherwise, place `delphi_epidata.py` from this repo next to your python script.
+
+```python
+# Import
+from delphi_epidata import Epidata
+# Fetch data
+res = Epidata.twitter('auth_token', ['nat'], time_type="week", time_values=[201501])
+print(res['result'], res['message'], len(res['epidata']))
+```
+
+
+
+
+Place `delphi_epidata.R` from this repo next to your R script.
+
+```R
+source("delphi_epidata.R")
+# Fetch data
+res <- Epidata$twitter(auth = "auth_token", locations = list("nat"), time_type = "week", time_values = list(201501))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+
+```html
+
+
+
+
+```
+
+
+
+Click to expand
+
+| Article Name |
+|---|
+| amantadine |
+| antiviral_drugs |
+| avian_influenza |
+| canine_influenza |
+| cat_flu |
+| chills |
+| common_cold |
+| cough |
+| equine_influenza |
+| fatigue_(medical) |
+| fever |
+| flu_season |
+| gastroenteritis |
+| headache |
+| hemagglutinin_(influenza) |
+| human_flu |
+| influenza |
+| influenzalike_illness |
+| influenzavirus_a |
+| influenzavirus_c |
+| influenza_a_virus |
+| influenza_a_virus_subtype_h10n7 |
+| influenza_a_virus_subtype_h1n1 |
+| influenza_a_virus_subtype_h1n2 |
+| influenza_a_virus_subtype_h2n2 |
+| influenza_a_virus_subtype_h3n2 |
+| influenza_a_virus_subtype_h3n8 |
+| influenza_a_virus_subtype_h5n1 |
+| influenza_a_virus_subtype_h7n2 |
+| influenza_a_virus_subtype_h7n3 |
+| influenza_a_virus_subtype_h7n7 |
+| influenza_a_virus_subtype_h7n9 |
+| influenza_a_virus_subtype_h9n2 |
+| influenza_b_virus |
+| influenza_pandemic |
+| influenza_prevention |
+| influenza_vaccine |
+| malaise |
+| myalgia |
+| nasal_congestion |
+| nausea |
+| neuraminidase_inhibitor |
+| orthomyxoviridae |
+| oseltamivir |
+| paracetamol |
+| rhinorrhea |
+| rimantadine |
+| shivering |
+| sore_throat |
+| swine_influenza |
+| viral_neuraminidase |
+| viral_pneumonia |
+| vomiting |
+| zanamivir |
+
+
+
+###### Norovirus (Noro)
+
+Click to expand
+
+| Article Name |
+|---|
+| abdominal_pain |
+| caliciviridae |
+| dehydration |
+| diarrhea |
+| fecal–oral_route |
+| foodborne_illness |
+| gastroenteritis |
+| intravenous_therapy |
+| leaky_scanning |
+| nausea |
+| norovirus |
+| oral_rehydration_therapy |
+| rotavirus |
+| shellfish |
+| vomiting |
+
+
+
+###### Dengue
+
+Click to expand
+
+| Article Name |
+|---|
+| aedes |
+| aedes_aegypti |
+| arthralgia |
+| blood_transfusion |
+| dengue_fever |
+| dengue_vaccine |
+| dengue_virus |
+| diarrhea |
+| exanthem |
+| fever |
+| flavivirus |
+| headache |
+| hematuria |
+| mosquito |
+| mosquito-borne_disease |
+| myalgia |
+| nausea |
+| nosebleed |
+| paracetamol |
+| petechia |
+| rhinitis |
+| thrombocytopenia |
+| vomiting |
+
+
+
+
+
+#### Optional
| Parameter | Description | Type |
|-----------|-------------|------------------------|
| `hours` | hours | `list` of hours (0-23) |
-## Response
+{: .note}
+> **Notes:**
+> - Only one of `dates` and `epiweeks` is required. If both are provided, `epiweeks` is ignored.
+> - `dates`, `epiweeks`, and `hours` are `None` by default.
+> - `language` is `en` by default.
+
+### Response
| Field | Description | Type |
|---------------------|-----------------------------------------------------------------|------------------|
| `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
| `epidata` | list of results | array of objects |
-| `epidata[].article` | | string |
-| `epidata[].count` | | integer |
-| `epidata[].total` | | integer |
-| `epidata[].hour` | hour (-1 if `hour` not used) | integer |
-| `epidata[].date` | date (yyyy-MM-dd) (only included if `date` used) | string |
-| `epidata[].epiweek` | epiweek (only included if `epiweek` used) | integer |
-| `epidata[].value` | | float |
+| `epidata[].article` | Wikipedia article name | string |
+| `epidata[].count` | article-specific pageview count for the requested period/hours | integer |
+| `epidata[].total` | total Wikipedia pageviews for the specified `language` (e.g., all English Wikipedia traffic) over the same period/hours | integer |
+| `epidata[].hour` | hour (0-23) of access (-1 if not filtering by hour) | integer |
+| `epidata[].date` | date (yyyy-MM-dd) | string |
+| `epidata[].epiweek` | epiweek | integer |
+| `epidata[].value` | normalized pageview count (pageviews per million total language traffic): `(count / total) * 10^6` | float |
| `message` | `success` or error message | string |
-# Example URLs
+## Example URLs
### Wikipedia Access article "influenza" on 2020w01
-https://api.delphi.cmu.edu/epidata/wiki/?language=en&articles=influenza&epiweeks=202001
+
```json
{
@@ -88,7 +245,7 @@ https://api.delphi.cmu.edu/epidata/wiki/?language=en&articles=influenza&epiweeks
```
### Wikipedia Access article "influenza" on date 2020-01-01
-https://api.delphi.cmu.edu/epidata/wiki/?language=en&articles=influenza&dates=20200101
+
```json
{
@@ -107,54 +264,103 @@ https://api.delphi.cmu.edu/epidata/wiki/?language=en&articles=influenza&dates=20
}
```
-# Code Samples
+## Code Samples
-Libraries are available for [JavaScript](https://github.com/cmu-delphi/delphi-epidata/blob/main/src/client/delphi_epidata.js), [Python](https://pypi.org/project/delphi-epidata/), and [R](https://github.com/cmu-delphi/delphi-epidata/blob/dev/src/client/delphi_epidata.R).
-The following samples show how to import the library and fetch national Wikipedia Access data for article "influenza" on
-epiweeks `201940` and `202001-202010` (11 weeks total) for hours 0 and 12 in English.
+Libraries are available for [R](https://cmu-delphi.github.io/epidatr/) and [Python](https://cmu-delphi.github.io/epidatpy/).
+The following samples show how to import the library and fetch Wikipedia Access data for article "influenza" in English for epiweeks `202001-202010` (10 weeks total) and hours 0 and 12.
-
+
+
-````html
-
-
-
-
-````
+
+
+Install the package using pip:
+```bash
+pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"
+```
+
+```python
+# Import
+from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
+# Fetch data
+epidata = EpiDataContext()
+res = epidata.pub_wiki(articles=['influenza'], time_values=EpiRange(202001, 202010), time_type='week', language='en', hours=[0, 12])
+print(res)
+```
+
+
+
+
+```R
+library(epidatr)
+# Fetch data
+res <- pub_wiki(articles = "influenza", time_values = epirange(202001, 202010),
+ time_type = "week", language = "en", hours = c(0, 12))
+print(res)
+```
+
+
+
+
+
+
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.wiki(['influenza'], None, [201940, Epidata.range(202001, 202010)], [0, 12])
+res = Epidata.wiki(['influenza'], Epidata.range(202001, 202010), {'time_type': 'week', 'language': 'en', 'hours': [0, 12]})
print(res['result'], res['message'], len(res['epidata']))
-````
+```
+
-Note:
-- `dates`, `epiweeks`, and `hours` are `None` by default.
-- `language` is `en` by default.
+
-### R
+Place `delphi_epidata.R` from this repo next to your R script.
-````R
-# Import
-source('delphi_epidata.R')
+```R
+source("delphi_epidata.R")
# Fetch data
-res <- Epidata$wiki(list('nat'), NULL, list(201940, Epidata$range(202001, 202010)), list(0, 12), 'en')
-cat(paste(res$result, res$message, length(res$epidata), "\n"))
-````
+res <- Epidata$wiki(articles = list("influenza"), time_values = Epidata$range(202001, 202010), time_type = "week", options = list(language = "en", hours = list(0, 12)))
+print(res$message)
+print(length(res$epidata))
+```
+
+
+
+
+
+```html
+
+
+
+
+```
+
+
+