bolster.data_sources.ni_water

Northern Ireland Water Quality Data Integration.

Data Source: Northern Ireland Water provides public water quality data through the OpenDataNI portal at https://admin.opendatani.gov.uk/. The service offers water quality test results from customer tap supply points across Northern Ireland, including chemical analysis, pH levels, hardness classifications, and safety parameters. Additionally, postcode-to-water-zone mapping is available for geographic analysis.

Update Frequency: Water quality data is published annually, typically reflecting the previous calendar year’s test results. The dataset includes comprehensive testing from customer tap supply points across all water zones in Northern Ireland. Postcode mapping data is updated as required when zone boundaries change.

Example

Access water quality data and zone information:

>>> from bolster.data_sources import ni_water
>>> quality_data = ni_water.get_water_quality()
>>> 'NI Hardness Classification' in quality_data.columns
True
>>> len(quality_data) > 0
True

The module provides utilities for analyzing water quality across Northern Ireland’s supply zones, with support for both current quality data and historical zone mapping.

Attributes

logger

POSTCODE_DATASET_URL

WATER_QUALITY_CSV_URL

T_HARDNESS

INVALID_ZONE_IDENTIFIER

Functions

get_water_quality_csv_data()

Get the latest water quality CSV data from OpenDataNI.

get_postcode_to_water_supply_zone()

Using data from OpenDataNI to generate a map from NI Postcodes to Water Supply Zone.

get_water_quality_by_zone(zone_code[, strict])

Get the latest Water Quality for a given Water Supply Zone.

get_water_quality()

Get a DataFrame of Water Quality Data from OpenDataNI.

Module Contents

bolster.data_sources.ni_water.logger[source]
bolster.data_sources.ni_water.POSTCODE_DATASET_URL = 'https://admin.opendatani.gov.uk/dataset/38a9a8f1-9346-41a2-8e5f-944d87d9caf2/resource/f2bc12c1-4...[source]
bolster.data_sources.ni_water.WATER_QUALITY_CSV_URL = 'https://admin.opendatani.gov.uk/dataset/38a9a8f1-9346-41a2-8e5f-944d87d9caf2/resource/02d85526-c...[source]
bolster.data_sources.ni_water.T_HARDNESS[source]
bolster.data_sources.ni_water.INVALID_ZONE_IDENTIFIER = 'No Zone Identified'[source]
bolster.data_sources.ni_water.get_water_quality_csv_data()[source]

Get the latest water quality CSV data from OpenDataNI.

This function downloads and caches the complete water quality dataset which contains all results from customer tap supply points.

Returns:

Complete water quality data with columns:

  • Year: Sample year

  • Sample Location: Location description

  • Site Code: Unique site identifier

  • Site Name: Human-readable site name

  • Sample Id Text: Unique sample identifier

  • Sample Date: Date of sample collection

  • Postcode: Postcode for the sample location

  • Parameter: Water quality parameter name (e.g., ‘Total Hardness (mg/l)’)

  • PCV Limit: Prescribed Concentration Value limit

  • Result: Numeric test result

  • Report Value: Formatted result value

  • Units: Unit of measurement

Return type:

pd.DataFrame

Raises:

  • HTTPError – If the CSV download fails

  • RuntimeError – If no data is found

bolster.data_sources.ni_water.get_postcode_to_water_supply_zone()[source]

Using data from OpenDataNI to generate a map from NI Postcodes to Water Supply Zone.

>>> zones = get_postcode_to_water_supply_zone()
>>> len(zones)
49006

Zones is keyed off postcode to a Water Supply Zone >>> zones[‘BT1 1AA’] ‘ZS0107’

There are much fewer zones than postcodes >>> len(set(zones.values())) 65

And many postcodes that aren’t associated with any zone >>> len([k for k,v in zones.items() if v == INVALID_ZONE_IDENTIFIER]) 97

bolster.data_sources.ni_water.get_water_quality_by_zone(zone_code, strict=False)[source]

Get the latest Water Quality for a given Water Supply Zone.

Now uses modern OpenDataNI CSV data instead of the deprecated HTML API. The zone_code can be either a legacy zone code (like ‘ZS0101’) or a site code from the CSV data (like ‘BALM’).

Parameters:

  • zone_code (str) – Water supply zone identifier or site code

  • strict – If True, raise ValueError for invalid zones

Returns:

Water quality data in legacy API format with indices like:

  • Water Supply Zone: Human-readable zone name

  • Total Hardness (mg/l): Hardness as mg/l

  • Total Hardness (mg CaCO3/l): Hardness as mg CaCO3/l

  • Clark English Degrees: English degrees of hardness

  • French Degrees: French degrees of hardness

  • German Degrees: German degrees of hardness

  • NI Hardness Classification: Categorical hardness level

  • Dishwasher Setting: Recommended dishwasher setting

Return type:

pd.Series

Raises:

  • ValueError – If zone_code is invalid and strict=True

  • HTTPError – If CSV data cannot be downloaded

  • RuntimeError – If CSV data is empty

Example usage:

data = get_water_quality_by_zone(‘BALM’) # Using CSV site code print(data[‘Water Supply Zone’]) print(data[‘NI Hardness Classification’])

bolster.data_sources.ni_water.get_water_quality()[source]

Get a DataFrame of Water Quality Data from OpenDataNI.

This function now uses the modern CSV data source instead of the deprecated HTML API. It returns water quality data for all available sites.

Returns:

Water quality data with one row per site/zone.

Columns include hardness measurements, classifications, and other water quality parameters. The ‘NI Hardness Classification’ column uses categorical data type with proper ordering.

Return type:

pd.DataFrame

Raises:

  • HTTPError – If CSV data cannot be downloaded

  • RuntimeError – If CSV data is empty

Example usage:

df = get_water_quality() print(df.shape) # Number of rows and columns print(df[‘NI Hardness Classification’].value_counts(sort=False))

# Show available sites print(df.index.tolist()) # Site codes

# Get hardness data hardness_summary = df.groupby(‘NI Hardness Classification’).size() print(hardness_summary)