airbase package

class airbase.AirbaseClient[source]

Bases: object

The central point for requesting Airbase data.

Example:

>>> client = AirbaseClient()
>>> r = client.request("Historical", "NL", "DE", poll=["O3", "NO2"])
>>> r.download("data/raw")
summary : 100%|██████████| 2/2 [00:00<00:00,  2.19requests/s]
URLs    : 100%|██████████| 1.80k/1.80k [00:00<00:00, 17.4kURL/s]
download: 2.05Gb [01:58, 18.6Mb/s]
>>> r.download_metadata("data/metadata.tsv")
Writing metadata to data/metadata.tsv...

countries: All pollutants available from AirBase

static download_metadata(filepath, verbose=True)[source]

Download the metadata CSV file.

See https://discomap.eea.europa.eu/App/AQViewer/index.html?fqn=Airquality_Dissem.b2g.measurements

Parameters:

filepath (str | Path) –
verbose (bool) –

Return type:

None

request(source, *countries, poll=None, verbose=True)[source]

Initialize an AirbaseRequest for a query.

Pollutants can be specified by name/notation (poll). If no pollutants are specified, data for all available pollutants will be requested. If a poll is not available for a country, then we simply do not try to download those parquet files.

Requests proceed in two steps: First, URLs to individual parquet files are requested from the EEA server. Then these links are used to download the individual parquet files.

See https://eeadmz1-downloads-webapp.azurewebsites.net/

Parameters:

source (Literal['Historical', 'Verified', 'Unverified'] | ~airbase.parquet_api.dataset.Dataset) – One of 3 options. “Historical” data delivered between 2002 and 2012, before Air Quality Directive 2008/50/EC entered into force. “Verified” data (E1a) from 2013 to 2022 reported by countries by 30 September each year for the previous year. “Unverified” data transmitted continuously (Up-To-Date/UTD/E2a), from the beginning of 2023.
countries (str) – (optional), 2-letter country codes. Data will be requested for each country. Will raise ValueError if a country is not in self.countries. If no countries are provided, data for all countries will be requested.
poll (str | Iterable[str] | None) – (optional) pollutant(s) to request data for. Must be one of the pollutants in self.pollutants.
verbose (bool) – (optional) print status messages to stderr. Default True.
preload_urls – (optional) Request all the file URLs from the EEA server at object initialization. Default False.

Return AirbaseRequest:

The initialized AirbaseRequest.

Example:

>>> client = AirbaseClient()
>>> r = client.request("Historical", "NL", "DE", poll=["O3", "NO2"])
>>> r.download("data/raw")
summary : 100%|██████████| 2/2 [00:00<00:00,  2.19requests/s]
URLs    : 100%|██████████| 1.80k/1.80k [00:00<00:00, 17.4kURL/s]
download: 2.05Gb [01:58, 18.6Mb/s]
>>> r.download_metadata("data/metadata.tsv")
Writing metadata to data/metadata.tsv...

Return type:

AirbaseRequest

search_pollutant(query, limit=None)[source]

Search for a pollutant’s id number based on its name.

Parameters:

query (str) – The pollutant to search for.
limit (int | None) – (optional) Max number of results.

Returns:

The best pollutant matches. Pollutants are dicts with keys “poll” and “id”.

Example:

>>> AirbaseClient().search_pollutant("o3", limit=2)
>>> [{"poll": "O3", "id": 7}, {"poll": "NO3", "id": 46}]

Return type:

list[airbase.airbase.PollutantDict]

class airbase.AirbaseRequest(source, *country, poll=None, verbose=True)[source]

Bases: object

Handler for Airbase data requests.

Requests proceed in two steps: First, URLs to individual parquet files are requested from the EEA server. Then these links are used to download the individual parquet files.

See https://eeadmz1-downloads-webapp.azurewebsites.net/

Parameters:

source (Dataset) – One of 3 options. airbase.Dataset.Historical data delivered between 2002 and 2012, before Air Quality Directive 2008/50/EC entered into force. airbase.Dataset.Verified data (E1a) from 2013 to 2022 reported by countries by 30 September each year for the previous year. airbase.Dataset.Unverified data transmitted continuously (Up-To-Date/UTD/E2a), from the beginning of 2023.
country (str) – 2-letter country code or a list of them. If a list, data will be requested for each country.
poll (str | Iterable[str] | None) – (optional) pollutant(s) to request data for. Will be applied to each country requested. If None, all available pollutants will be requested.
verbose (bool) – (optional) print status messages to stderr. Default True.
preload_urls (bool) – (optional) Request all the csv download links from the Airbase server at object initialization. Default False.

download(dir, skip_existing=True, raise_for_status=True)[source]

Download into a directory, preserving original file structure.

Parameters:

dir (str | Path) – The directory to save files in (must exist)
skip_existing (bool) – (optional) Don’t re-download files if they exist in dir. If False, existing files in dir may be overwritten. Default True.
raise_for_status (bool) – (optional) Raise exceptions if download links return “bad” HTTP status codes. If False, a warnings.warn() will be issued instead. Default True.

Returns:

self

Return type:

None

download_metadata(filepath)[source]

Download the metadata CSV file.

See https://discomap.eea.europa.eu/App/AQViewer/index.html?fqn=Airquality_Dissem.b2g.measurements

Parameters:: filepath (str | Path) – Where to save the CSV
Return type:: None

session = <airbase.parquet_api.session.Session object>

class airbase.Dataset(value)[source]

Bases: IntEnum

1. Unverified data transmitted continuously (Up-To-Date/UTD/E2a) data from the beginning of 2024. 2. Verified data (E1a) from 2013 to 2023 reported by countries by 30 September each year for the previous year. 3. Historical Airbase data delivered between 2002 and 2012 before Air Quality Directive 2008/50/EC entered into force.

https://eeadmz1-downloads-webapp.azurewebsites.net/content/documentation/How_To_Downloads.pdf

Airbase = 3

E1a = 2

E2a = 1

Historical = 3

UDT = 1

Unverified = 1

Verified = 2

Subpackages

Submodules

airbase.airbase module

class airbase.airbase.AirbaseClient[source]

Bases: object

The central point for requesting Airbase data.

Example:

>>> client = AirbaseClient()
>>> r = client.request("Historical", "NL", "DE", poll=["O3", "NO2"])
>>> r.download("data/raw")
summary : 100%|██████████| 2/2 [00:00<00:00,  2.19requests/s]
URLs    : 100%|██████████| 1.80k/1.80k [00:00<00:00, 17.4kURL/s]
download: 2.05Gb [01:58, 18.6Mb/s]
>>> r.download_metadata("data/metadata.tsv")
Writing metadata to data/metadata.tsv...

countries: All pollutants available from AirBase

static download_metadata(filepath, verbose=True)[source]

Download the metadata CSV file.

See https://discomap.eea.europa.eu/App/AQViewer/index.html?fqn=Airquality_Dissem.b2g.measurements

Parameters:

filepath (str | Path) –
verbose (bool) –

Return type:

None

request(source, *countries, poll=None, verbose=True)[source]

Initialize an AirbaseRequest for a query.

Pollutants can be specified by name/notation (poll). If no pollutants are specified, data for all available pollutants will be requested. If a poll is not available for a country, then we simply do not try to download those parquet files.

Requests proceed in two steps: First, URLs to individual parquet files are requested from the EEA server. Then these links are used to download the individual parquet files.

See https://eeadmz1-downloads-webapp.azurewebsites.net/

Parameters:

source (Literal['Historical', 'Verified', 'Unverified'] | ~airbase.parquet_api.dataset.Dataset) – One of 3 options. “Historical” data delivered between 2002 and 2012, before Air Quality Directive 2008/50/EC entered into force. “Verified” data (E1a) from 2013 to 2022 reported by countries by 30 September each year for the previous year. “Unverified” data transmitted continuously (Up-To-Date/UTD/E2a), from the beginning of 2023.
countries (str) – (optional), 2-letter country codes. Data will be requested for each country. Will raise ValueError if a country is not in self.countries. If no countries are provided, data for all countries will be requested.
poll (str | Iterable[str] | None) – (optional) pollutant(s) to request data for. Must be one of the pollutants in self.pollutants.
verbose (bool) – (optional) print status messages to stderr. Default True.
preload_urls – (optional) Request all the file URLs from the EEA server at object initialization. Default False.

Return AirbaseRequest:

The initialized AirbaseRequest.

Example:

>>> client = AirbaseClient()
>>> r = client.request("Historical", "NL", "DE", poll=["O3", "NO2"])
>>> r.download("data/raw")
summary : 100%|██████████| 2/2 [00:00<00:00,  2.19requests/s]
URLs    : 100%|██████████| 1.80k/1.80k [00:00<00:00, 17.4kURL/s]
download: 2.05Gb [01:58, 18.6Mb/s]
>>> r.download_metadata("data/metadata.tsv")
Writing metadata to data/metadata.tsv...

Return type:

AirbaseRequest

search_pollutant(query, limit=None)[source]

Search for a pollutant’s id number based on its name.

Parameters:

query (str) – The pollutant to search for.
limit (int | None) – (optional) Max number of results.

Returns:

The best pollutant matches. Pollutants are dicts with keys “poll” and “id”.

Example:

>>> AirbaseClient().search_pollutant("o3", limit=2)
>>> [{"poll": "O3", "id": 7}, {"poll": "NO3", "id": 46}]

Return type:

list[airbase.airbase.PollutantDict]

class airbase.airbase.AirbaseRequest(source, *country, poll=None, verbose=True)[source]

Bases: object

Handler for Airbase data requests.

Requests proceed in two steps: First, URLs to individual parquet files are requested from the EEA server. Then these links are used to download the individual parquet files.

See https://eeadmz1-downloads-webapp.azurewebsites.net/

Parameters:

source (Dataset) – One of 3 options. airbase.Dataset.Historical data delivered between 2002 and 2012, before Air Quality Directive 2008/50/EC entered into force. airbase.Dataset.Verified data (E1a) from 2013 to 2022 reported by countries by 30 September each year for the previous year. airbase.Dataset.Unverified data transmitted continuously (Up-To-Date/UTD/E2a), from the beginning of 2023.
country (str) – 2-letter country code or a list of them. If a list, data will be requested for each country.
poll (str | Iterable[str] | None) – (optional) pollutant(s) to request data for. Will be applied to each country requested. If None, all available pollutants will be requested.
verbose (bool) – (optional) print status messages to stderr. Default True.
preload_urls (bool) – (optional) Request all the csv download links from the Airbase server at object initialization. Default False.

download(dir, skip_existing=True, raise_for_status=True)[source]

Download into a directory, preserving original file structure.

Parameters:

dir (str | Path) – The directory to save files in (must exist)
skip_existing (bool) – (optional) Don’t re-download files if they exist in dir. If False, existing files in dir may be overwritten. Default True.
raise_for_status (bool) – (optional) Raise exceptions if download links return “bad” HTTP status codes. If False, a warnings.warn() will be issued instead. Default True.

Returns:

self

Return type:

None

download_metadata(filepath)[source]

Download the metadata CSV file.

See https://discomap.eea.europa.eu/App/AQViewer/index.html?fqn=Airquality_Dissem.b2g.measurements

Parameters:: filepath (str | Path) – Where to save the CSV
Return type:: None

pollutants: set[str]

session = <airbase.parquet_api.session.Session object>

class airbase.airbase.PollutantDict[source]

Bases: TypedDict

id: int

poll: str

airbase.cli module

class airbase.cli.Country(value)[source]

Bases: str, Enum

An enumeration.

AD = 'AD'

AL = 'AL'

AT = 'AT'

BA = 'BA'

BE = 'BE'

BG = 'BG'

CH = 'CH'

CY = 'CY'

CZ = 'CZ'

DE = 'DE'

DK = 'DK'

EE = 'EE'

ES = 'ES'

FI = 'FI'

FR = 'FR'

GB = 'GB'

GR = 'GR'

HR = 'HR'

HU = 'HU'

IE = 'IE'

IS = 'IS'

IT = 'IT'

LT = 'LT'

LU = 'LU'

LV = 'LV'

ME = 'ME'

MK = 'MK'

MT = 'MT'

NL = 'NL'

NO = 'NO'

PL = 'PL'

PT = 'PT'

RO = 'RO'

RS = 'RS'

SE = 'SE'

SI = 'SI'

SK = 'SK'

TR = 'TR'

XK = 'XK'

class airbase.cli.Frequency(value)[source]

Bases: str, Enum

An enumeration.

property aggregation_type: AggregationType

daily = 'daily'

hourly = 'hourly'

other = 'other'

class airbase.cli.Pollutant(value)[source]

Bases: str, Enum

An enumeration.

Acenaphthene = 'Acenaphthene'

Acenaphthylene = 'Acenaphthylene'

Acenaphtylene = 'Acenaphtylene'

Acetaldehyde = 'Acetaldehyde'

Acetone = 'Acetone'

Acetophenone = 'Acetophenone'

Acroleine = 'Acroleine'

Al = 'Al'

Aldrin = 'Aldrin'

Anthanthrene = 'Anthanthrene'

Anthracene = 'Anthracene'

As = 'As'

Atrazine = 'Atrazine'

BDE100 = 'BDE100'

BDE153 = 'BDE153'

BDE154 = 'BDE154'

BDE209 = 'BDE209'

BDE47 = 'BDE47'

BDE85 = 'BDE85'

BDE99 = 'BDE99'

BS = 'BS'

BTBPT = 'BTBPT'

BaP = 'BaP'

Benzaldehyde = 'Benzaldehyde'

Biphenyl = 'Biphenyl'

Butanales = 'Butanales'

Butenes = 'Butenes'

C2Cl4 = 'C2Cl4'

C2H6 = 'C2H6'

C6H12 = 'C6H12'

C6H12O2 = 'C6H12O2'

C6H14 = 'C6H14'

C6H4Cl2 = 'C6H4Cl2'

C6H6 = 'C6H6'

C7H16 = 'C7H16'

C8H18 = 'C8H18'

C8H8O = 'C8H8O'

C9H12 = 'C9H12'

C9H20 = 'C9H20'

CDD1N = 'CDD1N'

CDD4X = 'CDD4X'

CDD6P = 'CDD6P'

CDD6X = 'CDD6X'

CDD9X = 'CDD9X'

CDDO = 'CDDO'

CDF2N = 'CDF2N'

CDF2T = 'CDF2T'

CDF4X = 'CDF4X'

CDF6P = 'CDF6P'

CDF6X = 'CDF6X'

CDF9P = 'CDF9P'

CDF9X = 'CDF9X'

CDFDN = 'CDFDN'

CDFDX = 'CDFDX'

CDFO = 'CDFO'

CDFP2 = 'CDFP2'

CDFX1 = 'CDFX1'

CH2Cl2 = 'CH2Cl2'

CH4 = 'CH4'

CO = 'CO'

CO2 = 'CO2'

CS2 = 'CS2'

Cd = 'Cd'

Cholanthrene = 'Cholanthrene'

Chrysene = 'Chrysene'

Co = 'Co'

Coronene = 'Coronene'

Cr = 'Cr'

Crotonaldehyde = 'Crotonaldehyde'

Cu = 'Cu'

DBDPE = 'DBDPE'

DCMU = 'DCMU'

Dibenzofuran = 'Dibenzofuran'

Dibenzothiophene = 'Dibenzothiophene'

Dieldrin = 'Dieldrin'

EC = 'EC'

Endrin = 'Endrin'

Fe = 'Fe'

Fluoranthene = 'Fluoranthene'

Fluorene = 'Fluorene'

Glyoxal = 'Glyoxal'

H2S = 'H2S'

HBB = 'HBB'

HBCD = 'HBCD'

HCB = 'HCB'

HCHO = 'HCHO'

HCl = 'HCl'

HF = 'HF'

HNO3 = 'HNO3'

Heptachlor = 'Heptachlor'

Hg = 'Hg'

Hg0 = 'Hg0'

Isoproturon = 'Isoproturon'

MCCP = 'MCCP'

Methacroleine = 'Methacroleine'

Methylglyoxal = 'Methylglyoxal'

Mn = 'Mn'

Mo = 'Mo'

N2O = 'N2O'

NH3 = 'NH3'

NH4 = 'NH4'

NO = 'NO'

NO2 = 'NO2'

NO3 = 'NO3'

NOy = 'NOy'

NT = 'NT'

NVPM1 = 'NVPM1'

NVPM10 = 'NVPM10'

Naphtalene = 'Naphtalene'

Naphthalene = 'Naphthalene'

Ni = 'Ni'

O3 = 'O3'

OC = 'OC'

PAH = 'PAH'

PAN = 'PAN'

PBEB = 'PBEB'

PBT = 'PBT'

PCB_122 = 'PCB_122'

PCB_123 = 'PCB_123'

PCB_128 = 'PCB_128'

PCB_138 = 'PCB_138'

PFBA = 'PFBA'

PFBS = 'PFBS'

PFDA = 'PFDA'

PFDS = 'PFDS'

PFHpA = 'PFHpA'

PFHxA = 'PFHxA'

PFHxS = 'PFHxS'

PFNA = 'PFNA'

PFOA = 'PFOA'

PFOS = 'PFOS'

PFOSA = 'PFOSA'

PFPeA = 'PFPeA'

PFUnDA = 'PFUnDA'

PM1 = 'PM1'

PM10 = 'PM10'

Pb = 'Pb'

Pentenes = 'Pentenes'

Perylene = 'Perylene'

Phenanthrene = 'Phenanthrene'

Propanal = 'Propanal'

Pyrene = 'Pyrene'

Radioactivity = 'Radioactivity'

Retene = 'Retene'

SA = 'SA'

SCCP = 'SCCP'

SO2 = 'SO2'

SPM = 'SPM'

Se = 'Se'

TBP = 'TBP'

TCDD = 'TCDD'

TI = 'TI'

TP = 'TP'

UFPs = 'UFPs'

V = 'V'

VC = 'VC'

VPM1 = 'VPM1'

VPM10 = 'VPM10'

Valeraldehyde = 'Valeraldehyde'

Vanadium = 'Vanadium'

Zn = 'Zn'

k = 'k'

pH = 'pH'

precip_amount = 'precip_amount'

precip_amount_off = 'precip_amount_off'

trans_NO = 'trans_NO'

airbase.cli.callback(version=<typer.models.OptionInfo object>)[source]

Download Air Quality Data from the European Environment Agency (EEA)

Parameters:: version (bool | None) –

airbase.cli.historical(countries=<typer.models.OptionInfo object>, pollutants=<typer.models.OptionInfo object>, cities=<typer.models.OptionInfo object>, frequency=<typer.models.OptionInfo object>, metadata=<typer.models.OptionInfo object>, path=<typer.models.OptionInfo object>, summary_only=<typer.models.OptionInfo object>, country_subdir=<typer.models.OptionInfo object>, overwrite=<typer.models.OptionInfo object>, quiet=<typer.models.OptionInfo object>)[source]

Historical Airbase data delivered between 2002 and 2012 before Air Quality Directive 2008/50/EC entered into force.

Use -c/–country and -p/–pollutant to restrict the download specific countries and pollutants, e.g. - download only Norwegian, Danish and Finish sites

airbase historical -c NO -c DK -c FI

download only SO2, PM10 and PM2.5 observations airbase historical -p SO2 -p PM10 -p PM2.5

Use -C/–city to further restrict the download to specific cities, e.g. - download only PM10 and PM2.5 from Valletta, the Capital of Malta

airbase historical -C Valletta -c MT -p PM10 -p PM2.5

Parameters:

countries (List[Country]) –
pollutants (List[Pollutant]) –
cities (List[str]) –
frequency (Frequency | None) –
metadata (bool) –
path (Path) –
summary_only (bool) –
country_subdir (bool) –
overwrite (bool) –
quiet (bool) –

airbase.cli.unverified(countries=<typer.models.OptionInfo object>, pollutants=<typer.models.OptionInfo object>, cities=<typer.models.OptionInfo object>, frequency=<typer.models.OptionInfo object>, metadata=<typer.models.OptionInfo object>, path=<typer.models.OptionInfo object>, summary_only=<typer.models.OptionInfo object>, country_subdir=<typer.models.OptionInfo object>, overwrite=<typer.models.OptionInfo object>, quiet=<typer.models.OptionInfo object>)[source]

Unverified data transmitted continuously (Up-To-Date/UTD/E2a) data from the beginning of 2024.

Use -c/–country and -p/–pollutant to restrict the download specific countries and pollutants, e.g. - download only Norwegian, Danish and Finish sites

airbase unverified -c NO -c DK -c FI

download only SO2, PM10 and PM2.5 observations airbase unverified -p SO2 -p PM10 -p PM2.5

Use -C/–city to further restrict the download to specific cities, e.g. - download only PM10 and PM2.5 from Valletta, the Capital of Malta

airbase unverified -C Valletta -c MT -p PM10 -p PM2.5

Parameters:

countries (List[Country]) –
pollutants (List[Pollutant]) –
cities (List[str]) –
frequency (Frequency | None) –
metadata (bool) –
path (Path) –
summary_only (bool) –
country_subdir (bool) –
overwrite (bool) –
quiet (bool) –

airbase.cli.verified(countries=<typer.models.OptionInfo object>, pollutants=<typer.models.OptionInfo object>, cities=<typer.models.OptionInfo object>, frequency=<typer.models.OptionInfo object>, metadata=<typer.models.OptionInfo object>, path=<typer.models.OptionInfo object>, summary_only=<typer.models.OptionInfo object>, country_subdir=<typer.models.OptionInfo object>, overwrite=<typer.models.OptionInfo object>, quiet=<typer.models.OptionInfo object>)[source]

Verified data (E1a) from 2013 to 2023 reported by countries by 30 September each year for the previous year.

Use -c/–country and -p/–pollutant to restrict the download specific countries and pollutants, e.g. - download only Norwegian, Danish and Finish sites

airbase verified -c NO -c DK -c FI

download only SO2, PM10 and PM2.5 observations airbase verified -p SO2 -p PM10 -p PM2.5

Use -C/–city to further restrict the download to specific cities, e.g. - download only PM10 and PM2.5 from Valletta, the Capital of Malta

airbase verified -C Valletta -c MT -p PM10 -p PM2.5

Parameters:

countries (List[Country]) –
pollutants (List[Pollutant]) –
cities (List[str]) –
frequency (Frequency | None) –
metadata (bool) –
path (Path) –
summary_only (bool) –
country_subdir (bool) –
overwrite (bool) –
quiet (bool) –

airbase.cli.version_callback(value)[source]

Parameters:: value (bool) –