FluView Clinical

Attribute	Details
Source Name	fluview_clinical
Data Source	United States Centers for Disease Control and Prevention (CDC)
Geographic Levels	National, HHS regions, states, and Census divisions (see Geographic Codes)
Temporal Granularity	Weekly (Epiweek)
Reporting Cadence	Weekly (typically Fridays)
Temporal Scope Start	2016w40
License	Publicly Accessible US Government

Overview

This data source provides age-stratified clinical data on laboratory-confirmed influenza from the US Flu View system.

General topics not specific to any particular endpoint are discussed in the API overview. Such topics include: contributing, citing, and data licensing.

Table of contents

1. The API
   1. Parameters
      1. Required
      2. Optional
   2. Response
2. Example URLs
   1. FluView Clinical on 2020w01 (national)
3. Code Samples
   1. Legacy Clients

The API

The base URL is: https://api.delphi.cmu.edu/epidata/fluview_clinical/

Parameters

Required

Parameter	Description	Type
epiweeks	epiweeks (see Date Formats)	list of epiweeks
regions	regions	list of region labels: nat, states, hhs1-hhs10, cen1-cen9 (see Geographic Codes)

Optional

Parameter	Description	Type
issues	issues (see Date Formats)	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.

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	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

FluView Clinical on 2020w01 (national)

https://api.delphi.cmu.edu/epidata/fluview_clinical/?regions=nat&epiweeks=202001

{
  "result": 1,
  "epidata": [
    {
      "release_date": "2021-10-08",
      "region": "nat",
      "issue": 202139,
      "epiweek": 202001,
      "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 and Python. The following samples show how to import the library and fetch national FluView Clinical data for epiweeks 201601-201701.

Install the package using pip:

pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"

# 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']))

library(epidatr)
# Fetch data
res <- pub_fluview_clinical(regions = "nat", epiweeks =  epirange(201601, 201701))
print(res)

Legacy Clients

We recommend using the modern client libraries mentioned above. Legacy clients are also available for Python, R, and JavaScript.

Optionally install the package using pip(env):

pip install delphi-epidata

Place delphi_epidata.py from this repo next to your python script.

# Import
from delphi_epidata import Epidata
# Fetch data
res = Epidata.fluview_clinical(['nat'], [Epidata.range(201601, 201701)])
print(res['result'], res['message'], len(res['epidata']))

Place delphi_epidata.R from this repo next to your R script.

source("delphi_epidata.R")
# Fetch data
res <- Epidata$fluview_clinical(regions = list("nat"), epiweeks = list(Epidata$range(201601, 201701)))
print(res$message)
print(length(res$epidata))

  <!-- Imports -->
  <script src="delphi_epidata.js"></script>
  <!-- Fetch data -->
  <script>
    EpidataAsync.fluview_clinical('nat', [EpidataAsync.range(201601, 201701)]).then((res) => {
      console.log(res.result, res.message, res.epidata != null ? res.epidata.length : 0);
    });
  </script>