Digital Surveillance Sensors

Attribute	Details
Source Name	sensors
Data Source	Various digital data streams
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 2022w36
Temporal Scope Start	2010w40
License	CC BY

Overview

This endpoint provides access to Delphi’s digital surveillance sensor estimates for seasonal influenza-like illness (ILI). It aggregates signals from multiple digital sources, including Google Health Trends, Wikipedia access counts, Twitter posts, and CDC web traffic, to provide real-time indicators of flu activity before official clinical reports are finalized.

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

Note: This repository was built to support modelling and forecasting efforts surrounding dengue and seasonal influenza. Syndromic surveillance data, like ILI data (influenza-like illness) through FluView, will likely prove very useful for understanding disease in the time period that includes the COVID-19 pandemic. However, we urge caution to users examining the digital surveillance sensors, like ILI Nearby, Google Flu Trends, etc., during that same date range, because these were designed to track ILI as driven by seasonal influenza, and were NOT designed to track ILI during the COVID-19 pandemic.

Table of contents

1. Data Sources
2. The API
   1. Parameters
      1. Required
      2. Optional
   2. Response
3. Example URLs
   1. Delphi’s Digital Surveillance SAR3 Sensor on 2020w01 (national)
4. Code Samples
   1. Legacy Clients

Data Sources

The endpoint aggregates data from the following sources.

Signal	Name	Description	Documentation
cdc	CDC Webpage Visits	Count of hits to CDC flu-related pages	Docs
gft	Google Flu Trends	Estimated ILI cases	Docs
ght	Google Health Trends	Search volume for flu terms	Docs
twtr	Twitter Stream	Percentage of tweets related to ILI	Docs
wiki	Wikipedia Access	Page view counts for flu articles	Docs
quid	Quidel	Positive influenza lab tests	Docs
sar3	Seasonal Auto-Regressive model (v3)	SAR3 is a regression model that, given the current week number and preliminary wILI values of the past three weeks, provides an estimate of the final wILI value of the current week.	Reference (Subsection 4.3.2: Predictions)
epic	Epicast	A web-based system that collects and aggregates epidemic predictions from human participants to leverage collective human judgment.	Reference
arch	Archefilter	Builds an archetype influenza trajectory by splitting, smoothing, centering, and averaging historical wILI trajectories to estimate the current season’s curve.	Reference (Appendix B: The Archefilter)

The API

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

Parameters

Required

Parameter	Description	Type
epiweeks	epiweeks (see Date Formats)	list of epiweeks
locations	locations	list of location codes: nat, HHS regions, Census divisions, or state codes (see Geographic Codes)
names	sensor names	list of string

Note: Restricted access: Some component signals require authentication.

• Publicly-accessible sensors: sar3, epic, arch (no auth required)
• Private sensors: twtr, gft, ght, ghtj, cdc, quid, wiki (require auth token)

Optional

Parameter	Description	Type
auth	sensor authentication tokens (currently restricted to 1); can be global or granular	list of string

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[].name	sensor name	string
epidata[].location	location code	string
epidata[].epiweek	epiweek	integer
epidata[].value	signal value (varies by sensor)	float
message	success or error message	string

Example URLs

Delphi’s Digital Surveillance SAR3 Sensor on 2020w01 (national)

https://api.delphi.cmu.edu/epidata/sensors/?auth=...&names=sar3&locations=nat&epiweeks=202001

{
  "result": 1,
  "epidata": [
    {
      "name": "sar3",
      "location": "nat",
      "epiweek": 202001,
      "value": 6.2407
    }
  ],
  "message": "success"
}

Code Samples

Libraries are available for R and Python. The following samples show how to import the library and fetch national Delphi’s Digital Surveillance SAR3 Sensor data for epiweeks 201501-202001.

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.sensors(['nat'], ['sar3'], EpiRange(201501, 202001))
print(res['result'], res['message'], len(res['epidata']))

library(epidatr)
# Fetch data
res <- pvt_sensors(auth = 'SECRET_API_AUTH_SENSORS', locations = 'nat',
names = 'sar3', epiweeks = epirange(201501, 202001))
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.sensors(['nat'], ['sar3'], Epidata.range(201501, 202001))
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$sensors(locations = list("nat"), sensors = list("sar3"), epiweeks = Epidata$range(201501, 202001))
print(res$message)
print(length(res$epidata))

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