Missing documentation for some API fields on https://covidtracking.com/api

[julia326]

There are some fields that have been confusing folks, especially the cumulative/current ICU/vent/hospitalization counts. Some of these have been hidden from the website (e.g. from US Daily) but we're still serving them in the API and they're not documented on https://covidtracking.com/api.

(These fields are more urgent than others, but it would be great to make sure we document every API field we serve on our /api page)

[gitjeff05]

I could be mistaken, but I believe these statistics are no longer tracked: These are no longer aggregated at the US level but are still included at the state level.

I agree these should be documented with attention to the caveats shown on the data page:

States are currently reporting two fundamentally unlike statistics: current hospital/ICU admissions and cumulative hospitalizations/ICU admissions. Across the country, this reporting is also sparse. In short: it is impossible to assemble anything resembling the real statistics for hospitalizations, ICU admissions, or ventilator usage across the United States. As a result, we will no longer provide national-level summary hospitalizations, ICU admissions, or ventilator usage statistics on our site.

We will continue tracking these numbers on a state-by-state basis, but it does not feel responsible to continue to display these US-wide statistics for a general audience. These heavily caveated numbers will remain in the API for advanced data users.

https://covidtracking.com/data

Perhaps a "deprecated" link under each endpoint on the API page that expands to show all deprecated stats would clear up confusion.

[muamichali]

Tagging @friej715 so you can update the Swagger documentation with these fields if they are not already there #517

[friej715]

I do currently have those fields, but the descriptions don't have any of those details (see here), so let's definitely add that context.

Here's the data on SwaggerHub, which gives you a good sense of what the page will look like.

We could do a couple of things (maybe all):

• Include the paragraphs above in the main description area (where it currently just says "API documentation"), maybe including an "as of" date.
• Specifically call this out in each of the US endpoint description areas (for ex. here, where it currently just says "US current values")
• Document this in the BasicData schema descriptions (note that both state and US data currently inherit from this schema--sounds like US won't include these specific values soon though?).

Let me know which options appeal to you all and I'll update!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions!

[kevee]

Fixed in #517