Link Search Menu Expand Document

Google Flu Trends

This is the documentation of the API for accessing the Google Flu Trends (gft) data source of the Delphi’s epidemiological data.

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

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

The API

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

See this documentation for details on specifying epiweeks, dates, and lists.

Parameters

Required

Parameter Description Type
epiweeks epiweeks list of epiweeks
locations locations list of region/state/city labels

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 string
epidata[].epiweek epiweek epiweek
epidata[].num number integer
message success or error message string

Example URLs

https://delphi.cmu.edu/epidata/api.php?source=gft&locations=nat&epiweeks=201501

{
  "result": 1,
  "epidata": [
    {
      "location": "nat",
      "epiweek": 201501,
      "num": 4647
    }
  ],
  "message": "success"
}

Code Samples

Libraries are available for CoffeeScript, JavaScript, Python, and R. The following samples show how to import the library and fetch Google Flu Trends 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.gft(callback, ['nat'], [201440, Epidata.range(201501, 201510)]);
</script>

Python

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.gft(['nat'], [201440, Epidata.range(201501, 201510)])
print(res['result'], res['message'], len(res['epidata']))

R

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