Documentation and sample code for DELPHI's epidemiological data API.
Python PHP R CoffeeScript HTML
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
labels
src
tests/acquisition/fluview
LICENSE
README.md
deploy.json

README.md

Status

Deploy Status

About

This repo provides documentation and sample code for DELPHI's real-time epidemiological data API. The API currently contains influenza and dengue data for the United States and Taiwan.

This document contains the following sections:

Influenza Data

FluView

Influenza-like illness (ILI) from U.S. Outpatient Influenza-like Illness Surveillance Network (ILINet).

* Data is usually released on Friday

ILI-Nearby

A nowcast of U.S. national, regional, and state-level (weighted) %ILI, available seven days (regionally) or five days (state-level) before the first ILINet report for the corresponding week.

* Data is usually released on Friday and updated on Sunday and Monday

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 data source.

  • Data source: Google
  • Temporal Resolution: Weekly from 2003w40 until 2015w32
  • Spatial Resolution: National, HHS regions (1+10); by state/territory (50+1); and by city (97)
  • Open access

Twitter Stream

Estimate of influenza activity based on analysis of language used in tweets.

  • Data source: HealthTweets
  • Temporal Resolution: Daily and weekly from 2011-12-01 (2011w48)
  • Spatial Resolution: National, HHS regions, and Census divisions (1+10+9); and by state/territory (51)
  • Restricted access: DELPHI doesn't have permission to share this dataset

Wikipedia Access Logs

Number of page visits for selected English, Influenza-related wikipedia articles.

  • Data source: Wikimedia
  • Temporal Resolution: Hourly, daily, and weekly from 2007-12-09 (2007w50)
  • Spatial Resolution: N/A
  • Other resolution: By article (54)
  • Open access

NIDSS Flu

Outpatient ILI from Taiwan's National Infectious Disease Statistics System (NIDSS).

* Data is usually released on Tuesday

Dengue Data

NIDSS Dengue

Counts of confirmed dengue cases from Taiwan's NIDSS.

The API

The base URL is: https://delphi.midas.cs.cmu.edu/epidata/api.php

Epiweeks use the U.S. definition. That is, the first epiweek each year is the week, starting on a Sunday, containing January 4. See this page for more information.

Formatting for epiweeks is YYYYWW and for dates is YYYYMMDD.

list parameters consist of a comma-separated list of individual values or, for numeric parameters, a hyphenated range of values. Examples include:

  • param=201530 (A single epiweek)
  • param=201401,201501,201601 (Several epiweeks)
  • param=200501-200552 (A range of epiweeks)
  • param=201440,201501-201510 (Several epiweeks, including a range)
  • param=20070101-20071231 (A range of dates)

Universal Parameters

The only universally required parameter is source, which must be one of: fluview, ilinet, nowcast, gft, twitter, wiki, nidss_flu, or nidss_dengue

FluView Parameters

Required:

  • epiweeks: a list of epiweeks
  • regions: a list of region labels

Optional:

  • issues: a list of epiweeks
  • lag: a number of weeks
  • auth: the password for private imputed data

ILI-Nearby Parameters

Required:

  • epiweeks: a list of epiweeks
  • locations: a list of region/state labels

GFT Parameters

Required:

  • epiweeks: a list of epiweeks
  • locations: a list of region/state/city labels

Twitter Parameters

Required:

  • auth: an authorization token
  • locations: a list of region/state labels

Require one of:

  • dates: a list of dates
  • epiweeks: a list of epiweeks

Wiki Parameters

Required:

  • articles: a list of article labels

Require one of:

  • dates: a list of dates
  • epiweeks: a list of epiweeks

Optional:

  • hours: a list of hours

NIDSS-Flu Parameters

Required:

  • epiweeks: a list of epiweeks
  • regions: a list of region labels

Optional:

  • issues: a list of epiweeks
  • lag: a number of weeks

NIDSS-Dengue Parameters

Required:

  • epiweeks: a list of epiweeks
  • locations: a list of region and/or location labels

Example URLs

FluView/GFT/Twitter on 2015w01 (national)

Wiki article "influenza" on 2015w01

https://delphi.midas.cs.cmu.edu/epidata/api.php?source=wiki&articles=influenza&epiweeks=201501

{"result":1,"epidata":[{"article":"influenza","count":30819,"hour":-1,"epiweek":201501}],"message":"success"}

FluView in HHS Regions 4 and 6 for the 2014/2015 flu season

https://delphi.midas.cs.cmu.edu/epidata/api.php?source=fluview&regions=hhs4,hhs6&epiweeks=201440-201520

Updates to FluView on 2014w53, reported from 2015w01 through 2015w10 (national)

https://delphi.midas.cs.cmu.edu/epidata/api.php?source=fluview&regions=nat&epiweeks=201453&issues=201501-201510

NIDSS-Flu on 2015w01 (national)

https://delphi.midas.cs.cmu.edu/epidata/api.php?source=nidss_flu&regions=Nationwide&epiweeks=201501

{"result":1,"epidata":[{"release_date":"2015-08-04","region":"Nationwide","issue":201530,"epiweek":201501,"lag":29,"visits":65685,"ili":1.21}],"message":"success"}

NIDSS-Dengue on 2015w01 (national)

https://delphi.midas.cs.cmu.edu/epidata/api.php?source=nidss_dengue&locations=Nationwide&epiweeks=201501

{"result":1,"epidata":[{"location":"nationwide","epiweek":201501,"count":20}],"message":"success"}

Code Samples

Libraries are available for CoffeeScript, JavaScript, Python, and R. The following samples show how to import the library and fetch national FluView data for epiweeks 201440 and 201501-201510 (11 weeks total).

CoffeeScript (in Node.js)

# Import
{Epidata} = require('./delphi_epidata')
# Fetch data
callback = (result, message, epidata) ->
  console.log(result, message, epidata?.length)
Epidata.fluview(callback, ['nat'], [201440, Epidata.range(201501, 201510)])

JavaScript (in a web browser)

<!-- Imports -->
<script src="jquery.js"></script>
<script src="delphi_epidata.js"></script>
<!-- Fetch data -->
<script>
  var callback = function(result, message, epidata) {
    console.log(result, message, epidata != null ? epidata.length : void 0);
  };
  Epidata.fluview(callback, ['nat'], [201440, Epidata.range(201501, 201510)]);
</script>

Python

# Import
from delphi_epidata import Epidata
# Fetch data
res = Epidata.fluview(['nat'], [201440, Epidata.range(201501, 201510)])
print(res['result'], res['message'], len(res['epidata']))

R

# Import
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"))

References

  • Cook, Samantha, et al. "Assessing Google flu trends performance in the United States during the 2009 influenza virus A (H1N1) pandemic." PloS one 6.8 (2011): e23610.
  • Broniatowski, David A., Michael J. Paul, and Mark Dredze. "National and local influenza surveillance through Twitter: an analysis of the 2012-2013 influenza epidemic." (2013): e83672.
  • Dredze, Mark, et al. "HealthTweets. org: A Platform for Public Health Surveillance using Twitter." AAAI Conference on Artificial Intelligence. 2014.
  • Generous, Nicholas, et al. "Global disease monitoring and forecasting with Wikipedia." (2014): e1003892.
  • Hickmann, Kyle S., et al. "Forecasting the 2013–2014 Influenza Season Using Wikipedia." (2015): e1004239.
  • McIver, David J., and John S. Brownstein. "Wikipedia usage estimates prevalence of influenza-like illness in the United States in near real-time." PLoS Comput Biol 10.4 (2014): e1003581.