CDC

Attribute	Details
Source Name	`cdc`
Data Source	US Centers for Disease Control (CDC) site statistics
Geographic Levels	National, Department of Health & Human Services (HHS) Regions, Census Divisions, State (see Geographic Codes)
Temporal Granularity	Weekly (Epiweek)
Reporting Cadence	Inactive - No longer updated since 2020w03 (2020-01-12)
Temporal Scope Start	2013w02 (2013-01-06)
License	Permission by CDC flu division

Overview

This data source tracks public interest in influenza by counting visits to specific informational pages on the CDC website. Delphi receives server log summaries directly from the CDC, which count page hits for key topics such as ‘Flu Symptoms & Severity’, ‘How Flu Spreads’, and ‘What To Do If You Get Sick’. These counts act as a proxy for information-seeking behavior related to the flu.

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

Note: Restricted access: This endpoint requires authentication.

Estimation
1. Proxy Nature
The API
1. Parameters
  1. Required
2. Response
Example URLs
1. CDC Page Hits on 2015w01 (national)
Code Samples
1. Legacy Clients

Estimation

This endpoint exposes raw aggregation of server logs.

The endpoint consists of page hit counts for specific CDC informational pages.

Field	Description
`num1`	hits for ‘What You Should Know for the … Influenza Season’
`num2`	hits for ‘What To Do If You Get Sick’
`num3`	hits for ‘Flu Symptoms & Severity’
`num4`	hits for ‘How Flu Spreads’
`num5`	hits for ‘What You Should Know About Flu Antiviral Drugs’
`num6`	hits for ‘Weekly US Map’
`num7`	hits for ‘Basics’
`num8`	hits for ‘Flu Activity & Surveillance’
`total`	total number of hits for all CDC pages

Proxy Nature

These signals represent information-seeking behavior (internet searches/page visits), which may not perfectly correlate with clinical influenza burden. Media events or public panic can drive spikes in traffic unrelated to actual disease prevalence.

The API

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

Parameters

Required

Parameter	Description	Type
`auth`	password	string
`epiweeks`	epiweeks (see Date Formats)	`list` of epiweeks
`locations`	locations	`list` of location codes: `nat` (national), HHS regions (`hhs1`-`hhs10`), Census divisions (`cen1`-`cen9`), or state codes (see Geographic Codes)

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[].num(1-8)`	number of page hits for specific pages (see Signal Data Sources)	integer
`epidata[].total`	total page hits across all datasources	integer
`epidata[].value`	computed value (may be null)	float or null
`message`	`success` or error message	string

Example URLs

CDC Page Hits on 2015w01 (national)

https://api.delphi.cmu.edu/epidata/cdc/?auth=...&locations=nat&epiweeks=201501

{
  "result": 1,
  "epidata": [
    {
      "location": "nat",
      "epiweek": 201501,
      "num1": 91858,
      "num2": 81121,
      "num3": 89511,
      "num4": 52278,
      "num5": 16219,
      "num6": 87327,
      "num7": 38310,
      "num8": 51461,
      "total": 4252190,
      "value": null
    }
  ],
  "message": "success"
}

Code Samples

Libraries are available for R and Python. The following samples show how to import the library and fetch cdc data at the national level for epiweek 201501.

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
epidata = EpiDataContext()
res = epidata.pvt_cdc(auth='auth_token', locations=['nat'], epiweeks=[201501])
print(res)

library(epidatr)
# Fetch data
res <- pvt_cdc(auth = 'auth_token', locations = 'nat', epiweeks = 201501)
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

Otherwise, place delphi_epidata.py from this repo next to your python script.

# Import
from delphi_epidata import Epidata
# Fetch data
res = Epidata.cdc('auth_token', [201501], ['nat'])
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$cdc(auth = "auth_token", epiweeks = list(201501), locations = list("nat"))
print(res$message)
print(length(res$epidata))

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

CDC