Api Documentation

Retrieve COVID-19 global data with ease!

This is a straight forward and easy-to-use JSON API built for accessing and retrieving COVID-19 related data per country (or territory). The dataset is aggregated, cleaned and collated as a time series sequence. We currently provide data for 226 countries/states/territories (for availability see drop down menu at the top). For some datasets we also provide data for individual states/provinces/districts. The API is currently rate-limited at 30 requests per minute. This is so that the API is used sensibly and remains accessible to all. Note that the data are retrieved from public sources and therefore we cannot be held responsible for their accuracy and validity. The data are solely here for the convenience and facilitation of research and development and should not be used for taking any critical decisions. Our data sources are provided here.
Fetch Countries
To retrieve all available countries and their 2-digit ISO Country Code then you can run the command.
By default the command will return a JSON response. If you would like the output to be in a JSON human readable format then use the optional format=pretty parameter. If you would like the final output to be in a csv format, then use the optional format=csv parameter.
curl -L -G 'https://covid19.algolysis.com/api/v1/countries?format=pretty'
<?php
   $curl = curl_init();
   curl_setopt_array($curl, array( 
   CURLOPT_URL => 'https://covid19.algolysis.com/api/v1/countries?format=pretty',
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Retrieve all data for a country
To retrieve all data for a specific country, the only parameter you need to fill is countryCode which must be a valid 2-digit ISO 3166-1 alpha-2 country code. You can find those here.
In the example, we will try to fetch all data for Greece. We know the 2-digit ISO Country Code for Greece is GR. Thus, we set countryCode=GR .
Explanation of the expected result. As you can see, the returned response will be in JSON format. The attribute data holds the response and it is divided into two main attributes. First, the timerange holds info about the dates you requested. Second, the legend includes the details of the country you requested the data. Lastly, the 2-digit-country-iso-code which descripes the country you requested the data for, and in each block holds the data per day.
Explanation of the block attributes. First, the time field that marks the time of the data and it is a UNIX timestamp. Timestamps can be trivially converted to any time format, in all programming languages. Secondly, the confirmed field that holds the number of the confirmed cases for that time. The recovered field holds the number of recovered cases for that time. The deaths field holds the number of deaths for that time and the district field in which disctrict of the requested Country the data corresponds. When no district information is available, the value is equal to "nan".
Please notice that for clarity we do not show below the full result, but only a few samples.
Note: If you would like the output to be in a JSON human readable format then use the optional format=pretty parameter. If you would like the final output to be in a csv format, then use the optional format=csv parameter.
curl -L -G 'https://covid19.algolysis.com/api/v1/data?countryCode=GR'
<?php
   $curl = curl_init();
   curl_setopt_array($curl, array( 
   CURLOPT_URL => "https://covid19.algolysis.com/api/v1/data?countryCode=GR',
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

				
Fetch Data For A Country For Specific Dates
To retrieve all data for a specific country, you need to fill the mandatory parameter countryCode and parameters from and to .
In the example, we will try to fetch all data for Spain from March 21st, 2020 until April 7th 2020. We know the 2-digit ISO Country Code for Spain is ES. Thus, we set countryCode=ES , from=20200321 and to=20200407 . The data for Spain are broken down by autonomous community (a Spanish administrative division). The 'nan' district contains the country's totals.
More information regarding the output can be found in the first example where we retrieve full data for Greece.
Please notice that for the ease of the presentation we do not show the full result, but just one block of it.
Note: If you would like the output to be in a JSON human readable format then use the optional format=pretty parameter. If you would like the final output to be in a csv format, then use the optional format=csv parameter.
curl -L -G 'https://covid19.algolysis.com/api/v1/data?countryCode=ES&from=20200321&to=20200407'
<?php
   $curl = curl_init();
   curl_setopt_array($curl, array( 
   CURLOPT_URL => 'https://covid19.algolysis.com/api/v1/data?countryCode=ES&from=20200321&to=20200407',
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => "",
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;