Stats

Look up observation statistics.

Query Index:

Observation Statistics as JSON

Method: GET
URI
/v3/stats/(domain)/(key)/(startdate|latest)/(enddate|period)[?percentiles=(percentiles)]
Accept
application/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/aspect, for example, NZE/water-height/40/15s/nil.
Optional:
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.

End date may not be today or a day in the future.

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).
percentiles
Comma separated list of percentiles to calculate (eg. 5,20.5,95).

Response Properties

Response has the JSON struct of:

{
    "series": {
        "domain": "dart",
        "station": "NZE",
        "name": "water-height",
        "sensorCode": "40",
        "method": "15s",
        "aspect": "nil"
    },
    "latitude": -36.0493,
    "longitude": -177.708,
    "elevationM": 0,
    "datum": "WGS84",
    "relativeHeightM": -5779,
    "valueUnit": "m",
    "errorUnit": "m",
    "first": {
        "val": 5778851,
        "err": 0,
        "qc": "",
        "ts": "2021-03-05T01:08:30Z"
    },
    "last": {
        "val": 5778954,
        "err": 0,
        "qc": "",
        "ts": "2021-03-05T10:26:45Z"
    },
    "maximum": {
        "val": 5779177,
        "err": 0,
        "qc": "",
        "ts": "2021-03-05T01:09:15Z"
    },
    "minimum": {
        "val": 5778161,
        "err": 0,
        "qc": "",
        "ts": "2021-03-05T03:10:00Z"
    },
    "count": 974,
    "mean": 5778591.8285,
    "median": 5778600.5,
    "populationStdDev": 210.0884,
    "percentiles": [
        {
            "percentile": 5,
            "value": 5778229
        },
        {
            "percentile": 20.5,
            "value": 5778388
        },
        {
            "percentile": 95,
            "value": 5778912.25
        }
    ],
    (if present:)
    "additionalMetadataMap": {
        "key": "value",
    },
    "mutableMetadata": [
        {
            "start": "2021-03-05T00:00:00Z",
            "end": "2021-04-05T00:00:00Z",
            "metadataMap": {
                "key": "value1",
            }
        },
        {
            "start": "2021-04-06T00:00:00Z",
            "end": "2021-05-10T00:00:00Z",
            "metadataMap": {
                "key": "value2",
            }
        }
    ]
}
   
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 that are available at different resolutions, the time resolution of the series, for e.g. 'high rate', 'low rate', '10-min'.
aspect
Aspect – The series' aspect, a human readable description that captures a discrete part or feature of the time series. Different Aspects of a time series are obtained with the same method (process) and collected by the same station and sensorCode, but are representing a different output in the spectrum of possible results. It can be used to specify exactly which of several related data series is requested. For example, 'east, north, up' are 3 different aspects of the same gnss displacement time series; '10cm, 20cm, 30cm' are different aspects of the same soil-moisture collection sensor, that measures the same entity at different depths. Aspect can also be 'nil' (not applicable)

attributes
latitude
The series' latitude.
longitude
The series' longitude.
valueUnit
The observation's value unit.
errorUnit
The observation's error unit.
elevationM
Height in metres of the Sensor above the free surface for the given Reference Datum.
datum
Geographical reference system used for the latitude, longitude & elevation/height.
relativeHeightM
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:
start: The start of this period of meta data values coming into effect
end: The end of this period of meta data values coming into effect
relativeHeightOffset: Additional height offset to be added or substracted to relativeHeightM, in metres.
first
The first observation sample of the series during the period.
last
The last observation sample of the series during the period.
count
The number of observation records of the series during the period.
maximum
The observation sample having maximum value of the series during the period.
minumum
The observation sample having minimum value of the series during the period.
mean
The mean value of the requested series data.
median
The median value of the requested series data.
populationStdDev
The standard deviation of the values of the requested series data.
percentiles
The value for each percentile in the request parameter.

Example Query and Response

{
    "series": {
        "domain": "dart",
        "station": "NZE",
        "name": "water-height",
        "sensorCode": "40",
        "method": "15s",
        "aspect": "nil"
    },
    "latitude": -36.0493,
    "longitude": -177.708,
    "elevationM": 0,
    "datum": "WGS84",
    "relativeHeightM": -5779,
    "mutableMetadata": null,
    "additionalMetadataMap": {
        "depth": "5779.000000",
        "waterLevel": "0.000000"
    },
    "valueUnit": "m",
    "errorUnit": "m",
    "first": {
        "val": 5778851,
        "err": 0,
        "qc": "",
        "ts": "2021-03-05T01:08:30Z"
    },
    "last": {
        "val": 5778954,
        "err": 0,
        "qc": "",
        "ts": "2021-03-05T10:26:45Z"
    },
    "maximum": {
        "val": 5779177,
        "err": 0,
        "qc": "",
        "ts": "2021-03-05T01:09:15Z"
    },
    "minimum": {
        "val": 5778161,
        "err": 0,
        "qc": "",
        "ts": "2021-03-05T03:10:00Z"
    },
    "count": 974,
    "mean": 5778591.8285,
    "median": 5778600.5,
    "populationStdDev": 210.0884,
    "percentiles": [
        {
            "percentile": 5,
            "value": 5778229
        },
        {
            "percentile": 95,
            "value": 5778912.25
        }
    ]
}
    
/v3/stats/dart/NZA/water-height/40/15m/nil/latest/6h
(for results, refer to the example above)