Google Flu Trends

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

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

Google Flu Trends Data

Estimate of influenza activity based on volume of certain search queries. Google has discontinued Flu Trends, and this is now a static endpoint.

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://api.delphi.cmu.edu/epidata/gft/

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

Google Flu Trends on 2015w01 (national)

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

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

Code Samples

Libraries are available for 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).

JavaScript (in a web browser)

<!-- Imports -->
<script src="delphi_epidata.js"></script>
<!-- Fetch data -->
<script>
  EpidataAsync.gft('nat', [201440, EpidataAsync.range(201501, 201510)]).then((res) => {
    console.log(res.result, res.message, res.epidata != null ? res.epidata.length : 0);
  });
</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"))