docs: Complete the "Other endpoints" documentation #1703
Conversation
nmdefries
left a comment
nmdefries
left a comment
There was a problem hiding this comment.
Want more detailed info for some of these. Overall structure, headers, etc look good. I made some small wording changes, will push those in a minute.
| | :--- | :--- | | ||
| | **Source Name** | `cdc` | | ||
| | **Data Source** | CDC influenza surveillance data | | ||
| | **Geographic Levels** | National, HHS regions, Census divisions, and US states (see [Geographic Codes](geographic_codes.html#us-regions-and-states)) | |
There was a problem hiding this comment.
suggestion: names/abbreviations should match whatever we do here
| | `auth` | password | string | | ||
| | `epiweeks` | epiweeks | `list` of epiweeks | | ||
| | `locations` | locations | `list` of [region](https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/regions.txt)/[state](https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/states.txt) labels <!-- TODO: check --> | | ||
| | `epiweeks` | epiweeks (see [Date Formats](date_formats.html)) | `list` of epiweeks | |
There was a problem hiding this comment.
issue: internal links should use .md ending. (It looks like the .html links actually do work, but I believe special link rendering specified in the headers could break them.)
docs/api/cdc.md
Outdated
| | `epidata` | list of results | array of objects | | ||
| | `epidata[].location` | location label | string | | ||
| | `epidata[].epiweek` | epiweek | integer | | ||
| | `epidata[].num1` | number of hits for datasource 1 | integer | |
There was a problem hiding this comment.
issue: need more detail here (e.g. what is datasource 1?), see these column definitions.
docs/api/cdc.md
Outdated
| ## Overview | ||
| {: .no_toc} | ||
|
|
||
| This data source provides CDC-collected influenza surveillance data from various sources. |
There was a problem hiding this comment.
issue: I already made a V1 improvement of this, but in general the overview blurbs should say where the raw data is from, and what we report. It needs to be specific enough that a user can tell if it will be relevant to them. So "surveillance data" is too broad -- that could be from a direct survey, a summary of hospital reports, mobile phone/GPS tracking, etc. What we report could be ILI counts, etc.
Actually, we have some info about the endpoints summarized here, and about the fields they report here. We can probably copy some of that over. Let me know if you don't have access. Sorry I didn't think to share this sooner!
There was a problem hiding this comment.
Overview could also include more depth (when we think this would be/would not be useful to a user, known issues, recommendations for similar but better data sets, etc), but for these older datasets we don't really know that much. So if you see comments about that in the code for each endpoint, feel free to include, but no big deal if it's not available.
|
|
||
| | Code | Name | | ||
| | :--- | :--- | | ||
| | `af` | [Archefilter](http://reports-archive.adm.cs.cmu.edu/anon/cbd/CMU-CB-16-101.pdf#Appendix.1.B) | |
There was a problem hiding this comment.
praise: very nice to have all of these defined and with links!
| | `epidata[].location` | location label | string | | ||
| | `epidata[].date` | date (yyyy-MM-dd) | string | | ||
| | `epidata[].epiweek` | epiweek | integer | | ||
| | `epidata[].num` | number of tweets | integer | |
There was a problem hiding this comment.
issue: number meeting what criteria? More specific is better (e.g. any tweet with the word "flu"), although since the source is down I'm not sure we know this. Possibly in our code.
| {:toc} | ||
|
|
||
| {: .note} | ||
| > **Note:** Restricted access: Delphi doesn't have permission to share this dataset. |
There was a problem hiding this comment.
thought: we have several sources that we can't share externally, but for many of them the only indication of that on the doc page is that "auth" is included as an API parameter. Most don't have a note like this. It would be good to note access restrictions more clearly and consistently. Likely a followup issue.
| | `epidata[].count` | number of pageviews | integer | | ||
| | `epidata[].total` | total pageviews | integer | |
There was a problem hiding this comment.
issue: what's the difference between these?
| | `epidata[].date` | date (yyyy-MM-dd) (only included if `date` used) | string | | ||
| | `epidata[].epiweek` | epiweek (only included if `epiweek` used) | integer | | ||
| | `epidata[].value` | | float | | ||
| | `epidata[].value` | normalized pageview count | float | |
There was a problem hiding this comment.
issue: normalized by what?
| @@ -0,0 +1,467 @@ | |||
| --- | |||
| title: Geographic Codes | |||
There was a problem hiding this comment.
praise: this doc is great to have! Thanks for putting it together. Much better reference than pointing to the code.
|
addresses issue(s) #1517, #1209, #1518, #1520, #1670
Summary:
This PR updates the documentation for the “Other endpoints", superseding the corresponding changes made in #1697.
Prerequisites:
devbranchdev