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)
  • latitude
  • longitude

Please Note: Johns Hopkins CSSE update the data at approximately 10 p.m. PST.

Token

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 current time
  • Check token expiry against the current time whenever you make an API call
  • Re-authenticate and generate a new token in the background if token expiry is greater than the current time

Footnote: We are thinking of using a combination of access and 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

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-Limit is the maximum number of requests (5 requests) per minute.
  • X-RateLimit-Remaining denotes the number of request(s) you've got left.
  • X-Rate-Limit-Reset denotes when the current window ends, in seconds from the current time.
  • Retry-After denotes 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, admin and users. Henceforth, we have ensurer and enforcer, and as the naming convention implies:

  • Ensurer ensures request must comply with all the rules attached to it.
  • Enforcer enforces rules no matter the request and/or from whom.
  • Both Ensurer and Enforcer targets header, path, or query.
  • Both Ensurer and Enforcer contain a set of rules.

Going forward, users can access these resources: /token (POST), /v2/:month/:year (GET), /v2/:month/:year/:id (GET), /v2/time_series_confirmed_global (GET), /v2/time_series_confirmed_global/:id (GET), /v2/time_series_confirmed_us (GET), /v2/time_series_confirmed_us/:id (GET), /v2/time_series_deaths_global (GET), /v2/time_series_deaths_global/:id (GET), /v2/time_series_deaths_us (GET), /v2/time_series_deaths_us/:id (GET), /v2/time_series_recovered_global (GET) and /v2/time_series_recovered_global/:id (GET), whilst admin can access all resources without restrictions.

ETag Support

The API supports ETags, which allows the API to signal to developers whether or not data from previous queries have changed.

Usage:

  • 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: ETag: "W/"e4-hFc9aHGYZmwXvrBC8byswCwD+x0d"
  • 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.

API Deprecation

  • 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.

When the Sunset date has passed, a follow-up email will be sent to active third-party developers notifying them of the deprecation.

Performance Tips

Please reach out to us via e-mail if you have any additional feature requests.

API Changelog

12/09/2022

  • Implementation of UUID values as a database key (Multi-Master Delayed Synchronization)

18/08/2022

  • Golang SDK Refactored.

12/08/2022

  • JavaScript SDK Refactored.

30/07/2022

  • API Refactored. Version 2 Released.

01/09/2020