Merge pull request #93 from dfarrow0/master

add `fluview_meta` endpoint

Author: undefx

docs/api/README.md

@@ -102,6 +102,7 @@ The parameters available for each source are documented in each linked source-sp
 | [`ecdc_ili`](ecdc_ili.md) | ECDC ILI | ECDC ILI data from the ECDC website. | no |
 | [`flusurv`](flusurv.md) | FluSurv | FluSurv-NET data (flu hospitaliation rates) from CDC. | no |
 | [`fluview`](fluview.md) | FluView | Influenza-like illness (ILI) from U.S. Outpatient Influenza-like Illness Surveillance Network (ILINet). | no |
+| [`fluview_meta`](fluview_meta.md) | FluView Metadata | Summary data about [`fluview`](fluview.md). | no |
 | [`fluview_clinical`](fluview_clinical.md) | FluView Clinical | ... <!-- TODO --> | no |
 | [`gft`](gft.md) | 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. | no |
 | [`ght`](ght.md) | Google Health Trends | Estimate of influenza activity based on volume of certain search queries. | yes |

docs/api/fluview_meta.md

@@ -0,0 +1,54 @@
+# About
+
+This is the documentation of the API for accessing the FluView metadata
+(`fluview_meta`) data source of [Delphi](https://delphi.cmu.edu/)'s
+epidemiological data.
+
+General topics not specific to any particular data source are discussed in the
+[API overview](README.md). Such topics include:
+[contributing](README.md#contributing), [citing](README.md#citing), and
+[data licensing](README.md#data-licensing).
+
+## FluView Metadata
+
+Returns information about the [`fluview` endpoint](fluview.md).
+
+# The API
+
+The base URL is: https://delphi.cmu.edu/epidata/api.php
+
+See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
+
+## Parameters
+
+There are no parameters for this endpoint.
+
+## 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[].latest_update` | date when data was last updated | string |
+| `epidata[].latest_issue` | most recent "issue" (epiweek) in the data | integer |
+| `epidata[].table_rows` | total number of rows in the table | integer |
+| `message` | `success` or error message | string |
+
+# Example URLs
+
+### FluView Metadata
+https://delphi.cmu.edu/epidata/api.php?source=fluview_meta
+
+```json
+{
+  "result": 1,
+  "epidata": [
+    {
+      "latest_update": "2020-04-24",
+      "latest_issue": 202016,
+      "table_rows": 957673
+    }
+  ],
+  "message": "success"
+}
+```

integrations/server/test_fluview_meta.py

@@ -0,0 +1,71 @@
+"""Integration tests for the `fluview_meta` endpoint."""
+
+# standard library
+import unittest
+
+# third party
+import mysql.connector
+
+# first party
+from delphi.epidata.client.delphi_epidata import Epidata
+
+
+class FluviewMetaTests(unittest.TestCase):
+  """Tests the `fluview_meta` endpoint."""
+
+  @classmethod
+  def setUpClass(cls):
+    """Perform one-time setup."""
+
+    # use the local instance of the Epidata API
+    Epidata.BASE_URL = 'http://delphi_web_epidata/epidata/api.php'
+
+  def setUp(self):
+    """Perform per-test setup."""
+
+    # connect to the `epidata` database and clear the `fluview` table
+    cnx = mysql.connector.connect(
+        user='user',
+        password='pass',
+        host='delphi_database_epidata',
+        database='epidata')
+    cur = cnx.cursor()
+    cur.execute('truncate table fluview')
+    cnx.commit()
+    cur.close()
+
+    # make connection and cursor available to test cases
+    self.cnx = cnx
+    self.cur = cnx.cursor()
+
+  def tearDown(self):
+    """Perform per-test teardown."""
+    self.cur.close()
+    self.cnx.close()
+
+  def test_round_trip(self):
+    """Make a simple round-trip with some sample data."""
+
+    # insert dummy data
+    self.cur.execute('''
+      insert into fluview values
+        (0, "2020-04-07", 202021, 202020, "nat", 1, 2, 3, 4, 3.14159, 1.41421,
+          10, 11, 12, 13, 14, 15),
+        (0, "2020-04-28", 202022, 202022, "hhs1", 5, 6, 7, 8, 1.11111, 2.22222,
+          20, 21, 22, 23, 24, 25)
+    ''')
+    self.cnx.commit()
+
+    # make the request
+    response = Epidata.fluview_meta()
+
+    # assert that the right data came back
+    self.assertEqual(response, {
+      'result': 1,
+      'epidata': [{
+         'latest_update': '2020-04-28',
+         'latest_issue': 202022,
+         'table_rows': 2,
+       }],
+      'message': 'success',
+    })

src/client/delphi_epidata.R

@@ -76,6 +76,16 @@ Epidata <- (function() {
     return(.request(params))
   }
 
+  # Fetch FluView metadata
+  fluview_meta <- function() {
+    # Set up request
+    params <- list(
+      source = 'fluview_meta'
+    )
+    # Make the API call
+    return(.request(params))
+  }
+
   # Fetch FluView virological data
   fluview_clinical <- function(regions, epiweeks, issues, lag) {
     # Check parameters
@@ -521,6 +531,7 @@ Epidata <- (function() {
   return(list(
     range = range,
     fluview = fluview,
+    fluview_meta = fluview_meta,
     fluview_clinical = fluview_clinical,
     flusurv = flusurv,
     gft = gft,

src/client/delphi_epidata.coffee

@@ -82,7 +82,16 @@ class Epidata
       params.auth = auth
     # Make the API call
     _request(callback, params)
-  
+
+
+  # Fetch FluView metadata
+  @fluview_meta: (callback) ->
+    # Set up request
+    params =
+      'source': 'fluview_meta'
+    # Make the API call
+    _request(callback, params)
+
   # Fetch FluView clinical data
   @fluview_clinical: (callback, regions, epiweeks, issues, lag) ->
     # Check parameters

src/client/delphi_epidata.js

@@ -88,6 +88,17 @@ def fluview(regions, epiweeks, issues=None, lag=None, auth=None):
     # Make the API call
     return Epidata._request(params)
 
+  # Fetch FluView metadata
+  @staticmethod
+  def fluview_meta():
+    """Fetch FluView metadata."""
+    # Set up request
+    params = {
+      'source': 'fluview_meta',
+    }
+    # Make the API call
+    return Epidata._request(params)
+
   # Fetch FluView clinical data
   @staticmethod
   def fluview_clinical(regions, epiweeks, issues=None, lag=None):

src/client/delphi_epidata.py

@@ -1134,6 +1134,10 @@ function meta_delphi() {
       $epidata = get_fluview($epiweeks, $regions, $issues, $lag, $authorized);
       store_result($data, $epidata);
     }
+  } else if($source === 'fluview_meta') {
+    // get the data
+    $epidata = meta_fluview();
+    store_result($data, $epidata);
   } else if ($source === 'fluview_clinical') {
     if(require_all($data, array('epiweeks', 'regions'))) {
       // parse the request