Merge pull request #550 from cmu-delphi/sgratzl/docs_covidcast2.0

update docs for flask server

Author: sgratzl

docs/api/README.md

@@ -70,7 +70,7 @@ Please note that our `endpoint` parameters were previously referenced as `source
 
 # The API
 
-The base URL is: https://delphi.cmu.edu/epidata/api.php
+The base URL is: https://delphi.cmu.edu/epidata/
 
 ## Specifying Epiweeks, Dates, and Lists
 
@@ -154,7 +154,7 @@ The parameters available for each source are documented in each linked source-sp
 # Example URLs
 
 ### FluView on 2015w01 (national)
-https://delphi.cmu.edu/epidata/api.php?endpoint=fluview&regions=nat&epiweeks=201501
+https://delphi.cmu.edu/epidata/fluview/?regions=nat&epiweeks=201501
 
 ```json
 {
@@ -184,7 +184,7 @@ https://delphi.cmu.edu/epidata/api.php?endpoint=fluview&regions=nat&epiweeks=201
 ```
 
 ### Wikipedia Access article "influenza" on 2020w01
-https://delphi.cmu.edu/epidata/api.php?endpoint=wiki&language=en&articles=influenza&epiweeks=202001
+https://delphi.cmu.edu/epidata/wiki/?language=en&articles=influenza&epiweeks=202001
 
 ```json
 {

docs/api/afhsb.md

@@ -19,7 +19,7 @@ General topics not specific to any particular endpoint are discussed in the
 
 # The API
 
-The base URL is: https://delphi.cmu.edu/epidata/api.php
+The base URL is: https://delphi.cmu.edu/epidata/afhsb/
 
 See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
 

docs/api/cdc.md

@@ -19,7 +19,7 @@ General topics not specific to any particular endpoint are discussed in the
 
 # The API
 
-The base URL is: https://delphi.cmu.edu/epidata/api.php
+The base URL is: https://delphi.cmu.edu/epidata/cdc/
 
 See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
 

docs/api/client_libraries.md

@@ -7,7 +7,6 @@ nav_order: 1
 # Epidata API Client Libraries.
 
 Epidata clients are available for
-[CoffeeScript](https://github.com/cmu-delphi/delphi-epidata/blob/master/src/client/delphi_epidata.coffee),
 [JavaScript](https://github.com/cmu-delphi/delphi-epidata/blob/master/src/client/delphi_epidata.js),
 [Python](https://github.com/cmu-delphi/delphi-epidata/blob/master/src/client/delphi_epidata.py),
 and
@@ -18,29 +17,16 @@ Surveillance Streams from Facebook Survey CLI for county 06001 and days
 
 For anyone looking for COVIDCast data, please visit our [COVIDCast Libraries](covidcast_clients.md).
 
-### CoffeeScript (in Node.js)
-
-````coffeescript
-# Import
-{Epidata} = require('./delphi_epidata')
-# Fetch data
-callback = (result, message, epidata) ->
-  console.log(result, message, epidata?.length)
-Epidata.covidcast(callback, 'fb-survey', 'smoothed_cli', 'day', 'county', [20200401, Epidata.range(20200405, 20200414)], '06001')
-````
-
 ### JavaScript (in a web browser)
 
 ````html
 <!-- 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.covidcast(callback, 'fb-survey', 'smoothed_cli', 'day', 'county', [20200401, Epidata.range(20200405, 20200414)], '06001');
+  EpidataAsync.covidcast('fb-survey', 'smoothed_cli', 'day', 'county', [20200401, Epidata.range(20200405, 20200414)], '06001').then((res) => {
+    console.log(res.result, res.message, res.epidata != null ? res.epidata.length : 0);
+  });
 </script>
 ````
 

docs/api/covid_hosp.md

@@ -6,14 +6,14 @@ parent: Epidata API (Other Diseases)
 # COVID-19 Hospitalization by State
 
 This data source is a mirror of the "COVID-19 Reported Patient Impact and
-Hospital Capacity by State Timeseries" and "COVID-19 Reported Patient Impact and 
+Hospital Capacity by State Timeseries" and "COVID-19 Reported Patient Impact and
 Hospital Capacity by State" datasets provided by the US Department of
 Health & Human Services via healthdata.gov. The latter provides more frequent updates,
 so it is combined with the former to create a single dataset which is as recent as possible.
 
 For more information, see the
 [official description and data dictionary at healthdata.gov](https://healthdata.gov/Hospital/COVID-19-Reported-Patient-Impact-and-Hospital-Capa/g62h-syeh)
-for "COVID-19 Reported Patient Impact and Hospital Capacity by State Timeseries," 
+for "COVID-19 Reported Patient Impact and Hospital Capacity by State Timeseries,"
 as well as the [official description](https://healthdata.gov/dataset/COVID-19-Reported-Patient-Impact-and-Hospital-Capa/6xf2-c3ie)
 for "COVID-19 Reported Patient Impact and Hospital Capacity by State."
 
@@ -72,7 +72,7 @@ If `issues` is not specified, then the most recent issue is used by default.
 # Example URLs
 
 ### MA on 2020-05-10 (per most recent issue)
-https://delphi.cmu.edu/epidata/api.php?endpoint=covid_hosp&states=MA&dates=20200510
+https://delphi.cmu.edu/epidata/covid_hosp/?states=MA&dates=20200510
 
 ```json
 {
@@ -143,7 +143,7 @@ https://delphi.cmu.edu/epidata/api.php?endpoint=covid_hosp&states=MA&dates=20200
 
 # Code Samples
 
-Libraries are available for [CoffeeScript](../../src/client/delphi_epidata.coffee), [JavaScript](../../src/client/delphi_epidata.js), [Python](../../src/client/delphi_epidata.py), and [R](../../src/client/delphi_epidata.R).
+Libraries are available for [JavaScript](../../src/client/delphi_epidata.js), [Python](../../src/client/delphi_epidata.py), and [R](../../src/client/delphi_epidata.R).
 The following sample shows how to import the library and fetch MA on 2020-05-10
 (per most recent issue).
 

docs/api/covid_hosp_facility.md

@@ -30,7 +30,7 @@ HHS. New versions are expected to be published roughly weekly.
 
 # The API
 
-The base URL is: https://delphi.cmu.edu/epidata/api.php
+The base URL is: https://delphi.cmu.edu/epidata/covid_hosp_facility/
 
 See [this documentation](README.md) for details on specifying locations and dates.
 
@@ -80,7 +80,7 @@ has been renamed here for clarity.
 # Example URLs
 
 ### Moses Taylor Hospital (Scranton, PA) on the first collection week of December 2020 (per most recent issue)
-https://delphi.cmu.edu/epidata/api.php?source=covid_hosp_facility&hospital_pks=390119&collection_weeks=20201201-20201207
+https://delphi.cmu.edu/epidata/covid_hosp_facility/?hospital_pks=390119&collection_weeks=20201201-20201207
 
 ```json
 {
@@ -190,7 +190,7 @@ https://delphi.cmu.edu/epidata/api.php?source=covid_hosp_facility&hospital_pks=3
 
 # Code Samples
 
-Libraries are available for [CoffeeScript](../../src/client/delphi_epidata.coffee), [JavaScript](../../src/client/delphi_epidata.js), [Python](../../src/client/delphi_epidata.py), and [R](../../src/client/delphi_epidata.R).
+Libraries are available for [JavaScript](../../src/client/delphi_epidata.js), [Python](../../src/client/delphi_epidata.py), and [R](../../src/client/delphi_epidata.R).
 The following sample shows how to import the library and fetch Moses Taylor
 Hospital (Scranton, PA) on the first collection week of December 2020 (per most
 recent issue).

docs/api/covid_hosp_facility_lookup.md

@@ -30,7 +30,7 @@ This data source provides metadata about healthcare facilities in the US.
 
 # The API
 
-The base URL is: https://delphi.cmu.edu/epidata/api.php?source=covid_hosp_facility_lookup
+The base URL is: https://delphi.cmu.edu/epidata/covid_hosp_facility_lookup/
 
 See [this documentation](README.md) for details on specifying locations and dates.
 
@@ -61,7 +61,7 @@ supported.
 # Example URLs
 
 ### Lookup facilities in the city of Southlake (TX)
-https://delphi.cmu.edu/epidata/api.php?source=covid_hosp_facility_lookup&city=southlake
+https://delphi.cmu.edu/epidata/covid_hosp_facility_lookup/?city=southlake
 
 ```json
 {
@@ -99,7 +99,7 @@ https://delphi.cmu.edu/epidata/api.php?source=covid_hosp_facility_lookup&city=so
 
 # Code Samples
 
-Libraries are available for [CoffeeScript](../../src/client/delphi_epidata.coffee), [JavaScript](../../src/client/delphi_epidata.js), [Python](../../src/client/delphi_epidata.py), and [R](../../src/client/delphi_epidata.R).
+Libraries are available for [JavaScript](../../src/client/delphi_epidata.js), [Python](../../src/client/delphi_epidata.py), and [R](../../src/client/delphi_epidata.R).
 The following sample shows how to import the library and fetch facilities in
 the city of Southlake (TX).
 

docs/api/covidcast.md

@@ -9,7 +9,7 @@ nav_order: 1
 This is the documentation for accessing Delphi's COVID-19 indicators via the `covidcast` endpoint of [Delphi](https://delphi.cmu.edu/)'s
 epidemiological data API. This API provides data on the spread and impact of the COVID-19 pandemic across the United States, most of which is available at the
 county level and updated daily. This data powers our public [COVIDcast
-map](https://covidcast.cmu.edu/) which includes testing, cases, and death data,
+map](https://delphi.cmu.edu/covidcast/) which includes testing, cases, and death data,
 as well as unique healthcare and survey data Delphi acquires through its
 partners. The API allows users to select specific signals and download data for
 selected geographical areas---counties, states, metropolitan statistical areas,
@@ -43,7 +43,7 @@ in the [API overview](README.md).
 
 ## Accessing the Data
 
-Our [COVIDcast site](https://covidcast.cmu.edu) provides an interactive
+Our [COVIDcast site](https://delphi.cmu.edu/covidcast/) provides an interactive
 visualization of a select set of the data signals available in the COVIDcast
 API, and provides a data export feature to download any data range as a
 CSV file.
@@ -92,8 +92,7 @@ sources and signals.
 ## Constructing API Queries
 
 The COVIDcast API is based on HTTP GET queries and returns data in JSON form.
-The base URL is `https://api.covidcast.cmu.edu/epidata/api.php`.  The covidcast
-endpoint is `https://api.covidcast.cmu.edu/epidata/api.php?endpoint=covidcast`.
+The base URL is `https://api.covidcast.cmu.edu/epidata/covidcast/`.
 
 See [this documentation](README.md) for details on specifying epiweeks, dates,
 and lists.
@@ -139,10 +138,10 @@ Use cases:
   do not include any updates that became available after June 1, use
   `as_of=20200601`.
 * To retrieve only data that was published or updated on June 1, and exclude
-  records whose most recent update occured earlier than June 1, use
+  records whose most recent update occurred earlier than June 1, use
   `issues=20200601`.
 * To retrieve all data that was published between May 1 and June 1, and exclude
-  records whose most recent update occured earlier than May 1, use
+  records whose most recent update occurred earlier than May 1, use
   `issues=20200501-20200601`. The results will include all matching issues for
   each `time_value`, not just the most recent.
 * To retrieve only data that was published or updated exactly 3 days after the
@@ -160,11 +159,15 @@ require knowing when we last confirmed an unchanged value, please get in touch.
 | --- | --- | --- |
 | `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
 | `epidata` | list of results, 1 per geo/time pair | array of objects |
+| `epidata[].source` | selected `data_source` | string |
+| `epidata[].signal` | selected `signal` | string |
+| `epidata[].geo_type` | selected `geo_type` | string |
 | `epidata[].geo_value` | location code, depending on `geo_type` | string |
+| `epidata[].time_type` | selected `time_type` | string |
 | `epidata[].time_value` | time unit (e.g. date) over which underlying events happened (see [date coding details](covidcast_times.md)) | integer |
-| `epidata[].direction` | trend classifier (+1 -> increasing, 0 -> steady or not determined, -1 -> decreasing) | integer |
 | `epidata[].value` | value (statistic) derived from the underlying data source | float |
 | `epidata[].stderr` | approximate standard error of the statistic with respect to its sampling distribution, `null` when not applicable | float |
+| `epidata[].direction` | trend classifier (+1 -> increasing, 0 -> steady or not determined, -1 -> decreasing) | integer |
 | `epidata[].sample_size` | number of "data points" used in computing the statistic, `null` when not applicable | float |
 | `epidata[].issue` | time unit (e.g. date) when this statistic was published | integer |
 | `epidata[].lag` | time delta (e.g. days) between when the underlying events happened and when this statistic was published | integer |
@@ -179,11 +182,32 @@ returned, but not all of the results you requested. API clients should check the
 results code and consider breaking up requests for e.g. large time intervals into multiple
 API calls.
 
+### Alternative Response Formats
+
+In addition to the default EpiData Response format, users can customize the response format using the `format=` parameter.
+
+#### JSON List Response
+
+When setting the format parameter to `format=json`, it will return a plain list of the `epidata` response objects without the `result` and `message` wrapper. The status of the query is returned via HTTP status codes. For example, a status code of 200 means the query succeeded, while 400 indicates that the query has a missing, misspelled, or otherwise invalid parameter. For all status codes != 200, the returned JSON includes details about what part of the query couldn't be interpreted.
+
+#### CSV File Response
+
+When setting the format parameter to `format=csv`, it will return a CSV file with same columns as the response objects. HTTP status codes are used to communicate success/failure, similar to `format=json`.
+
+#### JSON New Lines Response
+
+When setting the format parameter to `format=jsonl`, it will return each row as an JSON file separated by a single new line character `\n`. This format is useful for incremental streaming of the results. Similar to the JSON list response status codes are used.
+
+### Limit Returned Fields
+
+The `fields` parameter can be used to limit which fields are included in each returned row. This is useful in web applications to reduce the amount of data transmitted. The `fields` parameter supports two syntaxes: allow and deny. Using allowlist syntax, only the listed fields will be returned. For example, `fields=geo_value,value` will drop all fields from the returned data except for `geo_value` and `value`. To use denylist syntax instead, prefix each field name with a dash (-) to exclude it from the results. For example, `fields=-direction` will include all fields in the returned data except for the `direction` field.
+
+
 ## Example URLs
 
 ### Facebook Survey CLI on 2020-04-06 to 2010-04-10 (county 06001)
 
-https://api.covidcast.cmu.edu/epidata/api.php?endpoint=covidcast&data_source=fb-survey&signal=smoothed_cli&time_type=day&geo_type=county&time_values=20200406-20200410&geo_value=06001
+https://api.covidcast.cmu.edu/epidata/covidcast/?data_source=fb-survey&signal=smoothed_cli&time_type=day&geo_type=county&time_values=20200406-20200410&geo_value=06001
 
 ```json
 {
@@ -205,7 +229,7 @@ https://api.covidcast.cmu.edu/epidata/api.php?endpoint=covidcast&data_source=fb-
 
 ### Facebook Survey CLI on 2020-04-06 (all counties)
 
-https://api.covidcast.cmu.edu/epidata/api.php?endpoint=covidcast&data_source=fb-survey&signal=smoothed_cli&time_type=day&geo_type=county&time_values=20200406&geo_value=*
+https://api.covidcast.cmu.edu/epidata/covidcast/?data_source=fb-survey&signal=smoothed_cli&time_type=day&geo_type=county&time_values=20200406&geo_value=*
 
 ```json
 {

docs/api/covidcast_meta.md

@@ -13,7 +13,7 @@ geographic levels at which they are reported.
 
 ## The API
 
-The base URL is: https://api.covidcast.cmu.edu/epidata/api.php
+The base URL is: https://api.covidcast.cmu.edu/epidata/covidcast_meta/
 
 See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
 
@@ -45,7 +45,7 @@ None required.
 
 ## Example URLs
 
-https://api.covidcast.cmu.edu/epidata/api.php?endpoint=covidcast_meta
+https://api.covidcast.cmu.edu/epidata/covidcast_meta/
 
 ```json
 {
@@ -73,32 +73,19 @@ https://api.covidcast.cmu.edu/epidata/api.php?endpoint=covidcast_meta
 
 ## Code Samples
 
-Libraries are available for [CoffeeScript](../../src/client/delphi_epidata.coffee), [JavaScript](../../src/client/delphi_epidata.js), [Python](../../src/client/delphi_epidata.py), and [R](../../src/client/delphi_epidata.R).
+Libraries are available for [JavaScript](../../src/client/delphi_epidata.js), [Python](../../src/client/delphi_epidata.py), and [R](../../src/client/delphi_epidata.R).
 The following samples show how to import the library and fetch Delphi's COVID-19 Surveillance Streams metadata.
 
-### CoffeeScript (in Node.js)
-
-````coffeescript
-# Import
-{Epidata} = require('./delphi_epidata')
-# Fetch data
-callback = (result, message, epidata) ->
-  console.log(result, message, epidata?.length)
-Epidata.covidcast_meta(callback)
-````
-
 ### JavaScript (in a web browser)
 
 ````html
 <!-- 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.covidcast_meta(callback);
+  EpidataAsync.covidcast_meta().then((res) => {
+    console.log(res.result, res.message, res.epidata != null ? res.epidata.length : 0);
+  });
 </script>
 ````
 

docs/api/delphi.md

@@ -19,7 +19,7 @@ General topics not specific to any particular endpoint are discussed in the
 
 # The API
 
-The base URL is: https://delphi.cmu.edu/epidata/api.php
+The base URL is: https://delphi.cmu.edu/epidata/delphi/
 
 See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
 
@@ -58,7 +58,7 @@ See [this documentation](README.md) for details on specifying epiweeks, dates, a
 # Example URLs
 
 ### Delphi on 2020w01 (EC)
-https://delphi.cmu.edu/epidata/api.php?endpoint=delphi&system=ec&epiweek=202001
+https://delphi.cmu.edu/epidata/delphi/?system=ec&epiweek=202001
 
 ```json
 {

docs/api/dengue_nowcast.md

@@ -20,7 +20,7 @@ General topics not specific to any particular endpoint are discussed in the
 
 # The API
 
-The base URL is: https://delphi.cmu.edu/epidata/api.php
+The base URL is: https://delphi.cmu.edu/epidata/dengue_nowcast/
 
 See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
 

docs/api/dengue_sensors.md

@@ -20,7 +20,7 @@ General topics not specific to any particular endpoint are discussed in the
 
 # The API
 
-The base URL is: https://delphi.cmu.edu/epidata/api.php
+The base URL is: https://delphi.cmu.edu/epidata/dengue_sensors/
 
 See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
 

docs/api/ecdc_ili.md

@@ -19,7 +19,7 @@ ECDC ILI data from ECDC website. ... <!-- TODO -->
 
 # The API
 
-The base URL is: https://delphi.cmu.edu/epidata/api.php
+The base URL is: https://delphi.cmu.edu/epidata/ecdc_ili/
 
 See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.