Hydrological data formats: CSV, WaterML 2.0 and APIs

A district flood cell asks the state water resources department for last monsoon's river levels at a bridge. A spreadsheet arrives by email. The columns say "Date", "Time" and "Level". Is the time Indian Standard Time or UTC? Is the level in metres or centimetres, above the gauge zero or above mean sea level? Is a blank cell a missing reading or a dry channel? Were the values corrected after the gauge was resurveyed?

These are questions about the hydrological data format: the agreed way of writing a measurement down so that another office, with other software, reads it exactly as meant. This article shows one water-level series as CSV, as WaterML 2.0 and as a JSON API response, explains what each carries, and then looks at open standards for sharing water data between agencies.

Why does the data format decide whether water data can be shared?

Because a number without its context cannot be reused safely. The WMO Guide to Hydrological Practices (WMO-No. 168) notes that standards for exchanging hydrological data "have been developed but not widely adopted", and that the most common exchange formats are the de facto ones produced by data loggers and database software [1]. Each makes its own silent assumptions, which every receiving agency has to guess.

• Time zone. Indian Standard Time is five and a half hours ahead of UTC; a time without an offset could be either (see time stamps you can trust).
• Unit, as a code a program can read, not words in a column heading.
• Datum: what zero means. Records on different datums can disagree by metres (see gauge zero, datum and benchmarks).
• Quality flag and gaps: checked, suspect, estimated or missing, with missing values marked, not blank or zero.
• Series metadata: station, sensor, instantaneous or averaged values, provisional or validated status, and version.

One water-level series, three formats

The examples below use the same five readings, invented for illustration: 15-minute water levels at a fictional station EX-001 on 14 July 2025, in metres above the gauge zero. The 08:30 reading is missing and the 08:45 reading is flagged as suspect.

CSV: easy to open, easy to misread

CSV (comma-separated values) is plain text with one record per line and fields separated by commas. It was used for years before anyone wrote it down: RFC 4180, published in 2005, says the format "has never been formally documented" and that there are "considerable differences among implementations" [2]. RFC 4180 defines the record structure, quoting rules and an optional header line, but nothing about dates, units or missing values [2].

This is the kind of file that is usually exchanged:

Date,Time,Level
14/07/2025,08:00,2.412
14/07/2025,08:15,2.436
14/07/2025,08:30,
14/07/2025,08:45,2.481
14/07/2025,09:00,2.503

A reader cannot tell the time zone, the unit, the datum, whether the blank at 08:30 is a gap or an error, or that 08:45 is doubtful. A file that answers those questions might look like this:

station_id,time,water_level,unit,datum,quality
EX-001,2025-07-14T08:00:00+05:30,2.412,m,gauge zero,good
EX-001,2025-07-14T08:15:00+05:30,2.436,m,gauge zero,good
EX-001,2025-07-14T08:30:00+05:30,,m,gauge zero,missing
EX-001,2025-07-14T08:45:00+05:30,2.481,m,gauge zero,suspect
EX-001,2025-07-14T09:00:00+05:30,2.503,m,gauge zero,good

Each time now follows ISO 8601, the international format for dates and times, in the profile used on the internet (RFC 3339). It has a numeric offset calculated as "local time minus UTC", so 08:00:00+05:30 and 02:30:00Z are the same instant (Z means UTC) [3]. The unit, datum and flag are columns, so they survive sorting, filtering and copying.

Repeating "gauge zero" on every line is crude, and its height above a national datum must still be documented. The W3C Metadata Vocabulary for Tabular Data lets a small companion file describe each CSV column, including its datatype and date format [4].

WaterML 2.0: the series carries its own rules

WaterML 2.0 Part 1 – Timeseries is an Open Geospatial Consortium (OGC) standard for encoding hydrological time series in XML. It was developed under the joint WMO and OGC Hydrology Domain Working Group [5], and WMO-No. 168 describes it as a representation developed jointly by WMO and OGC [1]. The same five readings look like this (namespace declarations and the surrounding observation, which names the station and the observed property, are left out):

<wml2:MeasurementTimeseries gml:id="EX-001.level">
  <wml2:defaultPointMetadata>
    <wml2:DefaultTVPMeasurementMetadata>
      <wml2:quality xlink:href="http://www.opengis.net/def/waterml/2.0/quality/good"/>
      <wml2:uom code="m"/>
      <wml2:interpolationType
        xlink:href="http://www.opengis.net/def/waterml/2.0/interpolationType/Continuous"/>
    </wml2:DefaultTVPMeasurementMetadata>
  </wml2:defaultPointMetadata>
  <wml2:point><wml2:MeasurementTVP>
    <wml2:time>2025-07-14T08:00:00+05:30</wml2:time>
    <wml2:value>2.412</wml2:value>
  </wml2:MeasurementTVP></wml2:point>
  <wml2:point><wml2:MeasurementTVP>
    <wml2:time>2025-07-14T08:15:00+05:30</wml2:time>
    <wml2:value>2.436</wml2:value>
  </wml2:MeasurementTVP></wml2:point>
  <wml2:point><wml2:MeasurementTVP>
    <wml2:time>2025-07-14T08:30:00+05:30</wml2:time>
    <wml2:value xsi:nil="true"/>
    <wml2:metadata><wml2:TVPMeasurementMetadata>
      <wml2:nilReason xlink:href="http://www.opengis.net/def/nil/OGC/0/missing"/>
    </wml2:TVPMeasurementMetadata></wml2:metadata>
  </wml2:MeasurementTVP></wml2:point>
  <wml2:point><wml2:MeasurementTVP>
    <wml2:time>2025-07-14T08:45:00+05:30</wml2:time>
    <wml2:value>2.481</wml2:value>
    <wml2:metadata><wml2:TVPMeasurementMetadata>
      <wml2:quality xlink:href="http://www.opengis.net/def/waterml/2.0/quality/suspect"/>
    </wml2:TVPMeasurementMetadata></wml2:metadata>
  </wml2:MeasurementTVP></wml2:point>
  <wml2:point><wml2:MeasurementTVP>
    <wml2:time>2025-07-14T09:00:00+05:30</wml2:time>
    <wml2:value>2.503</wml2:value>
  </wml2:MeasurementTVP></wml2:point>
</wml2:MeasurementTimeseries>

It is longer, but the questions from the introduction are answered by rules, not by goodwill [5]:

• Time zone is compulsory. Every time must include a zone, either Z or a signed offset such as +05:30.
• Units are codes. Units must come from the Unified Code for Units of Measure (UCUM), and every value must have a unit, given directly or by default.
• Defaults with exceptions. defaultPointMetadata sets unit, quality and interpolation type once; a point can override it, as 08:45 does.
• Gaps are explicit. A null value must carry a reason, such as missing.
• Quality uses a shared list: good, suspect, estimate, poor, unchecked and missing, each identified by a web address that any software can read.
• What the value represents. The interpolation type says whether a value is instantaneous, or an average, maximum, minimum or total over an interval.
• Datum and status. The monitoring point can state its vertical datum, including a gauge zero given as a height above a reference datum. An observation can carry a status such as provisional or validated, though the list of statuses is not fixed.

A companion, Part 2, covers ratings, gaugings and sections [1]. The cost is size: WMO-No. 168 notes that XML can make time-series files ten times larger than plain text [1].

JSON from a web API: compact, but only as good as its documentation

JSON (JavaScript Object Notation) is a lightweight text format with four primitive types (strings, numbers, booleans and null) and two structures (objects and arrays) [6]. It has no date type and no units, so a JSON API needs a documented data model. The OGC SensorThings API supplies one [7]. Here, a client asks for the observations of one data stream:

GET /v1.1/Datastreams(42)/Observations?$orderby=phenomenonTime

{
  "value": [
    { "phenomenonTime": "2025-07-14T02:30:00Z", "result": 2.412,
      "parameters": { "quality": "good" } },
    { "phenomenonTime": "2025-07-14T02:45:00Z", "result": 2.436,
      "parameters": { "quality": "good" } },
    { "phenomenonTime": "2025-07-14T03:15:00Z", "result": 2.481,
      "parameters": { "quality": "suspect" } },
    { "phenomenonTime": "2025-07-14T03:30:00Z", "result": 2.503,
      "parameters": { "quality": "good" } }
  ]
}

The unit lives one level up, on the data stream, as a name, a symbol and a link to its definition, for example "unitOfMeasurement": {"name": "metre", "symbol": "m", ...} [7]. Three things stand out:

• Times here are in UTC. 02:30:00Z is 08:00 IST. The standard's time values are ISO 8601 strings, so any offset is allowed, but the client must handle both.
• The gap is silent. The 08:30 reading (03:00 UTC) is simply not there. A user who does not know the 15-minute interval cannot tell a gap from a station that reports every 30 minutes.
• Quality and datum are the publisher's choice. SensorThings offers a resultQuality field and a free parameters object but no fixed flag list and no datum field, so both must be documented.

What each format carries

What happens when local time travels without an offset?

A frequent error in shared water data is a local time stamp with no offset. If a file written in IST is read by software that assumes UTC and then shown in IST again, every value moves five and a half hours later.

Recorded peak:            10:00   (written without an offset)
Assumed to be UTC:        10:00Z
Converted to IST:         10:00 + 05:30 = 15:30 IST
Error in the peak time:   5 h 30 min

When comparing an upstream and a downstream gauge, an error of that size can make a flood wave appear to travel upstream. The fix costs nothing: write the offset on every time stamp.

How do agencies share water data through APIs?

An API (application programming interface) lets one computer system ask another for data without anyone emailing files. Three open approaches matter for water data, and they differ mainly in who starts the exchange.

OGC SensorThings API

SensorThings API Part 1: Sensing (version 1.1, 2021) is an OGC standard for sensor observations on the web [7]. A Thing (a station) has Datastreams, and each Datastream groups the Observations of one property made by one Sensor. It uses web (REST) requests, JSON and the OData conventions for filtering, sorting and paging. It separates phenomenonTime, when the river had that level, from resultTime, when the result was produced, and an optional extension delivers new observations over MQTT, a lightweight publish-subscribe protocol [7].

OGC API – Environmental Data Retrieval (EDR)

OGC API – EDR (version 1.1, approved 2022) is a family of simple web queries for taking just the part of a large dataset you need: data at a position, within an area or radius, along a trajectory or corridor, or at a named location [8]. A request for our station could be:

/collections/river-levels/locations/EX-001
    ?datetime=2025-07-14T02:30Z/2025-07-14T03:30Z
    &parameter-name=water_level&f=CoverageJSON

A location can be a station identifier, the server can offer formats such as GeoJSON, CoverageJSON, netCDF or CSV, and a collection can have several "instances" where data are reprocessed [8], which suits provisional and validated versions of a record. EDR is a way of asking, not a format: the response still has to carry units, flags and offsets.

WMO Information System 2.0 (WIS2)

WIS 2.0 is WMO's framework for exchanging weather, climate and water data between countries. It became operational on 1 January 2025, starting a transition (2025–2030) to replace the Global Telecommunication System [9]. Its rules are in WMO-No. 1060 and its guidance in WMO-No. 1061, Volume II of each [10][11].

WIS2 uses a "publish-subscribe" pattern: users subscribe to a topic and receive new data in real time [11]. Each publisher runs a WIS2 Node whose message broker publishes a notification, using MQTT, when new data are available; Global Brokers pass it on to subscribers. The data are downloaded over HTTP, preferably HTTPS, and Global Caches keep copies of core data for about 24 hours. Datasets are found through a Global Discovery Catalogue built on the OGC API – Records standard. WMO chose open standards to avoid bespoke systems that force national services to buy costly equipment [11].

For a state or basin agency, WIS2 is a model for real-time sharing: announce new data rather than wait to be polled, and serve the files from an ordinary web server.

What India-WRIS offers

India-WRIS, the national water resources information system, was started in 2009 by the Central Water Commission (CWC), the Ministry of Jal Shakti and the National Remote Sensing Centre (ISRO) as a "single window" for India's water resources data [12]. According to CWC, all unclassified data of CWC's hydrological observation stations and the Central Ground Water Board's groundwater data are available on the portal for free download, and the portal has modules for live telemetry data and for daily reservoir levels and storage [12]. Before building an interface to it, check the portal's download pages for the stations, formats and terms of use.

What should a tender ask for?

Data formats are cheap to specify and expensive to fix later. In a hydromet tender (see writing a technical specification for a hydromet tender), ask for:

1. Time stamps with an offset. Every stored and exported time in ISO 8601 / RFC 3339 form, with Z or +05:30, never bare local time [3].
2. Units and datum as data. A unit code with every series, and the datum of every water-level series, including the gauge zero's height above the national datum where known.
3. A quality flag on every value, from a documented list that maps onto the WaterML 2.0 categories (good, suspect, estimate, poor, unchecked, missing) [5].
4. Explicit gaps. Missing values marked with a reason, never written as zero, blank or an unexplained code such as −9999.
5. Raw data kept, corrections versioned. WMO-No. 168 says stage data should be preserved "in their original unmodified form" and that the originally recorded file should be archived and a copy edited [1]. Ask for raw, checked and validated versions, each labelled; see data quality control for hydromet time series.
6. Bulk export in an open format. CSV following RFC 4180 with the columns above and a documented column description, and WaterML 2.0 Part 1 where the receiving agency uses it.
7. A documented API for queries by station, parameter and time range, preferably to an open standard such as OGC SensorThings API or OGC API – EDR, and continued access to all data after the contract ends.
8. A sample before acceptance. Ask bidders to deliver a sample export and API response for a test period, and check them against these rules.

Common pitfalls

• Local time without an offset: the 5.5-hour error shown above.
• Units hidden in a header: "Level (cm)" is lost the moment the numbers are copied into another sheet.
• Ambiguous dates: 07/08/2025 can be 7 August or 8 July depending on the software. ISO 8601 order (year, month, day) removes the doubt.
• Corrections written over the original: nobody can then check or redo the correction.
• Datum changes without a note: after a resurvey, an unchanged river shows a step.
• Ignored paging: in SensorThings, a partial response carries an @iot.nextLink to the next page [7]. A client that ignores it silently gets only the first page.
• Arrival time used as measurement time: if a device sends no observation time, a SensorThings service stamps it with the server's clock [7], so a reading delivered an hour late is filed an hour late.

Key points

• A hydrological data format decides whether a record can be reused: time zone, unit, datum, quality flag and gaps must travel with every value.
• CSV is universal but defines none of these; write them as columns and describe the file.
• WaterML 2.0 makes time zones, UCUM units, null reasons and quality categories part of the format, at the cost of size.
• JSON APIs are compact, but only a documented data model, such as SensorThings API, makes them reliable.
• For sharing between agencies, request-response APIs (SensorThings, OGC API – EDR) suit queries; publish-subscribe (as in WMO WIS 2.0) suits real-time exchange.
• In a tender, specify offsets, units, datums, flags, explicit gaps, retained raw data, open export and an API.

Where ClimMaTech fits

Our monitoring devices log their readings on board and send them to the ClimMaTech cloud, where Visiflow (Device Cloud) shows live readings, history and alerts. When an agency needs the data in its own system, our devices support MQTT and open APIs. We are glad to work through the format and interface questions in this article for your network.

References

1. World Meteorological Organization, Guide to Hydrological Practices, Volume I: Hydrology – From Measurement to Hydrological Information, WMO-No. 168, 2008 edition, updated in 2020, Chapters 9 and 10. Copy hosted by Agência Nacional de Águas, Brazil.
2. Y. Shafranovich, Common Format and MIME Type for Comma-Separated Values (CSV) Files, RFC 4180, Internet Engineering Task Force, 2005. rfc-editor.org.
3. G. Klyne and C. Newman, Date and Time on the Internet: Timestamps, RFC 3339 (a profile of ISO 8601), Internet Engineering Task Force, 2002. rfc-editor.org.
4. World Wide Web Consortium, Metadata Vocabulary for Tabular Data, W3C Recommendation, 2015. w3.org.
5. Open Geospatial Consortium, OGC WaterML 2.0: Part 1 – Timeseries, version 2.0.1, OGC 10-126r4, P. Taylor (ed.), 2014. Sections 9.12, 9.15, 9.19, 10.3 and 10.9. docs.ogc.org PDF.
6. T. Bray (ed.), The JavaScript Object Notation (JSON) Data Interchange Format, RFC 8259, Internet Engineering Task Force, 2017. rfc-editor.org.
7. Open Geospatial Consortium, OGC SensorThings API Part 1: Sensing, version 1.1, OGC 18-088, 2021. docs.ogc.org.
8. Open Geospatial Consortium, OGC API – Environmental Data Retrieval Standard, version 1.1, OGC 19-086r6, M. Burgoyne, D. Blodgett, C. Heazel and C. Little (eds.), approved 2022, published 2023. docs.ogc.org PDF.
9. World Meteorological Organization, Operational Readiness of WIS 2.0 Gateways, circular letter 07546/2025/I/WIS, 20 June 2025. wmo.int PDF.
10. World Meteorological Organization, Manual on the WMO Information System, Volume II: WMO Information System 2.0, WMO-No. 1060, 2023 edition, updated in 2024. WMO e-Library.
11. World Meteorological Organization, Guide to the WMO Information System, Volume II: WMO Information System 2.0, WMO-No. 1061, release 1.1.0 (approved November 2024 through fast-track amendment 2024-2), sections 1.1, 1.3, 2.4 and 2.5. Source text, release 1.1.0.
12. Central Water Commission, Water Resources Information System (WRIS), Ministry of Jal Shakti, Government of India. cwc.gov.in.