Covid-19-API

This is the code running in AWS Lambda powering covid-api.mmediagroup.fr/v1

In our bid to do our part, we've created a free public API for others to build apps upon. The API returns live cases and historical data.

This API has now been called over 30 million times now!

The API has endpoints to handle historical as well as near realtime data (updated once every hour). The average API response time is between 70 and 250 ms but may take up to 3 seconds, depending if the request is in the cache or not.

You can see a human-friendly webpage that uses the API here https://mmediagroup.fr/covid-19.

What the API is for

The API is intended for developers, machines, programs, and other websites to be able to quickly fetch up to date information on the COVID-19 epidemic.

It can be used to build tools and systems that are used for data analysis all the way to websites that act as public dashboards and charts.

Using the API

If you're a developer, you can use the API right now. Please be nice to us and cache the data locally so we don't pay too much :)!

API base:
https://covid-api.mmediagroup.fr/v1

Live cases data

Request:
GET /cases

Optional query parameters

• country
  • Any country name (case sensitive)
• ab
  • Any country ISO abbreviation (example: FR) (takes precedence over "country" parameter)
• continent
  • Any world continent (example: Europe) (takes precedence over "country" parameter)

Example request:

GET /cases?country=France

Example response:

{
  "All": {
    "confirmed": 2604595,
    "recovered": 195365,
    "deaths": 62548,
    "country": "France",
    "population": 64979548,
    "sq_km_area": 551500,
    "life_expectancy": "78.8",
    "elevation_in_meters": 375,
    "continent": "Europe",
    "abbreviation": "FR",
    "location": "Western Europe",
    "iso": 250,
    "capital_city": "Paris",
    "lat": "46.2276",
    "long": "2.2137",
    "updated": "2020/12/26 12:21:56+00"
  },
  "French Guiana": {
    "lat": "4",
    "long": "-53",
    "confirmed": 12685,
    "recovered": 9995,
    "deaths": 71,
    "updated": "2020/12/26 12:21:56+00"
  }
}

Historical cases data

Request:
GET /history

Required query parameters

• status
  • Confirmed
  • Deaths
  • Recovered (DEPRECIATED)

Optional query parameters

• country
  • Any country name (case sensitive)
• ab
  • Any country ISO abbreviation (example: FR) (takes precedence over "country" parameter)
• continent
  • Any world continent (example: Europe) (takes precedence over "country" parameter)

Example request:

GET /history?country=Germany&status=deaths

Example response:

{
  "All": {
    "country": "Germany",
    "population": 82114224,
    "sq_km_area": 357022,
    "life_expectancy": "77.4",
    "elevation_in_meters": 263,
    "continent": "Europe",
    "abbreviation": "DE",
    "location": "Western Europe",
    "iso": 276,
    "capital_city": "Berlin",
    "dates": {
      "2020-12-25": 29580,
      "2020-12-24": 29330,
      "2020-12-23": 28909,
      "2020-12-22": 28096,
      "2020-12-21": 27110
    }
  }
}

Vaccines data

Request:
GET /vaccines

Optional query parameters

• country
  • Any country name (case sensitive)
• ab
  • Any country ISO abbreviation (example: FR) (takes precedence over "country" parameter)
• continent
  • Any world continent (example: Europe) (takes precedence over "country" parameter)

Example request:

GET /vaccines?country=France

Example response:

{
  "All": {
    "administered": 7927771,
    "people_vaccinated": 2297100,
    "people_partially_vaccinated": 5630671,
    "country": "France",
    "population": 64979548,
    "sq_km_area": 551500,
    "life_expectancy": "78.8",
    "elevation_in_meters": 375,
    "continent": "Europe",
    "abbreviation": "FR",
    "location": "Western Europe",
    "iso": 250,
    "capital_city": "Paris",
    "lat": "46.2276",
    "long": "2.2137",
    "updated": "2020/12/26 12:21:56+00"
  }
}

Authorization

No authorisation is required to fetch data from the API.

Built using this API

Feel free to share your projects that implement this API!

• mmediagroup.fr/covid-19
• covid-t.herokuapp.com
• GoCoronaVirusAPIParser
• Coronavirus-COVID-19-Watch-WordPress-Plugin
• Spider 3d vizualizer
• Discord bot-miku
• Ivis-Bot [Discord]
• NoCo Mobile App

Data sources

Historical data: https://github.com/CSSEGISandData/COVID-19

Realtime data: https://opendata.arcgis.com/datasets/bbb2e4f589ba40d692fab712ae37b9ac_1.csv

Population data:
https://github.com/M-Media-Group/country-json/blob/master/src/countries-master.json

Vaccine data: https://github.com/govex/COVID-19

Rate limits

A rate limiter is applied. Realistically, the data updates around once an hour so more frequent requests are futile (though possible). Ridiculous amount of requests will result in you being banned.

GNU AGPLv3 Licence

Additionally, we ask you to please not create API's that just use this API as the underlying source.

If you make absurd amounts of requests to our API we will block you. You can contact us to resolve the issue. Please cache the API responses with a lifetime of at least 10 minutes to avoid this happening.