What Should a Sensor Data Download Include?
From the earlier reference collection. Read the current software blog.
A useful sensor download preserves the reading and enough context to interpret, trace, and assess its quality later.
Include the observation and its identity
At minimum, include the measured value and unit, a timestamp, and a stable station identifier. A number without a unit cannot be interpreted reliably; a timestamp without a stated convention may be assigned to the wrong local hour. Use a consistent format and document whether times are expressed in UTC or another zone.
The station identifier should remain stable across exports where possible. Include a human-readable station name as a convenience, but do not make that name the only key: names can change or be shared by multiple locations.
Carry status and provenance
Include the quality flag, even when it is empty, and provide a data dictionary that explains the flag values. If the download combines records from multiple sources, identify the source for each record or clearly describe the provenance of each file. A reader needs to know which organization or feed supplied the observation and when the data was obtained.
For example, a row might contain station ID, observation time, value, unit, quality status, and source record identifier. The exact format can vary, but the fields should let a reader trace a plotted point back to the data and its context.
Preserve missingness and transformations
Do not encode a missing measurement as zero unless zero is explicitly the documented meaning. Use a documented null or status representation, and explain it. If a download contains estimated or aggregated values, label them and include the transformation method or reference to its documentation.
If timestamps, units, or coordinates have been transformed, disclose the rule and preserve original values when appropriate. The download should not make derived values indistinguishable from direct sensor observations.
Make the file self-explanatory
Include a header row or structured field names, a clear encoding, and a companion description of field types, units, time zone, and status meanings. State the extraction time and, when available, the source dataset version. These details help users reproduce a result after the live feed changes.
A good download is a portable record of both values and their interpretation. Include enough metadata that a reader can use it without reconstructing assumptions from a chart.