Interoperability
Open data
Every assessment Rivulet produces can leave it as FHIR R4, profiled to the OneAquaHealth Implementation Guide, so it can flow into the systems that already exist instead of sitting in another silo. No account or key is needed to read it.
How the numbers are produced is on the method page.
Read-only FHIR endpoint
Base URL https://rivulet-xi.vercel.app/fhir. Everything is read-only. Try the examples: each link returns real data for one Coimbra stream.
| Request | Returns |
|---|---|
GET /fhir/metadata try it | CapabilityStatement: exactly what this endpoint supports |
GET /fhir/Location?city=<city> try it | Water bodies Rivulet has mapped in a city (paged with _count and _offset) |
GET /fhir/Location/<id> try it | One water body as a LocationOah |
GET /fhir/Observation?subject=Location/<id> try it | Citizen indicator Observations (ObservationIndicatorsOah) for a water body |
GET /fhir/DetectedIssue?implicated=Location/<id> try it | The One Health warning for a water body, with the reports that evidence it |
GET /api/city/<city>/data try it | A whole city as a CSV: each stream's status class, 90% interval, data confidence, report counts and One Health concern |
GET /api/fhir/Observation?waterbody=<id> try it | The complete export for one water body in a single Bundle: Location, Observations, Provenance and any DetectedIssue |
Resource model
| Concept | Resource | Profile and notes |
|---|---|---|
| A stream section | Location | LocationOah (identifier, name, mode = instance, position) |
| One thing a resident reported | Observation | ObservationIndicatorsOah; measured values use OneAquaHealth codes and UCUM units |
| Who reported it and what assembled it | Provenance | Core R4: author (a pseudonymous observer) and assembler (the Rivulet web app) |
| A warning worth acting on near people or animals | DetectedIssue | Core R4: severity, the Location, and the Observations that evidence it |
| The classified outcome | Observation | Rivulet code wfd-ecological-status, valued high to bad; indicative, not an official classification |
Code systems
Real measurements (pH, dissolved oxygen, water temperature, nitrate) use the OneAquaHealth code system, with UCUM units. What a resident sees but cannot measure (clarity, a sewage smell, algae, foam, dead fish, litter, how fast the water moves, which animal groups they recognised) is never passed off as a laboratory analyte such as coliforms or suspended solids. It uses a clearly separated Rivulet code system, together with the Forel–Ule index, the indicative status class and the One Health concern, so the boundary between adopted and derived vocabulary stays auditable.
/fhir/CodeSystem/rivulet-derived lists every code Rivulet adds and says what it is and is not.
Validation
On every change, a workflow builds the OneAquaHealth guide from source and runs the official HL7 validator over Rivulet’s own output: a sample export, the endpoint’s search results, its CapabilityStatement and its CodeSystem. The current result is 0 errors; the warnings are a best-practice recommendation (resources should carry a narrative) and UCUM codes an offline validator cannot look up.
What this shows: a representative sample passes, offline. What it does not: it is not a conformance claim by the guide’s authors, it does not check every row in the live database, and external terminologies (UCUM, SNOMED) are not looked up.
What is in the data, and what is not
- Held observations stay out. Reports that fail plausibility checks wait for a person to review them and are never served until approved.
- Demonstration data is labelled. Seeded observations carry
meta.tagHTEST(“test health data”), the standard HL7 code, so a downstream system can filter them out of genuine citizen data. Coimbra’s reports are of this kind. - Privacy. An observer is a pseudonym. Exact GPS positions and GPS accuracy of individual reports are never exported; a stream is located by its mapped path. Photos are not stored or exported.
- Indicative, not authoritative. Status classes and concerns are estimates from what residents can see and smell, not laboratory or public-health assessments.
Sources and attribution
- Stream geometry and nearby places: © OpenStreetMap contributors, available under the Open Database Licence.
- Satellite cross-check: contains modified Copernicus Sentinel data 2026, processed by Rivulet as an independent, coarse check against citizen reports, never a replacement for them.
- Standards: HL7 FHIR R4 and the OneAquaHealth Implementation Guide by HL7 Europe. Rivulet is an independent prototype and is not endorsed by the OneAquaHealth consortium, the EU or IEEE.
- Code: open under Apache-2.0 at github.com/it-withend/rivulet.