Hydrionis API | Hydrionis

Endpoints

Endpoint	Returns
/api/v1/index.json	Service index: available endpoints, record counts and publication metadata.
/api/v1/metrics.json	Every metric with its definition, unit, native geography, aggregation rules and comparability notes.
/api/v1/sources.json	The full source registry including structured rights for each source.
/api/v1/geographies.json	Every geography: world, continents, regions, countries, UK nations, councils, utility areas, basins and oceans.
/api/v1/entities.json	Every entity: utilities, water bodies, aquifers, infrastructure, events, enforcement, bottled waters, sectors, standards and more.
/api/v1/observations.json	Every observation with metric, subject, period, value, unit, basis, source, confidence and retrieval date.
/api/v1/observations/by-metric/{metricId}.json	All observations for one metric.
/api/v1/observations/by-subject/{subjectId}.json	All observations for one country, place or entity.
/api/v1/guides.json	Guide index with slugs, sections, summaries and search intents.
/api/v1/diagrams.json	Diagram index with titles, summaries and text alternatives.
/api/v1/tools.json	Tool registry with method and caveats for each.

Example

curl https://hydrionis.com/api/v1/observations/by-subject/country-gbr.json

{
  "subjectId": "country-gbr",
  "count": 8,
  "observations": [
    {
      "id": "renewable-water-resources::country-gbr::1990-01-01",
      "metricId": "renewable-water-resources",
      "value": 147,
      "unit": "km³/yr",
      "period": { "start": "1990-01-01", "end": "2022-12-31", "kind": "multi-year" },
      "basis": "derived",
      "sourceId": "fao-aquastat",
      "confidence": "medium",
      "qualifier": "transcribed-pending-collection",
      "retrieved": "2026-08-23"
    }
  ]
}

Fields you should not ignore

basis — whether the value was measured, reported, calculated, derived, aggregated, estimated, modelled or inferred. The last three are not observations.
qualifier — currently carries transcribed-pending-collection on values hand-loaded from published sources rather than collected automatically.
confidence — high, medium or low, set per observation.
sourceId — resolves against /api/v1/sources.json, which carries the licence terms governing what you may do with the value.

How access is expected to be layered

Stated so that the boundary is legible now rather than announced later. Nothing below this line is built, and the first row is the only one that currently exists.

Layer	What it is	Status
Public data API	Everything on this page. Free and open access to data that can appropriately be distributed as public files, generated from the same registries as the site.	This is what exists. Free, no key, no metering.
Developer API	A stable query experience over the same model — filtering and selection rather than pre-generated files. A key and a reasonable quota would exist to make it operable, not to charge for it.	Not built. Expected to remain free.
Professional and enterprise access	Higher volume, bespoke extracts, derived intelligence, and licensed data where a publisher’s terms permit onward supply. Support and a stated refresh cadence.	Not built. Bespoke extracts are available now by enquiry rather than through an endpoint.

No paid layer can widen what a publisher withheld. Access classes only ever restrict further, which is why the rights position is resolved per source and stated per dataset. See Hydrionis Professional for what is available today.