Epidata Metadata

This is the documentation of the API for accessing the API Metadata (meta) for fluview, twitter, wiki, and delphi endpoints of the 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.

API Metadata

Overview of the current state of the database, including the latest update times and data volume for specific endpoints.

The API

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

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

Parameters

None.

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[].fluview	Metadata for FluView	array of objects
epidata[].twitter	Metadata for Twitter	array of objects
epidata[].wiki	Metadata for Wikipedia	array of objects
epidata[].delphi	Metadata for Delphi Forecasts	array of objects
message	success or error message	string

Example URLs

https://api.delphi.cmu.edu/epidata/meta/

{
  "result": 1,
  "epidata": [
    {
      "fluview": [
        {
          "latest_update": "2020-04-10",
          "latest_issue": 202014,
          "table_rows": 945920
        }
      ],
      "twitter": [
        {
          "latest_update": "2020-04-11",
          "num_states": 41,
          "table_rows": 132712
        }
      ],
      "wiki": [
        {
          "latest_update": "2020-04-12 07:00:00",
          "table_rows": 131585
        }
      ],
      "delphi": [
        {
          "system": "af",
          "first_week": 201541,
          "last_week": 201619,
          "num_weeks": 31
        },
        {
          "system": "eb",
          "first_week": 201441,
          "last_week": 201519,
          "num_weeks": 32
        },
        {
          "system": "ec",
          "first_week": 201441,
          "last_week": 202013,
          "num_weeks": 171
        },
        {
          "system": "sp",
          "first_week": 201441,
          "last_week": 201519,
          "num_weeks": 32
        },
        {
          "system": "st",
          "first_week": 201542,
          "last_week": 201949,
          "num_weeks": 123
        }
      ]
    }
  ],
  "message": "success"
}

Code Samples

Libraries are available for R and Python. The following samples show how to import the library and fetch API metadata.

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.pub_meta()
print(res)

library(epidatr)
# Fetch data
res <- pub_meta()
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.meta()
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$meta()
print(res$message)
print(length(res$epidata))

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