uk-covid19


Nameuk-covid19 JSON
Version 1.1.5 PyPI version JSON
download
home_pagehttps://coronavirus.data.gov.uk/
SummarySDK for the COVID-19 API (Coronavirus Dashboard in the UK)
upload_time2020-08-06 18:05:22
maintainerPublic Health England - Coronavirus Dashboard Team
docs_urlNone
authorPouria Hadjibagheri
requires_python>=3.7
licenseMIT
keywords api sdk phe covid19 covid-19 coronavirus data uk england wales scotland northern_ireland united_kingdom
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            Coronavirus (COVID-19) in the UK - API Service
==============================================

|PyPi_Version| |PyPi_Status| |Format| |Supported_versions_of_Python| |lgtm| |License|


Software Development Kit (SDK) for Python
-----------------------------------------

This is a Python 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 `JavaScript`_ 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, please run:

.. code-block:: bash

    python -m pip install uk-covid19

and import it in Python as follows:

.. code-block:: python

    from uk_covid19 import Cov19API


Note that you must use ``uk_covid19`` (with an underscore, not a hyphen) to import the
library in Python.

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:

.. code-block:: python

    from uk_covid19 import Cov19API


Next, we construct the value of the ``filters`` parameter:

.. code-block:: python

    england_only = [
        '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:

.. code-block:: python

    cases_and_deaths = {
        "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:

.. code-block:: python

    api = Cov19API(filters=england_only, structure=cases_and_deaths)
    data = api.get_json()  # Returns a dictionary
    print(data)


You may also use ``data.get_xml()`` or ``data.get_csv()`` to download the data in other
available formats.

::

    {
        '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:

.. code-block:: python

    print(api.last_update)

::

    2020-07-28T15:34:31.000000Z


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

.. code-block:: python

    all_nations = [
        "areaType=nation"
    ]

    api = Cov19API(
        filters=all_nations,
        structure=cases_and_deaths,
        latest_by="newCasesByPublishDate"
    )

    data = api.get_json()

    print(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
    }


Set the ``save_as`` input argument to a path to save the data in a file. This
functionality is only available for ``.get_json()``, ``.get_xml()`` and ``.get_csv()``
methods.

Note that the ``save_as`` argument must be set to a file name with the correct extension;
that is, ``.json`` for JSON data, ``.xml`` for XML data, and ``.csv`` for CSV data. It is
assumed that the directory in which you wish to save the file already exists.

You may use relative or absolute paths.

.. code-block:: python

    path = "data.csv"

    api.get_csv(save_as="some_existing_directory/data.csv")


This will create a file entitled ``data.csv`` under ``some_existing_directory``. The
contents of the file would be as follows:

::

    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,,


Set the ``as_string`` input argument to ``True`` for the ``.get_json()`` method if you
wish to receive the result as a JSON string instead of a ``dict`` object:

.. code-block:: python

    data = api.get_json(as_string=True)
    print(data)

::

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



-----------

Developed and maintained by `Public Health England`_.

Copyright (c) 2020, Public Health England.

.. _`Coronavirus (COVID-19) in the UK`: http://coronavirus.data.gov.uk/
.. _`Public Health England`: https://www.gov.uk/government/organisations/public-health-england
.. _`JavaScript`: https://github.com/publichealthengland/coronavirus-dashboard-api-javascript-sdk
.. _`R`: https://github.com/publichealthengland/coronavirus-dashboard-api-R-sdk

.. |PyPi_Version| image:: https://img.shields.io/pypi/v/uk-covid19
.. |PyPi_Status| image:: https://img.shields.io/pypi/status/uk-covid19
.. |Format| image:: https://img.shields.io/pypi/format/uk-covid19
.. |Supported_versions_of_Python| image:: https://img.shields.io/pypi/pyversions/uk-covid19
.. |License| image:: https://img.shields.io/github/license/publichealthengland/coronavirus-dashboard-api-python-sdk
.. |lgtm| image:: https://img.shields.io/lgtm/grade/python/github/publichealthengland/coronavirus-dashboard-api-python-sdk


            

Raw data

            {
    "_id": null,
    "home_page": "https://coronavirus.data.gov.uk/",
    "name": "uk-covid19",
    "maintainer": "Public Health England - Coronavirus Dashboard Team",
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "covid19-tech@phe.gov.uk",
    "keywords": "API SDK PHE COVID19 COVID-19 coronavirus data UK England Wales Scotland Northern_Ireland United_Kingdom",
    "author": "Pouria Hadjibagheri",
    "author_email": "Pouria.Hadjibagheri@phe.gov.uk",
    "download_url": "https://files.pythonhosted.org/packages/bb/87/8c4381792894f49b85121c8f500b0e39c52184280ad31750c1dc7b6bc651/uk_covid19-1.1.5.tar.gz",
    "platform": "",
    "description": "Coronavirus (COVID-19) in the UK - API Service\n==============================================\n\n|PyPi_Version| |PyPi_Status| |Format| |Supported_versions_of_Python| |lgtm| |License|\n\n\nSoftware Development Kit (SDK) for Python\n-----------------------------------------\n\nThis is a Python SDK for the COVID-19 API, as published by Public Health England\non `Coronavirus (COVID-19) in the UK`_.\n\nThe API supplies the latest data for the COVID-19 outbreak in the United Kingdom. \n\nThe endpoint for the data provided using this SDK is:\n\n    https://api.coronavirus.data.gov.uk/v1/data\n\nThe SDK is also available for `JavaScript`_ and `R`_.\n\nPagination\n..........\n\nUsing this SDK will bypass the pagination process. You will always download the entire\ndataset unless the ``latest_by`` argument is defined.\n\n\nInstallation\n............\n\nPython 3.7+ is required to install and use this library.\n\nTo install, please run:\n\n.. code-block:: bash\n\n    python -m pip install uk-covid19\n\nand import it in Python as follows:\n\n.. code-block:: python\n\n    from uk_covid19 import Cov19API\n\n\nNote that you must use ``uk_covid19`` (with an underscore, not a hyphen) to import the\nlibrary in Python.\n\nExample\n.......\n\nWe would like to extract the number of new cases, cumulative cases, new deaths and\ncumulative deaths for England using the API.\n\nWe start off by importing the library into our workspace:\n\n.. code-block:: python\n\n    from uk_covid19 import Cov19API\n\n\nNext, we construct the value of the ``filters`` parameter:\n\n.. code-block:: python\n\n    england_only = [\n        'areaType=nation',\n        'areaName=England'\n    ]\n\nNext step is to construct the value of the ``structure`` parameter. To do so, we need to\nfind out the name of the metric in which we are interested. You can find this information\nin the Developer's Guide on the Coronavirus Dashboard website.\n\nIn the case of this example, the metrics are as follows:\n\n- ``newCasesByPublishDate``: New cases (by publish date)\n- ``cumCasesByPublishDate``: Cumulative cases (by publish date)\n- ``newDeathsByDeathDate``: New deaths (by death date)\n- ``cumDeathsByDeathDate``: Cumulative deaths (by death date)\n\nIn its simplest form, we construct the structure as follows:\n\n.. code-block:: python\n\n    cases_and_deaths = {\n        \"date\": \"date\",\n        \"areaName\": \"areaName\",\n        \"areaCode\": \"areaCode\",\n        \"newCasesByPublishDate\": \"newCasesByPublishDate\",\n        \"cumCasesByPublishDate\": \"cumCasesByPublishDate\",\n        \"newDeathsByDeathDate\": \"newDeathsByDeathDate\",\n        \"cumDeathsByDeathDate\": \"cumDeathsByDeathDate\"\n    }\n\n\nNow, we may use ``filters`` and ``structure`` to initialise the ``Covid19API`` object:\n\n.. code-block:: python\n\n    api = Cov19API(filters=england_only, structure=cases_and_deaths)\n    data = api.get_json()  # Returns a dictionary\n    print(data)\n\n\nYou may also use ``data.get_xml()`` or ``data.get_csv()`` to download the data in other\navailable formats.\n\n::\n\n    {\n        'data': [\n            {\n                'date': '2020-07-28',\n                'areaName': 'England',\n                'areaCode': 'E92000001',\n                'newCasesByPublishDate': 547,\n                'cumCasesByPublishDate': 259022,\n                'newDeathsByDeathDate': None,\n                'cumDeathsByDeathDate': None\n            },\n            {\n                'date': '2020-07-27',\n                'areaName': 'England',\n                'areaCode': 'E92000001',\n                'newCasesByPublishDate': 616,\n                'cumCasesByPublishDate': 258475,\n                'newDeathsByDeathDate': 20,\n                'cumDeathsByDeathDate': 41282\n            },\n            ...\n        ],\n        'lastUpdate': '2020-07-28T15:34:31.000000Z',\n        'length': 162,\n        'totalPages': 1\n    }\n\n\nTo see the timestamp for the last update, run:\n\n.. code-block:: python\n\n    print(api.last_update)\n\n::\n\n    2020-07-28T15:34:31.000000Z\n\n\nTo get the latest data by a specific metric, run:\n\n.. code-block:: python\n\n    all_nations = [\n        \"areaType=nation\"\n    ]\n\n    api = Cov19API(\n        filters=all_nations,\n        structure=cases_and_deaths,\n        latest_by=\"newCasesByPublishDate\"\n    )\n\n    data = api.get_json()\n\n    print(data)\n\n::\n\n    {\n        \"data\": [\n            {\n                \"date\": \"2020-07-28\",\n                \"areaName\": \"England\",\n                \"areaCode\": \"E92000001\",\n                \"newCasesByPublishDate\": 547,\n                \"cumCasesByPublishDate\": 259022,\n                \"newDeathsByDeathDate\": None,\n                \"cumDeathsByDeathDate\": None\n            },\n            {\n                \"date\": \"2020-07-28\",\n                \"areaName\": \"Northern Ireland\",\n                \"areaCode\": \"N92000002\",\n                \"newCasesByPublishDate\": 9,\n                \"cumCasesByPublishDate\": 5921,\n                \"newDeathsByDeathDate\": None,\n                \"cumDeathsByDeathDate\": None\n            },\n            {\n                \"date\": \"2020-07-28\",\n                \"areaName\": \"Scotland\",\n                \"areaCode\": \"S92000003\",\n                \"newCasesByPublishDate\": 4,\n                \"cumCasesByPublishDate\": 18558,\n                \"newDeathsByDeathDate\": None,\n                \"cumDeathsByDeathDate\": None\n            },\n            {\n                \"date\": \"2020-07-28\",\n                \"areaName\": \"Wales\",\n                \"areaCode\": \"W92000004\",\n                \"newCasesByPublishDate\": 21,\n                \"cumCasesByPublishDate\": 17191,\n                \"newDeathsByDeathDate\": None,\n                \"cumDeathsByDeathDate\": None\n            }\n        ],\n        \"lastUpdate\": \"2020-07-28T15:34:31.000000Z\",\n        \"length\": 4,\n        \"totalPages\": 1\n    }\n\n\nSet the ``save_as`` input argument to a path to save the data in a file. This\nfunctionality is only available for ``.get_json()``, ``.get_xml()`` and ``.get_csv()``\nmethods.\n\nNote that the ``save_as`` argument must be set to a file name with the correct extension;\nthat is, ``.json`` for JSON data, ``.xml`` for XML data, and ``.csv`` for CSV data. It is\nassumed that the directory in which you wish to save the file already exists.\n\nYou may use relative or absolute paths.\n\n.. code-block:: python\n\n    path = \"data.csv\"\n\n    api.get_csv(save_as=\"some_existing_directory/data.csv\")\n\n\nThis will create a file entitled ``data.csv`` under ``some_existing_directory``. The\ncontents of the file would be as follows:\n\n::\n\n    date,areaName,areaCode,newCasesByPublishDate,cumCasesByPublishDate,newDeathsByDeathDate,cumDeathsByDeathDate\n    2020-07-28,England,E92000001,547,259022,,\n    2020-07-28,Northern Ireland,N92000002,9,5921,,\n    2020-07-28,Scotland,S92000003,4,18558,,\n    2020-07-28,Wales,W92000004,21,17191,,\n\n\nSet the ``as_string`` input argument to ``True`` for the ``.get_json()`` method if you\nwish to receive the result as a JSON string instead of a ``dict`` object:\n\n.. code-block:: python\n\n    data = api.get_json(as_string=True)\n    print(data)\n\n::\n\n    {\"data\":[{\"date\":\"2020-07-28\",\"areaName\":\"England\",\"areaCode\":\"E92000001\",\"newCasesByPublishDate\":547,\"cumCasesByPublishDate\":259022,\"newDeathsByDeathDate\":null,\"cumDeathsByDeathDate\":null},{\"date\":\"2020-07-28\",\"areaName\":\"Northern Ireland\",\"areaCode\":\"N92000002\",\"newCasesByPublishDate\":9,\"cumCasesByPublishDate\":5921,\"newDeathsByDeathDate\":null,\"cumDeathsByDeathDate\":null},{\"date\":\"2020-07-28\",\"areaName\":\"Scotland\",\"areaCode\":\"S92000003\",\"newCasesByPublishDate\":4,\"cumCasesByPublishDate\":18558,\"newDeathsByDeathDate\":null,\"cumDeathsByDeathDate\":null},{\"date\":\"2020-07-28\",\"areaName\":\"Wales\",\"areaCode\":\"W92000004\",\"newCasesByPublishDate\":21,\"cumCasesByPublishDate\":17191,\"newDeathsByDeathDate\":null,\"cumDeathsByDeathDate\":null}],\"lastUpdate\":\"2020-07-28T15:34:31.000000Z\",\"length\":4,\"totalPages\":1}\n\n\n\n-----------\n\nDeveloped and maintained by `Public Health England`_.\n\nCopyright (c) 2020, Public Health England.\n\n.. _`Coronavirus (COVID-19) in the UK`: http://coronavirus.data.gov.uk/\n.. _`Public Health England`: https://www.gov.uk/government/organisations/public-health-england\n.. _`JavaScript`: https://github.com/publichealthengland/coronavirus-dashboard-api-javascript-sdk\n.. _`R`: https://github.com/publichealthengland/coronavirus-dashboard-api-R-sdk\n\n.. |PyPi_Version| image:: https://img.shields.io/pypi/v/uk-covid19\n.. |PyPi_Status| image:: https://img.shields.io/pypi/status/uk-covid19\n.. |Format| image:: https://img.shields.io/pypi/format/uk-covid19\n.. |Supported_versions_of_Python| image:: https://img.shields.io/pypi/pyversions/uk-covid19\n.. |License| image:: https://img.shields.io/github/license/publichealthengland/coronavirus-dashboard-api-python-sdk\n.. |lgtm| image:: https://img.shields.io/lgtm/grade/python/github/publichealthengland/coronavirus-dashboard-api-python-sdk\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "SDK for the COVID-19 API (Coronavirus Dashboard in the UK)",
    "version": "1.1.5",
    "split_keywords": [
        "api",
        "sdk",
        "phe",
        "covid19",
        "covid-19",
        "coronavirus",
        "data",
        "uk",
        "england",
        "wales",
        "scotland",
        "northern_ireland",
        "united_kingdom"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "5ca5a5473fb109d8744b18976a81ceef",
                "sha256": "b1b3c336c2b8904be060daeb26107ce156bfc974fd4790d49db0864b384c0b52"
            },
            "downloads": -1,
            "filename": "uk_covid19-1.1.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5ca5a5473fb109d8744b18976a81ceef",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 10699,
            "upload_time": "2020-08-06T18:05:21",
            "upload_time_iso_8601": "2020-08-06T18:05:21.474489Z",
            "url": "https://files.pythonhosted.org/packages/7b/0b/ead7c70d97562241fd9418e105e113907d826a4a5f25437cd5a4d57ff27f/uk_covid19-1.1.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "6f930011a4db5a4f8b32e61c0c614758",
                "sha256": "e371be0cf047f1ce180e63459a037c663ba6b5a6c17a5a86b557b92e8fc06b2b"
            },
            "downloads": -1,
            "filename": "uk_covid19-1.1.5.tar.gz",
            "has_sig": false,
            "md5_digest": "6f930011a4db5a4f8b32e61c0c614758",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 12108,
            "upload_time": "2020-08-06T18:05:22",
            "upload_time_iso_8601": "2020-08-06T18:05:22.990780Z",
            "url": "https://files.pythonhosted.org/packages/bb/87/8c4381792894f49b85121c8f500b0e39c52184280ad31750c1dc7b6bc651/uk_covid19-1.1.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2020-08-06 18:05:22",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "uk-covid19"
}
        
Elapsed time: 0.15279s