api_interface¶

class uk_covid19.api_interface.Cov19API(filters: Iterable[str], structure: Dict[str, Union[dict, str]], latest_by: Optional[str] = None)[source]¶

Interface to access the API service for COVID-19 data in the United Kingdom.

Parameters

filters (Iterable[str]) – API filters. See the API documentations for additional information.
structure (Dict[str, Union[dict, str]]) – Structure parameter. See the API documentations for additional information.
latest_by (Union[str, None]) – Retrieves the latest value for a specific metric. [Default: None]

property api_params¶

staticmethod:: API parameters, constructed based on filters, structure, and latest_by arguments as defined by the user.

Returns
Return type: Dict[str, str]

get_csv(save_as=None) → str[source]¶

Provides full data (all pages) in CSV.

Warning

Please make sure that the structure is not hierarchical as CSV outputs are defined as 2D tables and as such, do not support hierarchies.

Parameters

save_as (Union[str, None]) –

If defined, the results will (also) be saved as a file. [Default: None]

The value must be a path to a file with the correct extension – i.e. .csv for CSV).

Returns

Return type

str

Raises

ValueError – If the structure is nested.

Examples

>>> filters = ["areaType=region"]
>>> structure = {
...     "name": "areaName",
...     "newCases": "newCasesBySpecimenDate"
... }
>>> data = Cov19API(
...     filters=filters,
...     structure=structure,
...     latest_by='newCasesBySpecimenDate'
... )
>>> result = data.get_csv()
>>> print(result)
name,newCases
East Midlands,0
...

get_dataframe()[source]¶

Provides the data as as pandas.DataFrame object.

New in version 1.2.0.

Warning

The pandas library is not included in the dependencies of this library and must be installed separately.

Returns
Return type: DataFrame
Raises: ImportError – If the pandas library is not installed.

get_json(save_as: Optional[str] = None, as_string: bool = False) → Union[dict, str][source]¶

Provides full data (all pages) in JSON.

Parameters

save_as (Union[str, None]) –
If defined, the results will (also) be saved as a file. [Default: None]

The value must be a path to a file with the correct extension – i.e. .json for JSON).
as_string (bool) –

New in version 1.1.4.

If False (default), returns the data as a dictionary. Otherwise, returns the data as a JSON string.

Returns

Return type

Union[Dict, str]

Examples

>>> filters = ["areaType=region"]
>>> structure = {
...     "name": "areaName",
...     "newCases": "newCasesBySpecimenDate"
... }
>>> data = Cov19API(
...     filters=filters,
...     structure=structure,
...     latest_by='newCasesBySpecimenDate'
... )
>>> result = data.get_json()
>>> print(result)
{'data': [{'name': 'East Midlands', 'newCases': 0}, ... }

static get_release_timestamp() → str[source]¶

Staticmethod: Produces the website timestamp in GMT.

New in version 1.2.0.

This property supplies the website timestamp - i.e. the time at which the data were released to the API and by extension the website. Please note that there will be a difference between this timestamp and the timestamp produced using the last_update property. The latter signifies the time at which the data were deployed to the database, not the time at which they were released.

Note

The output is extracted from the header and is accurate to the miliseconds.

Warning

The ISO-8601 standard requires a "Z" character to be added to the end of the timestamp. This is a timezone feature and is not recognised by Python’s datetime library. It is, however, most other libraries; e.g. pandas. If you wish to parse the timestamp using the the datetime library, make sure that you remove the trailing "Z" character.

Returns: Timestamp, formatted as ISO-8601.
Return type: str

Examples

>>> release_timestamp = Cov19API.get_release_timestamp()
>>> print(release_timestamp)
2020-08-08T15:00:09.977840Z

>>> from datetime import datetime
>>> release_timestamp = Cov19API.get_release_timestamp()
>>> parsed_timestamp = datetime.fromisoformat(release_timestamp.strip("Z"))
>>> print(parsed_timestamp)
2020-08-08 15:00:09

get_xml(save_as=None, as_string=False) → xml.etree.ElementTree.Element[source]¶

Provides full data (all pages) in XML.

Parameters

save_as (Union[str, None]) –
If defined, the results will (also) be saved as a file. [Default: None]

The value must be a path to a file with the correct extension – i.e. .xml for XML).
as_string (bool) –

New in version 1.1.4.

If False (default), returns an ElementTree object. Otherwise, returns the data as an XML string.

Returns

Return type

xml.etree.ElementTree.Element

Examples

>>> from xml.etree.ElementTree import tostring
>>> filters = ["areaType=region"]
>>> structure = {
...     "name": "areaName",
...     "newCases": "newCasesBySpecimenDate"
... }
>>> data = Cov19API(
...     filters=filters,
...     structure=structure,
...     latest_by='newCasesBySpecimenDate'
... )
>>> result_xml = data.get_xml()
>>> result_str = tostring(result_xml, encoding='unicode', method='xml')
>>> print(result_str)
<document>
    <data>
        <name>East Midlands</name>
        <newCases>0</newCases>
    </data>
    ...
</document>

head()[source]¶

Request header for the given input arguments (filters, structure, and lastest_by).

Returns
Return type: Dict[str, str]

Examples

>>> filters = ["areaType=region"]
>>> structure = {
...     "name": "areaName",
...     "newCases": "newCasesBySpecimenDate"
... }
>>> data = Cov19API(
...     filters=filters,
...     structure=structure,
...     latest_by='newCasesBySpecimenDate'
... )
>>> head = data.head()
>>> print(head)
{'Cache-Control': 'public, max-age=60', 'Content-Length': '0',
 ...
}

property last_update¶

property:: Produces the timestamp for the last update in GMT.

This property supplies the API time - i.e. the time at which the data were deployed to the database. Please note that there will always be a difference between this time and the timestamp that is displayed on the website, which may be accessed via the .get_release_timestamp() method. The website timestamp signifies the time at which the data were release to the API, and by extension the website.

Note

The output is extracted from the header and is accurate to the second.

Warning

The ISO-8601 standard requires a "Z" character to be added to the end of the timestamp. This is a timezone feature and is not recognised by Python’s datetime library. It is, however, most other libraries; e.g. pandas. If you wish to parse the timestamp using the the datetime library, make sure that you remove the trailing "Z" character.

Returns: Timestamp, formatted as ISO-8601.
Return type: str

Examples

>>> filters = ["areaType=region"]
>>> structure = {
...     "name": "areaName",
...     "newCases": "newCasesBySpecimenDate"
... }
>>> data = Cov19API(
...     filters=filters,
...     structure=structure,
...     latest_by='newCasesBySpecimenDate'
... )
>>> timestamp = data.last_update
>>> print(timestamp)
2020-07-27T20:29:16.000000Z

>>> from datetime import datetime
>>> parsed_timestamp = datetime.fromisoformat(timestamp.strip("Z"))
>>> print(parsed_timestamp)
2020-07-27 20:29:16

static options()[source]¶

Staticmethod: Provides the options by calling the OPTIONS method of the API.
Returns: API options.
Return type: dict

Examples

>>> from pprint import pprint
>>> options = Cov19API.options()
>>> pprint(options)
{'info': {'description': "Public Health England's Coronavirus Dashboard API",
 'title': 'Dashboard API',
 'version': '1.0'},
 'openapi': '3.0.1',
  ...
}

property total_pages¶

property:: Produces the total number of pages for a given set of parameters (only after the data are requested).

Returns
Return type: Union[int, None]