API

Start with a site

Search by a place or station name. You can narrow the result with a provider identifier, such as ea_bathing, ea_wqe, ea_hydrology or uk_air.

curl 'https://semantic.construction/v1/sites?provider=ea_bathing&search=Kingston&limit=10'

Open this request →

1. Take a site's id from the returned items list.
2. Request /sites/{id}/series to find its metrics (measurement series).
3. Use a series id in /series/{id}/observations to read its history.
4. Use the series metric_id in /metrics/{metric_id} for its explanation and references.

Site and series IDs are opaque 32-character hexadecimal identifiers. Keep them unchanged. For an exact publisher identity, query sites with both provider and source_id; matching station names alone does not establish that two records describe the same site.

Available requests

All endpoints below use GET and return JSON. Prefix each path with /v1.

Recent reporting

Open reporting statistics →

The reporting counts are station feeds with measurements in each period, not numbers of measurements. They use observation dates, not download dates. Importing older history does not increase today's count. Each publisher's station ID counts as a separate feed; two feeds may describe the same physical station. Entries without a usable location are counted separately from the area totals.

Gaps in our archive do not establish that a station is offline. Publisher statuses retain their own check dates, and unavailable or old status information is kept separate. Periodic laboratory samples are not treated as silent sensors.

Map measurements

GET /v1/map/observations returns the last stored observation in each measurement series at located sites within a bounding box. It includes water, weather and UK-AIR measurements, plus the latest archived Thames overflow monitor states. Monitor states describe source reports; they are not numeric measurements.

curl 'https://semantic.construction/v1/map/observations?bbox=-0.5,51.3,0.2,51.7&provider=ea_bathing&limit=500'

• bbox is required: four comma-separated WGS84 coordinates in west,south,east,north order, with longitude first. The box must not wrap across the antimeridian.
• provider is optional. Accepted values are ea_wqe, ea_hydrology, ea_flood, ea_bathing, metoffice_land, uk_air and thames_overflows. Omit it to include all sources.
• limit defaults to 500 features and allows at most 1,000. A feature represents one metric or one monitor report. The all-source view interleaves providers and stations before additional channels at the same station; choosing one provider uses station-name order.
• reported_since is an optional RFC3339 timestamp. It selects stations with a measurement between that time and query time, before applying the result limit. Overflow monitors use the latest archived status-check time. All metrics at qualifying stations remain available, including older measurements. Future-dated readings do not qualify a station.

The GeoJSON response has Point features with flat properties. Measurement features carry a series_id; monitor features carry their site_id. These exact IDs connect to measurement history or archived site definitions. Similar site names are not joined across sources.

• Identity: provider, station_id (publisher site identifier), measure_id (publisher series identifier), source_observation_id, name, parameter, metric_id and kind.
• Result and timing: value, raw_value, unit, qualifier, quality, observed_at, optional interval_end, source_time and time_basis.
• Method and source: matrix, method, statistic, period_seconds, datum, optional interpretation_pending, source_url, retrieved_at and archive_id.

Alongside type and features, the response has top-level queried_at, returned, truncated, limit, bbox and provider. The returned bbox is an array in the same coordinate order; an empty provider string means all supported sources. The query timestamp describes when the database was read; each observation retains its own date. When truncated is true, more series matched than were returned. Narrow the box or choose a provider. This bounded map result has no continuation cursor.

A last stored observation can be old or nonnumeric; a missing numeric value stays null. The latest record is selected by its observation date, without falling back to an older numeric value. The endpoint includes stored observations and archived monitor reports at located sites. It does not describe present conditions, return a complete year per series or measure total agency coverage. Date-range and text-search filters are not supported on this route.

Weather results retain their source QC JSON, averaging or accumulation period and timestamps. Air and water temperatures, rainfall totals and rainfall rates remain distinct. A series with interpretation_pending: true remains available in history but is excluded from numeric colour scales.

On the map, use Search this view after moving or zooming. Opening the map or changing its provider filter makes one request. Panning does not automatically load more records, and there is no automatic polling. These requests read stored data only.

Only stations reporting in the last 5 days applies this station filter. Turning it off restores older stations. The separate source-date filter still applies to individual displayed measurements.

Charts

/series/{id}/chart?from=2026-09-01&to=2026-09-02&points=1000 covers the selected interval with a bounded number of marks. points defaults to 1,000 and allows 32–2,000; chart ranges allow at most 366 days.

mode: "observations" returns exact sparse measurements in items. Denser results use mode: "time-buckets" with at most floor(points / 4) buckets. Each bucket retains actual first, last, eligible minimum and eligible maximum measurements, including their timestamps and provenance. No means, interpolation or predictions are supplied; joining these selected marks would hide omitted measurements.

Buckets include empty intervals, total and eligible counts, flagged, censored and missing counts, and max_gap_seconds. Counts can overlap. The largest gap measures intervals between stored observations; it does not establish why a source was absent. Raw observations remain separately available through the paginated observations route.

Nearby and river context

/context/series requires WGS84 lon and lat. radius_m defaults to 10,000 metres and allows more than zero through 50,000. It returns tidal level, water level, water temperature, air temperature, rainfall and river flow categories. Each item keeps its site and series identities, distance and first/last stored dates.

/rivers/context requires the station's provider and source_id. Upstream and downstream distances each default to 10,000 metres and allow 0–50,000. Associations follow the configured directed river network, with its version and binding evidence. An unknown association returns associated: false. Geographic proximity alone does not establish river connectivity, and mapped direction does not describe instantaneous tidal current.

Both routes accept paired from and to parameters. With dates, candidates must have an actual stored observation in that interval, and returned first/last dates refer to that interval. Without dates, discovery uses all retained history. per_category defaults to 3 and allows 1–20 series. One channel from each station ranks before further channels; category truncated flags indicate omitted candidates. River stations can include associations without stored measurements; categories requires observations.

Station definitions

/sites/{id}/metadata?limit=100 returns retained site and series definitions, newest first. limit defaults to 100 and allows 1–500. The result has site_id, items and truncated; there is no continuation cursor.

Each item identifies the entity, archive, parser version, retrieval time, origin and original definition record. Repeated definitions can appear. retrieved_at is the archive time, not necessarily when a change happened. Records with origin: "merged_baseline" retain an earlier combined definition and cannot establish a historical transition. The route does not infer equivalent stations or causes of outages.

Caching and saved results

Successful data responses use Cache-Control: public, max-age=15, must-revalidate. The reporting summary uses max-age=120; metric definitions use max-age=3600. Both supply an ETag; send it as If-None-Match to allow a 304 Not Modified response when the response bytes match. Responses containing query timestamps can change ETag even when measurements are unchanged. Health and errors use no-store.

Each SQL query uses a consistent database snapshot. Separate pages can reflect later imports or corrections; a cursor does not freeze a database edition. Save the returned data and provenance when an analysis must be reproducible. The station report shares a cutoff between its catalogue and station details. Source checks and measurement times remain separate.