The Coronavirus Current and Historical Data API is developed by the team at Moat Systems Limited to help data scientists, government agencies, health professionals, and the public effectively understand and respond to Coronavirus. Independent developers and companies can use it to build interactive data visualization dashboards and applications (mobile and web) and integrate them with their internal tools.
Attribution: a special thank you to Dong E., Du Hongru, Gardner L., and Johns Hopkins CSSE for the data.
Endpoint (Datasets) Content
The API endpoint registers cases for every day from January 21, 2020, to the present day. Below are the fields included:
- confirmed: number of confirmed cases
- deaths: total number of recorded deaths
- last_updated: date from Jan 21, 2020 to Present
- country_region: provided for all countries
- province_state: provided for Australia, Canada, China, Denmark, France, Netherlands, United Kingdom, and United States
- admin2: US only - County name
- fips: US only - a 5-digit Federal Information Processing Standard
- combined_key: US only - Combination of admin2, state_province, and country_region
- incidence_rate: COVID-19 14-day incidence rate
- case_fatality_ratio: estimating the infection and case fatality ratio (CFR)
Please Note: Johns Hopkins CSSE update the data at approximately 10 p.m. PST.
We use access tokens to grant admittance to the API for security reasons and flexibility, and it lasts for 200,000 seconds (55.56 hours). Your engineering team can write a code logic using the implementation strategy below:
- Generate a token and store it in a session
- Store the time you generated the token a.k.a
- Check token expiry against the
current timewhenever you make an API call
- Re-authenticate and generate a new token in the background if
token expiryis greater than the
Footnote: We are thinking of using a combination of
refresh tokens where the response returns a
fresh token that never expires. Of course, we won't issue
refresh tokens using Implicit grant. Your application can easily use the refresh token to obtain a new
access token when the access token expires. It's done in the backend without the user's involvement, thereby making it a seamless process.
Rate limiting is a critical aspect of the API's scalability, and as such, we measure processing limits in Transactions Per Second (TPS). To prevent abuse by automated systems (bots) and humans, we are enforcing a limit to the number of requests and quantity of data clients can consume.
X-RateLimit-Limitis the maximum number of requests (5 requests) per minute.
X-RateLimit-Remainingdenotes the number of request(s) you've got left.
X-Rate-Limit-Resetdenotes when the current window ends, in seconds from the current time.
Retry-Afterdenotes how long you have to wait before making a new request.
Role-based Access Control (RBAC)
We decided to implement and enforce RBAC on our endpoints with these two roles,
users. Henceforth, we have
enforcer, and as the naming convention implies:
Ensurerensures request must comply with all the rules attached to it.
Enforcerenforces rules no matter the request and/or from whom.
Enforcercontain a set of
users can access these resources:
/v2/time_series_recovered_global (GET) and
/v2/time_series_recovered_global/:id (GET), whilst
admin can access all resources without restrictions.
The API supports ETags, which allows the API to signal to developers whether or not data from previous queries have changed.
- When fetching from the API, the response header will include an ETag with a digest of the response data. Save this ETag value for future requests to the same route. An example ETag response header:
- If the data hasn't changed, the response status code will be 304 (Not Modified) and no data will be returned.
- If the response data has changed since the last request, the data is returned normally with a new ETag in the response header. Save this value for future requests.
- When an API endpoint is scheduled for deprecation the following actions will be taken:
- We will mark the endpoint documentation as deprecated with a migration plan included.
- The endpoint will have Sunset in the header (Sunset HTTP Header) added to indicate the last date you should rely on it.
- We will send out an email to third party developers notifying them of the deprecation.
- We will register an entry in the API Changelog.
Sunset date has passed, a follow-up email will be sent to active third-party developers notifying them of the deprecation.
Please reach out to us via e-mail if you have any additional feature requests.
- Implementation of UUID values as a database key (Multi-Master Delayed Synchronization)
- Golang SDK Refactored.
- API Refactored. Version 2 Released.