ukhsa-internal/coronavirus-dashboard-api-javascript-sdk

Coronavirus (COVID-19) in the UK - API Service SDK for JavaScript

Coronavirus (COVID-19) in the UK - API Service

Software Development Kit (SDK) for JavaScript

This is a JavaScript SDK for the COVID-19 API, as published by Public Health England on Coronavirus (COVID-19) in the UK.

The API supplies the latest data for the COVID-19 outbreak in the United Kingdom.

The endpoint for the data provided using this SDK is:

https://api.coronavirus.data.gov.uk/v1/data

The SDK is also available for Python and R.

Pagination

Using this SDK will bypass the pagination process. You will always download the entire dataset unless the latest_by argument is defined.

Installation

Python 3.7+ is required to install and use this library.

To install globally, please run:

npm install -g @publichealthengland/uk-covid19

or to install locally in your project, run:

npm install @publichealthengland/uk-covid19

Import the library in TypeScript as follows:

import Cov19API from "@publichealthengland/uk-covid19";

or using CommonJS:

const Cov19API = require("@publichealthengland/uk-covid19");

Example

We would like to extract the number of new cases, cumulative cases, new deaths and cumulative deaths for England using the API.

We start off by importing the library into our workspace:

const Cov19API = require("@publichealthengland/uk-covid19");

Next, we construct the value of the filters parameter:

const englandOnly = [
    'areaType=nation',
    'areaName=England'
];

Next step is to construct the value of the structure parameter. To do so, we need to find out the name of the metric in which we are interested. You can find this information in the Developer's Guide on the Coronavirus Dashboard website.

In the case of this example, the metrics are as follows:

• newCasesByPublishDate: New cases (by publish date)
• cumCasesByPublishDate: Cumulative cases (by publish date)
• newDeathsByDeathDate: New deaths (by death date)
• cumDeathsByDeathDate: Cumulative deaths (by death date)

In its simplest form, we construct the structure as follows:

const casesAndDeaths = {
    "date": "date",
    "areaName": "areaName",
    "areaCode": "areaCode",
    "newCasesByPublishDate": "newCasesByPublishDate",
    "cumCasesByPublishDate": "cumCasesByPublishDate",
    "newDeathsByDeathDate": "newDeathsByDeathDate",
    "cumDeathsByDeathDate": "cumDeathsByDeathDate"
};

Now, we may use filters and structure to initialise the Covid19API object:

const api = new Cov19API({
        filters: englandOnly,
        structure: casesAndDeaths
    });

const data = api.getJSON(); 

console.log(data)

You may also use data.getCSV() to download the data in CSV. This is exemplified later in this document.

{
    'data': [
        {
            'date': '2020-07-28',
            'areaName': 'England',
            'areaCode': 'E92000001',
            'newCasesByPublishDate': 547,
            'cumCasesByPublishDate': 259022,
            'newDeathsByDeathDate': None,
            'cumDeathsByDeathDate': None
        },
        {
            'date': '2020-07-27',
            'areaName': 'England',
            'areaCode': 'E92000001',
            'newCasesByPublishDate': 616,
            'cumCasesByPublishDate': 258475,
            'newDeathsByDeathDate': 20,
            'cumDeathsByDeathDate': 41282
        },
        ...
    ],
    'lastUpdate': '2020-07-28T15:34:31.000000Z',
    'length': 162,
    'totalPages': 1
}

To see the timestamp for the last update, run:

const timestamp = api.lastUpdate();

console.log(timestamp);

2020-07-28T15:34:31.000Z

To get the latest data by a specific metric, run:

const allNations = [
    "areaType=nation"
];

const latestData = new Cov19API({
        filters: allNations,
        structure: casesAndDeaths,
        latest_by: "newCasesByPublishDate"
    });

const data = latestData.getJSON();

console.log(data)

{
    "data": [
        {
            "date": "2020-07-28",
            "areaName": "England",
            "areaCode": "E92000001",
            "newCasesByPublishDate": 547,
            "cumCasesByPublishDate": 259022,
            "newDeathsByDeathDate": None,
            "cumDeathsByDeathDate": None
        },
        {
            "date": "2020-07-28",
            "areaName": "Northern Ireland",
            "areaCode": "N92000002",
            "newCasesByPublishDate": 9,
            "cumCasesByPublishDate": 5921,
            "newDeathsByDeathDate": None,
            "cumDeathsByDeathDate": None
        },
        {
            "date": "2020-07-28",
            "areaName": "Scotland",
            "areaCode": "S92000003",
            "newCasesByPublishDate": 4,
            "cumCasesByPublishDate": 18558,
            "newDeathsByDeathDate": None,
            "cumDeathsByDeathDate": None
        },
        {
            "date": "2020-07-28",
            "areaName": "Wales",
            "areaCode": "W92000004",
            "newCasesByPublishDate": 21,
            "cumCasesByPublishDate": 17191,
            "newDeathsByDeathDate": None,
            "cumDeathsByDeathDate": None
        }
    ],
    "lastUpdate": "2020-07-28T15:34:31.000000Z",
    "length": 4,
    "totalPages": 1
}

You may retrieve CSV-formatted data as follows:

const csvData = api.getCSV();

console.log(csvData)

date,areaName,areaCode,newCasesByPublishDate,cumCasesByPublishDate,newDeathsByDeathDate,cumDeathsByDeathDate
2020-07-28,England,E92000001,547,259022,,
2020-07-28,Northern Ireland,N92000002,9,5921,,
2020-07-28,Scotland,S92000003,4,18558,,
2020-07-28,Wales,W92000004,21,17191,,

---

Developed and maintained by Public Health England.

Copyright (c) 2020, Public Health England.

coronavirus-dashboard-api-javascript-sdk's Issues

getJSON() call fails with 'unexpected end of file' error

While attempting to use this in Node (14.13.1 FWIW), I get the following error...

(node:92897) UnhandledPromiseRejectionWarning: Error: unexpected end of file
    at Zlib.zlibOnError [as onerror] (zlib.js:180:17)

...with the following code:

const Cov19API = require('@publichealthengland/uk-covid19').default;

(async () => {
  const casesAndDeaths = {
    date: 'date',
    areaName: 'areaName',
    areaCode: 'areaCode',
    newDeaths28DaysByDeathDate: 'newDeaths28DaysByDeathDate',
  };

  const englandOnly = ['areaType=nation', 'areaName=England'];

  const api = new Cov19API({
    filters: englandOnly,
    structure: casesAndDeaths,
  });

  const data = await api.getJSON();
  console.log(data);
})();

I've added .default per #1 and updated the metrics per #3 in this code already. I did add an await before api.getJSON(), since that returns a promise.

As best as I can tell from debugging this, the error seems to come from the axios call in this.head(), triggered at the end of getJSON, when the API returns status code 204. Wasn't able to solve the problem though.

As a workaround, calling getCSV doesn't have this problem (because it doesn't make a HEAD request).

Requesting fewer records than one page causes infinite loop

When making a request that results in fewer results than contained in a single response of the API, request will be repeated infinitely.

See example below:

    const structure = {
        date: 'date',
        areaName: 'areaName',
        cumPeopleVaccinatedFirstDoseByPublishDate: 'cumPeopleVaccinatedFirstDoseByPublishDate',
    };

    const filters = ['areaType=nation'];

    const api = new Cov19API({
        filters,
        structure,
        latestBy: 'cumPeopleVaccinatedFirstDoseByPublishDate',
    });

I would expect this to have been caused by a change to the API that means page 1 returns the same result as page 2. As can be seen in the below examples.

Example Page 1

Example Page 2

With API.getData looping until it receives a 204 or an error, this will now loop indefinitely:

https://github.com/publichealthengland/coronavirus-dashboard-api-javascript-sdk/blob/7ac7f6fbc06450a122ea446ee4fe78023eb4950d/lib/UKCovid19.ts#L120-L137

Incorrect example ...

The example structure parameters are invalid, resulting in a 404.

You should be using newDeaths28DaysByDeathDate and cumDeaths28DaysByDeathDate

getData does not have correct termination condition

The termination condition in the getData loop is incorrect - calling the API with an invalid page number will result in a 404, not a 204.

The loop termination condition is when data.pagination.next is null on return from the Axios get.

Does not work with node app

Hi,

Your example does not work in a node.js app. The following error is generated:

const api = new Cov19API({
^
TypeError: Cov19API is not a constructor

I think it may be to do with the way that you transpire your typescript?

What does work is adding ".default" to the require():

const Cov19API = require('@publichealthengland/uk-covid19').default;