# TidalWaiv public bot API (v1)

Base URL: https://www.tidalwaiv.co.uk/api/v1
Interactive reference: https://www.tidalwaiv.co.uk/api/docs
OpenAPI schema: https://www.tidalwaiv.co.uk/api/openapi.json

No API key or account is required. The API is public and read-only. It serves
Environment Agency bathing-water data for England, processed by TidalWaiv.
It does not publish posts, send messages or operate an X bot for you.

## 1. Find a bathing water

GET /api/v1/sites?q=Brean

Search is case-insensitive and matches names, districts or an exact site ID.
Use region to filter by region label; limit is 1-100 (default 20), offset starts
at zero. The total field is the number of matching sites before pagination.
Choose the returned site_id. Names can be ambiguous: preserve every match and
ask the caller to choose by district/site ID rather than guessing.

## 2. Fetch a summary and share/media links

GET /api/v1/sites/ukk2302-35600/summary

The response includes site metadata, description, sample coverage, a long-term
trend, the latest OFFICIAL annual classification with its year, summary text,
share_text, and absolute links to the canonical page, social image, CSV, full
history and downloadable PNG graphs. GET /api/v1/sites/{site_id} is an alias.
Post or share links.page rather than the old /?site=... URLs. share_text includes
the canonical page URL; use summary for a longer explanation. Check your target
platform's text and media limits before posting. The API never posts on your behalf.

## 3. Get the underlying data

GET /api/v1/sites/ukk2302-35600/history
GET /api/v1/sites/ukk2302-35600/samples.csv

History contains dated points, coverage statistics, trend_pct and annual
classifications. Missing measurements are null in JSON and empty in CSV.
Units are CFU per 100 ml. Fields ec/ie/fc/fs/tc are source indicator counts after
the website's detection-limit handling; ec_unified/ie_unified include historical
FC/FS proxies. Four-year geometric means require a complete four-year span and
at least eight samples. No missing measurement is replaced with zero.
The trend is the percentage change between the earliest and latest four-year
rolling points in different calendar years, using the average of available EC/IE
geometric means at each point, matching the website.
A negative trend means lower bacterial counts. Null means insufficient history.
This is a bacterial-indicator trend, not a measurement of all pollution.
Annual classification data_source distinguishes official assessments from estimates.
Never describe a newer estimated classification as the latest official assessment.
retrieved_at is the cached source-fetch time; coverage.end_date is the last sample date.

## 4. Download a graph for an attachment

GET /api/v1/sites/ukk2302-35600/charts/samples.png
GET /api/v1/sites/ukk2302-35600/charts/ec.png
GET /api/v1/sites/ukk2302-35600/charts/ie.png
GET /api/v1/sites/ukk2302-35600/charts/classifications.png

PNG downloads need no browser or JavaScript. samples.png contains aligned EC/IE
panels (1200x1000). Individual graphs are 1200x675. Sample axes are logarithmic
and show harmonised sample points and four-year geometric means. Classification
graphs distinguish official assessments from historical estimates. These are
server-rendered graphs from the same processed data as the interactive website.
Use links.social_image for the 1200x630 social summary card; use links.page for
a link preview. Image downloads may take longer on the first request.

## Reliability and responsible use

Cache successful responses for at least five minutes, follow Cache-Control, and
request individual sites on demand rather than repeatedly polling every site.
Source snapshots are cached for up to an hour; this is not a real-time feed.
Return codes: 200 success, 404 unknown site, 422 invalid query/chart type,
503 source temporarily unavailable (retry using Retry-After). Handle hosting
429 responses with backoff. Do not treat an error as an empty successful history.
Attribute Environment Agency source data and TidalWaiv's historical processing.
Historical bacterial indicators and annual assessments do not establish whether
water is safe today or whether there is an active sewage discharge. Consult
official current notices separately. Methodology: https://www.tidalwaiv.co.uk/methodology/

## Example (Python)

import requests
base = "https://www.tidalwaiv.co.uk/api/v1"
response = requests.get(base + "/sites", params={"q": "Brean"}, timeout=60)
response.raise_for_status()
matches = response.json()["items"]
if len(matches) != 1:
    raise ValueError("Choose a specific bathing water from the returned matches")
response = requests.get(matches[0]["summary_url"], timeout=120)
response.raise_for_status()
summary = response.json()
print(summary["share_text"])
image = requests.get(summary["links"]["charts"]["samples"], timeout=120)
image.raise_for_status()
with open("brean-samples.png", "wb") as file:
    file.write(image.content)