Data

Version 1

Look up observation data.

Query Index:

• JSON - Observation Data as JSON
• CSV - Observation Data as CSV

Data

Observation Data as JSON

Query Parameters

Required:

domain

For example, dart for Deep-ocean Assessment and Reporting of Tsunami.

key

The key of the data associated to. It should have the format of /station/name/sensorCode/method, for example, NZE/water-height/40/15s.
sensorCode and method can be - for wildcard matching, for instance, NZE/water-height/-/15s will try to match water-height series with any sensor code and method=15s.

startdate

The start date of the query period in the format of yyyy-mm-dd, UTC time zone.

enddate

The end date of the query period in the format of yyyy-mm-dd, UTC time zone.

Start date and end date may not be today or a day in the future. For the latest data from today please use the latest/(period) style of request.

The start date and the end date are inclusive, for example, 2021-06-04/2021-06-04 returns all data that have a timestamp that occurs on that date i.e, between 2021-06-04 00:00:00 UTC and 2021-06-04 24:00:00 UTC

latest

By specifying latest in (startdate) field in conjuction with (period), the user can simply query for the latest period of data.

period

The latest period to query. Can be 30d (latest 30 days), 7d, 2d, 1d, or 6h (latest 6 hours).

Optional:

aggregationPeriod

Specifying the time window to do aggregation. Can be 1m (1 minute), 5m, 10m, 15m, 30m, 1h (1 hour), 2h, 3h, 4h, 6h, 8h, 12h, or 1d (1 day)

aggregationFunction

Method to aggregate return values. Can be min for minimum, max for maximum, mean for mean, sum for summation, or perc(N) for (N)th percentile (eg. perc95).

Response Properties

Response has the JSON struct of:

[
    {
        "data": [
            {
                "value": 5237100,
                "err": 0,
                "qc": "",
                "ts": "2021-03-05T00:00:00Z"
            },
            (repeated)
        ],
        "series": {
            "domain": "dart",
            "station": "NZE",
            "name": "water-height",
            "sensorCode": "40",
            "method": "15s",
            "aspect": "nil"
        },
        "lat": -36.0493,
        "lon": -177.708,
        "seriesElevationM": 0,
        "seriesDatum": "WGS84",
        "seriesRelativeHeightM": "-5779",
        "valueUnit": "m",
        "errorUnit": "m",
        (if present:)
        "additionalMetadataMap": {
            "key": "value",
        },
        "mutableMetadata": [
            {
                "startTs": "2021-03-05T00:00:00Z",
                "endTs": "2021-04-05T00:00:00Z",
                "metadataMap": {
                    "key": "value1",
                }
            },
            {
                "startTs": "2021-04-06T00:00:00Z",
                "endTs": "2021-05-10T00:00:00Z",
                "metadataMap": {
                    "key": "value2",
                }
            }
        ]
    },
    {
        // repeated JSON objects if multiple series matched
    }
]
    

data object

ts

The date-time of the observation in ISO8601 format, UTC time zone.

value

The observation value.

err

The observation error. 0 is used for an unknown error.

qc

The observation's qc flag.

series object

domain

The series' domain name, an overall description of the type of observations that have been recorded (e.g. dart). It is an handy label to help in searching for data of a certain use and type.

station

The series' station code, a unique string identifier which can be used to describe where the measurement has been taken ( see /station endpoint [in development] ).

name

The series' name, a general name for the observation. It includes the measurement itself and the object being measured. It is also used to differentiate different series observed at the same Station, eg: water-height, temperature.

sensorCode

The station sensor's code. A measurement specific term used to distinguish between multiple sensors at a given station performing the same operation. For example seismic sensors in the same borehole may have different numbers, or successive DART buoys deployed in the same nominal station but at slightly different locations.

method

A human readable description of the measurement collection method, typically for manual observations, e.g. 'thermometer', 'lab-analysis', 'cospec', or, for regularly sampled observations that are available at different resolutions, the time resolution of the series, e.g. 'high rate', 'low rate', '10-min'.

attributes

lat

The series's latitude.

lon

The series's longitude.

valueUnit

The observation's value unit.

errorUnit

The observation's error unit.

seriesElevationM

Height in metres of the Sensor above the free surface for the given Reference Datum.

seriesDatum

Geographical reference system used for the latitude, longitude & elevation/height.

seriesRelativeHeightM

Relative height of the station with respect to the series elevation and datum, in metres. If station is installed underwater, relative height is the depth of water in metres above the station. If station is installed above the ground, relative height is the height of the station above the ground.

additionalMetadataMap

(Optional) Additional metadata for the series. These meta-data types are not present for all series.
For example (in the future), for LRDCP data, a feature description could be added:
feature-description: Small lake on south east side of crater.

mutableMetadata

(Optional) Additional metadata that define properties of the series that can change over time. These meta-data types are not present for all series.
For example (in the future), for FITS data, relativeHeightOffset could be provided:
startTs: The start of this period of meta data values coming into effect
endTs: The end of this period of meta data values coming into effect
relativeHeightOffset: Additional height offset to be added or substracted to seriesRelativeHeightM, in metres.

Example Query and Response

[
    {
        "data": [
            {
                "value": 5237100,
                "err": 0,
                "qc": "",
                "ts": "2021-03-05T00:00:00Z"
            },
            (repeated)
        ],
        "series": {
            "domain": "dart",
            "station": "NZE",
            "name": "water-height",
            "sensorCode": "40",
            "method": "15s",
            "aspect": "nil"
        },
        "lat": -36.0493,
        "lon": -177.708,
        "seriesElevationM": 0,
        "seriesDatum": "WGS84",
        "seriesRelativeHeightM": "-5779",
        "valueUnit": "m",
        "errorUnit": "m",
    }
]
        

Data

Observation Data as CSV

Query Parameters

The same as Data as JSON

Response Properties

column 1 to 5

The domain, station, name, sensor code, method, and aspect of the observation.

column 6

The date-time of the observation in ISO8601 format, UTC time zone.

column 7

The observation value.

column 8

The observation error. 0 is used for an unknown error.

column 9

The observation's qc flag.

Example Query and Response

domain,station,name,sensor_code,method,aspect,time,value,err,qc
dart,NZE,water-height,40,15s,nil,2021-03-05T00:00:00Z,5778684.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T00:15:00Z,5778681.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T00:30:00Z,5778679.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T00:45:00Z,5778679.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T01:00:00Z,5778678.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T01:15:00Z,5778676.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T01:30:00Z,5778675.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T01:45:00Z,5778674.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T02:00:00Z,5778671.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T02:15:00Z,5778670.0000000,0.0000000,
dart,NZE,water-height,40,15s,nil,2021-03-05T02:30:00Z,5778668.0000000,0.0000000,
...