Oceans 2.0 API
Page tree
Skip to end of metadata
Go to start of metadata

Near real-time (as fast as they get into our database) data access methods allow the extraction of sensor data as time-series, either as processed scalar data with Quality Assurance and Control flags (QAQC) or directly as raw data obtained from the device in its specific output format. In contrast to the Data product download methods, this data can be downloaded directly without waiting for any kind of generation process.

Common use cases include:

  • Plotting time-series from properties in a specific timeframe or in "near real-time"
  • Quickly obtaining the latest reading from a particular sensor
  • Obtaining raw unprocessed data from our instruments (data might require processing to be readable)


The methods getDirectByLocation() and getDirectRawByLocation() obtain data readings from a location no matter what device it came from (hence the need to specify a "device category code" instead of a single "device code"). You might want to obtain data by location instead of by device, as individual devices are often replaced/repositioned.

Each request to our API can return a maximum of 100,000 samples; larger data requests must be downloaded as a sequence of "pages". Use the "allPages" parameter to automatically download all pages required for your requested timeframe.

Summary

Method

Description

getDirectByLocation (filters, allPages)

Obtain scalar data readings from a device category in a location
getDirectByDevice (filters, allPages)Obtain scalar data readings from a device

getDirectRawByLocation (filters, allPages)

Obtain raw data readings from a device category in a location

getDirectRawByDevice (filters, allPages)

Obtain raw data readings from a device


getDirectByLocation

Downloads time-series of property readings from a device category in a location.

Returned data contains a value, time and QAQC flag for every measurement in the time-series.

Parameter

Type

Description

Example

filters^filters

A group of filters used to configure the scalar data request, to be provided to the getByLocation method from the API scalardata service.

The following filters are required and will set the data origin:

The following filters are optional:

Visit the getByLocation method documentation for information on filter usage.


{
'locationCode': 'TWDP',
'deviceCategoryCode': 'TSG',
'dateFrom':'2016-09-01T00:00:00.000Z',
'dateTo': '2016-09-01T08:00:00.000Z'
}
{
'locationCode', 'TWDP',
'deviceCategoryCode', 'TSG',
'dateFrom','2016-09-01T00:00:00.000Z',
'dateTo', '2016-09-01T08:00:00.000Z'
}
struct(
"locationCode" = 'TWDP',
"deviceCategoryCode" = 'TSG',
"dateFrom"='2016-09-01T00:00:00.000Z',
"dateTo" = '2016-09-01T08:00:00.000Z'
)

allPages

boolean

Whether this method should automatically download all pages when the data requested exceeds the row limit.

  • ^False: Only download the first page of data
  • ^True: If required, keep downloading all pages of data until all the requested data is obtained.

Default value: False

^False 

(parameters with an underline are required)


Example: Get all property readings in a time range
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode': 'TWDP',         # Tswwassen DP Ferry
    'deviceCategoryCode':'TSG',     # Thermosalinograph
    'dateFrom':'2016-09-01T00:00:00.000Z',
    'dateTo':'2016-09-01T00:01:00.000Z'
}
result = onc.getDirectByLocation(filters, allPages=True)

onc.print(result)

onc = Onc(YOUR_TOKEN_HERE);

filters = {
    'locationCode',       'TWDP',    % Tswwassen DP Ferry
    'deviceCategoryCode', 'TSG',     % Thermosalinograph
    'dateFrom',           '2016-09-01T00:00:00.000Z',
    'dateTo',             '2016-09-01T00:00:04.000Z'
};
result = onc.getDirectByLocation(filters, "allPages", true);

onc.print(result);

library(onc)
onc <- Onc(YOUR_TOKEN_HERE)

filters = list(
    'locationCode'       = 'TWDP',    # Tswwassen DP Ferry
    'deviceCategoryCode' = 'TSG',     # Thermosalinograph
    'dateFrom'           = '2016-09-01T00:00:00.000Z',
    'dateTo'             = '2016-09-01T00:00:04.000Z'
)
result = onc$getDirectByLocation(filters, 'allPages'=TRUE)

onc$print(result)

Returns

A ^dictionary with separate ^lists | vectors | lists of sensor readings for each property, as returned by the scalardata getByLocation method.

By default, each property in the response includes a "data" ^dictionary with matching ^lists | vectors | lists for "values", "sampleTimes" and "qaqcFlags".

{
    "queryUrl": "https://data.oceannetworks.ca/api/scalardata?locationCode=TWDP&(...)",    
    "next": null,
    "sensorData": [
        {
            "sensorCategoryCode": "conductivity",
            "sensorCode": "Conductivity",
            "sensorName": "Conductivity",
            "unitOfMeasure": "S/m",
            "data": {
                "values": [3.442, 3.448, 3.448, 3.447],
                "sampleTimes": [
                    "2016-09-01T00:00:07.037Z",
                    "2016-09-01T00:00:17.041Z",
                    "2016-09-01T00:00:27.046Z",
                    "2016-09-01T00:00:37.040Z"
                ],
                "qaqcFlags": [1,1,1,1]
            }
        }
    ]
}

Note that "sampleTimes" is a cell array of strings.

struct(
    queryUrl: 'https://data.oceannetworks.ca/api/scalardata?locationCode=TWDP(...)'
    next: []
    sensorData: [
        struct(
            sensorCategoryCode: 'conductivity'
            sensorCode: 'Conductivity'
            sensorName: 'Conductivity'
            unitOfMeasure: 'S/m'
            data: struct(
                sampleTimes: {
                    '2016-09-01T00:00:07.037Z',
                    '2016-09-01T00:00:17.041Z',
                    '2016-09-01T00:00:27.046Z',
                    '2016-09-01T00:00:37.040Z'
                }
                values: [
                    3.44294,
                    3.44834,
                    3.44827,
                    3.44771,
                ]
                qaqcFlags: [1,1,1,1]
            )
        ),
        (...)
    ]
)
[
  queryUrl: "https://data.oceannetworks.ca/api/scalardata?(...)",
  next: NULL,
  sensorData: [
    [
      sensorCategoryCode: "conductivity",
      sensorCode: "Conductivity",
      sensorName: "Conductivity",
      unitOfMeasure: "S/m",
      data: [
        qaqcFlags: [1, 1, 1, 1, 1, 1],
        sampleTimes: [
          "2016-09-01T00:00:07.037Z",
          "2016-09-01T00:00:17.041Z",
          "2016-09-01T00:00:27.046Z",
          "2016-09-01T00:00:37.040Z"
        ],
        values: [
          3.44294,
          3.44834,
          3.44827,
          3.44771
        ]
      ]
    ],
    (...)
  ]
]

If the request filters include the "outputFormat" parameter set to "object", each measurement will be represented as a ^list | vector | list of self-contained ^dictionaries | structs | named lists as in the following example (Warning: This might noticeably increase the download size in long time-series):

{
    "queryUrl": "https://data.oceannetworks.ca/api/scalardata?locationCode=TWDP&(...)",    
    "next": null,
    "sensorData": [
        {
            "sensorCategoryCode": "conductivity",
            "sensorCode": "Conductivity",
            "sensorName": "Conductivity",
            "unitOfMeasure": "S/m",
            "data": [
                {
                    "qaqcFlag": 1,
                    "sampleTime": "2016-09-01T00:00:07.037Z",
                    "value": 28.9096
                },
                (...)
            ]
        },
        (...)
    ]
}
struct(
    next: []
    queryUrl: 'https://data.oceannetworks.ca/api/scalardata?locationCode=TWDP&(...)'
    sensorData: [
        struct(
            sensorCategoryCode: 'conductivity'
            sensorCode: 'Conductivity'
            sensorName: 'Conductivity'
            unitOfMeasure: 'S/m'
            data: [
                struct(
                    qaqcFlag: 1
                    sampleTime: '2016-09-01T00:00:07.037Z'
                    value: 3.44294
                ),
                (...)
            ]
        ),
        (...)
    ]
)
[
  next: NULL,
  queryUrl: "https://data.oceannetworks.ca/api/scalardata?locationCode=TWDP&(...)",
  sensorData: [
    [
      sensorCategoryCode: "conductivity",
      sensorCode: "Conductivity",
      sensorName: "Conductivity",
      unitOfMeasure: "S/m"
      data: [
        [
          qaqcFlag: 1,
          sampleTime: "2016-09-01T00:00:07.037Z",
          value: 3.44294
        ],
        (...)
      ]
    ],
    (...)
  ]
]

If the request filters include the "metadata" parameter set to "full", the response will also include a "metadata" ^dictionary as in the following example:

{
    (...),
    "metadata": {
        "boundingBox": {
            "maxDepth": 3.0,
            "maxLat": 49.005763,
            "maxLon": -123.128994,
            "minDepth": 3.0,
            "minLat": 49.005763,
            "minLon": -123.128994
        },
        "depth": 3.0,
        "deviceCategoryCode": "TSG",
        "lat": 49.005763,
        "locationName": "Tsawwassen - Duke Point",
        "lon": -123.128994
    }
}
struct(
    (...)
    metadata: struct(
        boundingBox: struct(
            maxDepth: 3
            maxLat: 49.0058
            maxLon: -123.129
            minDepth: 3
            minLat: 49.0058
            minLon: -123.129
        )
        depth: 3
        deviceCategoryCode: 'TSG'
        lat: 49.0058
        locationName: 'Tsawwassen - Duke Point'
        lon: -123.129
    )
)
[
  (...),
  metadata: [
    boundingBox: [
      maxDepth: 3,
      maxLat: 49.005763,
      maxLon: -123.128994,
      minDepth: 3,
      minLat: 49.005763,
      minLon: -123.128994
    ],
    depth: 3,
    deviceCategoryCode: "TSG",
    lat: 49.005763,
    locationName: "Tsawwassen - Duke Point",
    lon: -123.128994
  ]
]

If there are additional data pages to download, the "next" property will contain a ^dictionary with the filters (and URL) that obtain the next page of data as in the following example:

{
    "next": {
        "parameters": {
            "locationCode": "TWDP",
            "deviceCategoryCode": "TSG",
            "dateTo": "2016-09-01T00:01:00.000Z",
            "dateFrom": "2016-09-01T00:00:27.046Z",
            "method": "getByLocation",
            "token": "YOUR_TOKEN"
        },
        "url": "https://data.oceannetworks.ca/api/scalardata?(...)"
    },
    (...)
}
struct(
    next: struct(
        parameters: struct(
            locationCode: 'TWDP'
            deviceCategoryCode: 'TSG'
            dateTo: '2016-09-01T00:00:40.000Z'
            dateFrom: '2016-09-01T00:00:27.046Z'
            method: 'getByLocation'
            token: 'YOUR_TOKEN'
        )
        url: 'https://data.oceannetworks.ca/api/scalardata?(...)'
    )
    (...)
)
[
  next: [
    parameters: [
      locationCode: "TWDP",
      deviceCategoryCode: "TSG",
      dateFrom: "2016-09-01T00:00:27.046Z",
      dateTo: "2016-09-01T00:00:40.000Z",
      method: "getByLocation",
      token: "YOUR_TOKEN"
    ],
    url: "https://data.oceannetworks.ca/api/scalardata?(...)"
  ],
  (...)
]


 Detailed description of returned data [+]

The response is a ^dictionary with the following structure:

PropertyTypeDescription
queryUrlstringThe URL that obtained the results
sensorData^listA list of ^dictionaries, one for each property obtained, with the data readings and sensor information (see below)
metaData^dictionary

Includes information from the instruments that contribute to the data readings returned.

Only included when the "metadata" request parameter has been set to "full"

next^dictionary

If the data requested exceeds the row limit, this element contains the parameters required to produce the next page of data and the corresponding URL (see below).

If this is the last / only page of data, "next" will be ^null | an empty list: [ ] | NULL.


"sensorData" Is a ^list of data properties (i.e. oxygen, conductivity, etc.) returned for the request.

Each data property is a ^dictionary with the following structure:

PropertyTypeDescription
sensorCategoryCodefloatThe property code for this property
sensorCodestringThe code of the sensor that produced the property
sensorNamestringThe name of the sensor that produced the property
unitOfMeasurestringThe unit of measure for the property
data

^dictionary

OR

^list

By default this is a ^dictionary with the readings. The information for each sample is distributed into 3 lists of matching indexes: "values", "sampleTimes" and "qaqcFlags".

If the request filters include the "outputFormat" parameter set to "object", this element will instead hold a ^list of self-contained ^dictionaries (one per sample), each with its own "value", "sampleTime" and "qaqcFlag" as explained in the scalardata getByLocation method documentation.

When "data" is a ^dictionary:

data.values

^listMeasurement values returned (float)

data.sampleTimes

^listSample times for each corresponding element in "values"

data.qaqcFlags

^listQAQC flag for each corresponding element in "values"


When the "next" dictionary is not empty (there are more data pages available), it will have the following structure:

PropertyTypeDescription
urlstringThe URL that obtains the next data page
parameters^dictionary

Filters that can be used to request the next data page.

Will contain all the parameters provided in the original request, with the following changes:

  • "dateFrom" will be modified to match the start of the next page of data
  • If "dateTo" was provided as a relative date, it will be translated to an absolute date
  • Also includes the user "token" and the "method" for the request

getDirectByDevice

Downloads time-series of property readings from a specific device.

The returned data contains a value, time and QAQC flag for every measurement in the time-series.

Parameter

Type

Description

Example

filters^filters

A group of filters used to configure the scalar data request, to be provided to the getByDevice method from the API scalardata service.

The deviceCode filter is required and will set the data origin.

The following filters are optional:

Visit the getByDevice method documentation for information on filter usage.


{
'deviceCode': 'AMLMETRECX50348',
'dateFrom': '2019-06-01T00:00:00.000Z',
'dateTo': '2019-06-01T00:00:10.000Z'
}
{
'deviceCode', 'AMLMETRECX50348',
'dateFrom', '2019-06-01T00:00:00.000Z',
'dateTo', '2019-06-01T00:00:10.000Z'
}
list(
"deviceCode" = "AMLMETRECX50348",
"dateFrom" = "2019-06-01T00:00:00.000Z",
"dateTo": "2019-06-01T00:00:10.000Z"
)



allPages

boolean

Whether this method should automatically download all pages when the data requested exceeds the row limit and requires to be downloaded in multiple pages.

  • ^False: Only download the first page of data
  • ^True: If required, keep downloading all pages of data until all the requested data is obtained.

Default value: ^False

^False 

(parameters with an underline are required)


Example: Get all readings from a specific device in a time range
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'deviceCode': 'AMLMETRECX50348',
    'dateFrom':'2019-06-01T00:00:00.000Z',
    'dateTo':'2019-06-01T00:00:10.000Z'
}
result = onc.getDirectByDevice(filters)

onc.print(result)

onc = Onc(YOUR_TOKEN_HERE);

filters = {
    'deviceCode', 'AMLMETRECX50348',
    'dateFrom',   '2019-06-01T00:00:00.000Z',
    'dateTo',     '2019-06-01T00:00:04.000Z'
};
result = onc.getDirectByDevice(filters);

onc.print(result);

library(onc)
onc <- Onc(YOUR_TOKEN_HERE)

filters = list(
    'deviceCode' = 'AMLMETRECX50348',
    'dateFrom'   = '2019-06-01T00:00:00.000Z',
    'dateTo'     = '2019-06-01T00:00:10.000Z'
)
result = onc$getDirectByDevice(filters)

onc$print(result)

Returns

A ^dictionary with sensor readings for each data property in the response, as returned by the scalardata getByDevice method.

Each property in sensorData includes a "data" ^dictionary, which contains matching ^lists for "values", "sampleTimes" and "qaqcFlags".

{
    "queryUrl": "https://data.oceannetworks.ca/api/scalardata?(...)",    
    "next": null,
    "sensorData": [
        {
            "sensorCategoryCode": "conductivity",
            "sensorCode": "Conductivity",
            "sensorName": "Conductivity",
            "unitOfMeasure": "S/m",
            "data": {
                "values": [3.442, 3.448, 3.448, 3.447],
                "sampleTimes": [
                    "2016-09-01T00:00:07.037Z",
                    "2016-09-01T00:00:17.041Z",
                    "2016-09-01T00:00:27.046Z",
                    "2016-09-01T00:00:37.040Z"
                ],
                "qaqcFlags": [1,1,1,1]
            }
        },
        (...)
    ]
}
struct(
    queryURL: 'https://data.oceannetworks.ca/api/scalardata?(...)'
    next: []
    sensorData: [
        struct(
            sensorCategoryCode: 'conductivity'
            sensorCode: 'Conductivity'
            sensorName: 'Conductivity'
            unitOfMeasure: 'S/m'
            data: struct(
                values: [3.442, 3.448, 3.448, 3.447]
                sampleTimes: {
                    '2019-06-01T00:00:00.723Z',
                    '2019-06-01T00:00:01.723Z',
                    '2019-06-01T00:00:02.723Z',
                    '2019-06-01T00:00:03.723Z'
                }
                qaqcFlags: [0, 0, 0, 0]
            )
        ),
        (...)
    ]
)
[
  queryURL: "https://data.oceannetworks.ca/api/scalardata?(...)",
  next: NULL,
  sensorData: [
    [
      sensorCategoryCode: "conductivity",
      sensorCode: "Conductivity",
      sensorName: "Conductivity",
      unitOfMeasure: "S/m"
      data: [
        values: [3.442, 3.448, 3.448, 3.447],
        sampleTimes: [
          "2019-06-01T00:00:00.723Z",
          "2019-06-01T00:00:01.723Z",
          "2019-06-01T00:00:02.723Z",
          "2019-06-01T00:00:03.723Z",
        ],
        qaqcFlags: [0, 0, 0, 0]
      ]
    ],
    (...)
  ]
]

This response has the same structure and behavior as the response of the getDirectByLocation method. This includes:

  • If the request filters include the "metadata" parameter set to "full", the response will also include a "metadata" ^dictionary as previously explained.
  • If the request filters include the "outputFormat" parameter set to "object", individual measurements in "sensorData" will be represented as self-contained ^dictionaries as previously explained.
  • If there are additional data pages to download, the "next" property will contain information to request the next page of data as previously explained.
 Detailed description of returned data [+]

The response is a ^dictionary with the following structure:

PropertyTypeDescription
queryUrlstringThe URL that obtained the results.
sensorData^listA ^list of ^dictionaries, one for each sensor property obtained, with the readings and sensor information.
metaData^dictionary

A dictionary with general information from the instruments that contribute to the data readings returned.

Only included when the "metadata" request parameter has been set to "full".

next^dictionary

If the data requested exceeds the row limit, this element contains the parameters required to produce the next page of data and the corresponding URL.

If this is the last / only page of data, "next" will be ^null | an empty list: [ ] | NULL.

All the properties in the response have the same structure and behavior described for the getDirectByLocation method.

getDirectRawByLocation

Downloads time-series of raw device output from a device category in a location.

The response will contain raw device output for all properties available in the devices providing the data.

Depending on the source devices' output format, raw data might not be readable (requires to be parsed).

Parameter

Type

Description

Example

filters^dictionary

A group of filters used to configure the raw data request, provided to the rawdata service's getByLocation API method.

The following filters are required and will set the data origin:

The following filters are optional:

Visit the getByLocation method documentation for information on filter usage.


{
'locationCode': 'TWDP',
'deviceCategoryCode': 'TSG',
'dateFrom': '2016-09-01T00:00:00.000Z',
'dateTo': '2016-09-01T08:00:00.000Z'
}
{
'locationCode', 'TWDP',
'deviceCategoryCode', 'TSG',
'dateFrom', '2016-09-01T00:00:00.000Z',
'dateTo', '2016-09-01T08:00:00.000Z'
}
list(
"locationCode" = "TWDP",
"deviceCategoryCode" = "TSG",
"'dateFrom" = "2016-09-01T00:00:00.000Z",
"'dateTo" = "2016-09-01T08:00:00.000Z"
)

allPages

boolean

Whether this method should automatically download all pages when the data requested exceeds the row limit and requires to be downloaded in multiple pages.

  • ^False: Only download the first page of data
  • ^True: If required, keep downloading all pages of data until all the requested data is obtained.

Default value: ^False

^False 

(parameters with an underline are required)


Example: Get raw readings from a location in a time range
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode': 'TWDP',         # Tswwassen DP Ferry
    'deviceCategoryCode':'TSG',     # Thermosalinograph
    'dateFrom':'2016-09-01T00:00:00.000Z',
    'dateTo':'2016-09-01T00:01:00.000Z'
}
result = onc.getDirectRawByLocation(filters, allPages=True)

onc.print(result)

onc = Onc(YOUR_TOKEN_HERE);

filters = {
    'locationCode',       'TWDP',    % Tswwassen DP Ferry
    'deviceCategoryCode', 'TSG',     % Thermosalinograph
    'dateFrom',           '2016-09-01T00:00:00.000Z',
    'dateTo',             '2016-09-01T00:00:30.000Z'
};
result = onc.getDirectRawByLocation(filters, "allPages", true);

onc.print(result);

library(onc)
onc <- Onc(YOUR_TOKEN_HERE)

filters = list(
    'locationCode'       = 'TWDP',    # Tswwassen DP Ferry
    'deviceCategoryCode' = 'TSG',     # Thermosalinograph
    'dateFrom'           = '2016-09-01T00:00:00.000Z',
    'dateTo'             = '2016-09-01T00:00:40.000Z'
)
result = onc$getDirectRawByLocation(filters, 'allPages'=TRUE)

onc$print(result)

Returns

A ^dictionary with separate ^lists of raw device output.

By default, each data sample in the result is represented in matching lists for "readings", "times" and "lineTypes",  as returned by the rawdata getByLocation method, as in the following example:

{
    "queryUrl": "https://data.oceannetworks.ca/api/rawdata?(...)",
    "next": null,
    "metadata": {
        "locationName": "Tsawwassen - Duke Point"
    },
    "data": {
        "readings": [
            "20160901-00:00:07.037, 12.9162,  3.44294,  28.9096",
            "20160901-00:00:17.041, 12.9798,  3.44834,  28.9114",
            "20160901-00:00:27.046, 13.0016,  3.44827,  28.8941"
        ],
        "times": [
            "2016-09-01T00:00:07.037Z",
            "2016-09-01T00:00:17.041Z",
            "2016-09-01T00:00:27.046Z",
        ],
        "lineTypes": [" "," "," "]
    }
}
struct(
    queryUrl: 'https://data.oceannetworks.ca/api/rawdata?(...)'
    next: []
    metadata: struct(
        locationName: 'Tsawwassen - Duke Point'
    )
    data: struct(
        readings: {
            '20160901-00:00:07.037, 12.9162,  3.44294,  28.9096',
            '20160901-00:00:17.041, 12.9798,  3.44834,  28.9114',
            '20160901-00:00:27.046, 13.0016,  3.44827,  28.8941'
        }
        times: {
            '2016-09-01T00:00:07.037Z',
            '2016-09-01T00:00:17.041Z',
            '2016-09-01T00:00:27.046Z'
        }
        lineTypes: {' ', ' ', ' '}
    )
)
[
  queryUrl: "https://data.oceannetworks.ca/api/rawdata?(...)",
  next: NULL,
  metadata: [
    locationName: "Tsawwassen - Duke Point"
  ],
  data: [
    readings: [
      "20160901-00:00:07.037, 12.9162,  3.44294,  28.9096",
      "20160901-00:00:17.041, 12.9798,  3.44834,  28.9114",
      "20160901-00:00:27.046, 13.0016,  3.44827,  28.8941"
    ],
    times: [
      "2016-09-01T00:00:07.037Z",
      "2016-09-01T00:00:17.041Z",
      "2016-09-01T00:00:27.046Z"
    ],
    lineTypes: [" ", " ", " "]
  ]
]

If the request filters include the "outputFormat" parameter set to "object", the data returned will be represented as a ^list of self-contained elements as in the following example (Warning: This might noticeably increase the download size in long time-series):

{
    "queryUrl": "https://data.oceannetworks.ca/api/rawdata?(...)",
    "next": null,
    "metadata": {
        "locationName": "Tsawwassen - Duke Point"
    },
    "data": [
        {
            "lineType": " ",
            "rawData": "20160901-00:00:07.037, 12.9162,  3.44294,  28.9096",
            "sampleTime": "2016-09-01T00:00:07.037Z"
        },
        (...)
    ]   
}
struct(
    queryUrl: 'https://data.oceannetworks.ca/api/rawdata?(...)'
    next: []
    metadata: struct(
        locationName: 'Tsawwassen - Duke Point'
    )
    data: [
        struct(
            lineType: ' '
            rawData: '20160901-00:00:07.037, 12.9162,  3.44294,  28.9096'
            sampleTime: '2016-09-01T00:00:07.037Z'
        ),
        (...)
    ]
)
[
  queryUrl: "https://data.oceannetworks.ca/api/rawdata?(...)",
  next: NULL,
  metadata: [
    locationName: "Tsawwassen - Duke Point"
  ],
  data: [
    [
      lineType: " ",
      rawData: "20160901-00:00:07.037, 12.9162,  3.44294,  28.9096",
      sampleTime: "2016-09-01T00:00:07.037Z"
    ],
    (...)
  ]
]

If there are additional data pages to download, the "next" property will contain a ^dictionary with the filters (and URL) that obtain the next page of data as in the following example:

{
    "next": {
        "parameters": {
            "locationCode": "TWDP",
            "deviceCategoryCode": "TSG",
            "dateTo": "2016-09-01T00:01:00.000Z",
            "dateFrom": "2016-09-01T00:00:17.042Z",
            "method": "getByLocation",
            "token": "YOUR_TOKEN"
        },
        "url": "https://data.oceannetworks.ca/api/rawdata?(...)"
    },
    (...)
}
struct(
    next: struct(
        parameters: struct(
            locationCode: 'TWDP'
            deviceCategoryCode: 'TSG'
            dateTo: '2016-09-01T00:00:30.000Z'
            dateFrom: '2016-09-01T00:00:17.042Z'
            method: 'getByLocation'
            token: 'YOUR_TOKEN'
        )
        url: 'https://data.oceannetworks.ca/api/rawdata?(...)'
    )
    (...)
)
[
  next: [
    parameters: [
      locationCode: "TWDP",
      deviceCategoryCode: "TSG",
      dateTo: "2016-09-01T00:00:40.000Z",
      dateFrom: "2016-09-01T00:00:17.042Z",
      method: "getByLocation",
      token: "YOUR_TOKEN"
    ],
    url: "https://data.oceannetworks.ca/api/rawdata?(...)"
  ],
  (...)
]

 Detailed description of returned data [+]

The response is a ^dictionary with the following properties:

PropertyTypeDescription
queryUrlstringThe URL that obtained the results
metadata^dictionary

metadata.locationName

stringThe name of the location the data originates from
nextdictionary

If the data requested exceeds the row limit, this dictionary contains the parameters required to produce the next page of data (see below).

If this is the last page of data, "next" will be ^null | an empty list: [ ] | NULL.

data

^dictionary

OR

^list

By default, a ^dictionary with the raw readings obtained. The data for each reading is distributed into 3 lists of matching indexes: "readings", "times" and "lineTypes".

If the request filters include the "outputFormat" parameter set to "object", this element will instead contain a ^list of self-contained ^dictionaries (one per sample), each with its own "reading", "time" and "lineType" as explained in the rawdata getByLocation documentation.

When "data" is a ^dictionary:

data.readings

^listRaw readings. The readings might be strings or integers depending on the raw data type.

data.times

^listSampling times for each corresponding element in the "readings" list

data.lineTypes

^list

Line type of each corresponding element in the "readings" list.

The line type " " matches data readings. Additionally, ">" and "<" indicate command lines.


When the "next" dictionary is not empty (there are more data pages available), it will have the following structure:

PropertyTypeDescription
urlstringThe URL that obtains the next data page
parameters^dictionary

Filters that can be used to request the next data page.

Will contain all the parameters provided in the original request, with the following changes:

  • "dateFrom" will be modified to match the start of the next page of data
  • If "dateTo" was provided as a relative date, it will be translated to an absolute date
  • Also includes the user "token" and the "method" for the request

getDirectRawByDevice

Downloads time-series of raw sensor readings from a specific device.

The response will contain readings for all properties available in the device.

Depending on the source devices' output format, raw data might not be readable (requires to be parsed; for more information, consult the device documentation in the Data Search page).

Parameter

Type

Description

Example

filters^filters

A group of filters used to configure the data product request, to be provided to the rawdata getByDevice API method.

The filter deviceCode is required and will set the data origin.

The following filters are optional:

  • dateFrom
  • dateTo
  • rowLimit
  • sizeLimit
  • convertHexToDecimal
  • outputFormat
  • getLatest

Visit the getByDevice method documentation for information on filter usage.


{
'deviceCode': 'AMLMETRECX50348',
'dateFrom': '2019-06-01T00:00:00.000Z',
'dateTo': '2019-06-01T00:00:10.000Z'
}
{
'deviceCode', 'AMLMETRECX50348',
'dateFrom', '2019-06-01T00:00:00.000Z',
'dateTo', '2019-06-01T00:00:10.000Z'
}
list(
"deviceCode" = "AMLMETRECX50348",
"dateFrom" = "2019-06-01T00:00:00.000Z",
"dateTo": "2019-06-01T00:00:10.000Z"
)

allPages

boolean

Whether this method should automatically download all pages when the data requested exceeds the row limit and requires to be downloaded in multiple pages.

  • ^False: Only download the first page of data
  • ^True: If required, keep downloading all pages of data until all the requested data is obtained.

Default value: ^False

^False 

(parameters with an underline are required)


Example: Get raw readings from a device in a time range
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'deviceCode':'AMLMETRECX50348',      # A CTD in Burrard Inlet
    'dateFrom':'2019-06-01T00:00:00.000Z',
    'dateTo':'2019-06-01T00:00:05.000Z'
}
result = onc.getDirectRawByDevice(filters, allPages=False)

onc.print(result)

onc = Onc(YOUR_TOKEN_HERE);

filters = {
    'deviceCode', 'AMLMETRECX50348',
    'dateFrom',   '2019-06-01T00:00:00.000Z',
    'dateTo',     '2019-06-01T00:00:04.000Z'
};
result = onc.getDirectRawByDevice(filters);

onc.print(result);

library(onc)
onc <- Onc(YOUR_TOKEN_HERE)

filters = list(
    'deviceCode' = 'AMLMETRECX50348',
    'dateFrom'   = '2019-06-01T00:00:00.000Z',
    'dateTo'     = '2019-06-01T00:00:04.000Z'
)
result = onc$getDirectRawByDevice(filters)

onc$print(result)

Returns

A ^dictionary with separate ^lists of raw device output, with the same structure described for the getDirectByLocation method.

By default, each data sample in the result is represented in matching lists for "readings", "times" and "lineTypes",  as returned by the rawdata getByDevice method, as in the following example:

{
    "queryUrl": "https://data.oceannetworks.ca/api/rawdata?(...)",
    "next": null,
    "metadata": {
        "locationName": "Tsawwassen - Duke Point"
    },
    "data": {
        "readings": [
            "20160901-00:00:07.037, 12.9162,  3.44294,  28.9096",
            "20160901-00:00:17.041, 12.9798,  3.44834,  28.9114",
            "20160901-00:00:27.046, 13.0016,  3.44827,  28.8941"
        ],
        "times": [
            "2016-09-01T00:00:07.037Z",
            "2016-09-01T00:00:17.041Z",
            "2016-09-01T00:00:27.046Z",
        ],
        "lineTypes": [" "," "," "]
    }
}
struct(
    queryUrl: 'https://data.oceannetworks.ca/api/rawdata?(...)'
    next: []
    metadata: struct(
        locationName: 'Tsawwassen - Duke Point'
    )
    data: struct(
        readings: {
            '20160901-00:00:07.037, 12.9162,  3.44294,  28.9096',
            '20160901-00:00:17.041, 12.9798,  3.44834,  28.9114',
            '20160901-00:00:27.046, 13.0016,  3.44827,  28.8941'
        }
        times: {
            '2016-09-01T00:00:07.037Z',
            '2016-09-01T00:00:17.041Z',
            '2016-09-01T00:00:27.046Z'
        }
        lineTypes: {' ', ' ', ' '}
    )
)
[
  queryUrl: "https://data.oceannetworks.ca/api/rawdata?(...)",
  next: NULL,
  metadata: [
    locationName: "Tsawwassen - Duke Point"
  ],
  data: [
    readings: [
      "20160901-00:00:07.037, 12.9162,  3.44294,  28.9096",
      "20160901-00:00:17.041, 12.9798,  3.44834,  28.9114",
      "20160901-00:00:27.046, 13.0016,  3.44827,  28.8941"
    ],
    times: [
      "2016-09-01T00:00:07.037Z",
      "2016-09-01T00:00:17.041Z",
      "2016-09-01T00:00:27.046Z"
    ],
    lineTypes: [" ", " ", " "]
  ]
]

This response has the same structure and behavior as the response of the getRawDirectByLocation() method. This includes:

  • If the request filters include the "outputFormat" parameter set to "object", individual measurements in "sensorData" will be represented as self-contained ^dictionaries as previously explained.
  • If there are additional data pages to download, the "next" property will contain information to request the next page of data as previously explained.

 Detailed description of returned data [+]

The response is a ^dictionary with the following properties:

PropertyTypeDescription
queryUrlstringThe URL that obtained the results
metadata^dictionary

metadata.locationName

stringThe name of the location the data originates from
nextdictionary

If the data requested exceeds the row limit, this dictionary contains the parameters required to produce the next page of data (see below).

If this is the last page of data, "next" will be ^null | an empty list: [ ] | NULL.

data

^dictionary

OR

^list

By default, a ^dictionary with the raw readings obtained. The data for each reading is distributed into 3 lists of matching indexes: "readings", "times" and "lineTypes".

If the request filters include the "outputFormat" parameter set to "object", this element will instead contain a ^list of self-contained ^dictionaries (one per sample), each with its own "reading", "time" and "lineType".

When "data" is a ^dictionary:

data.readings

^listRaw readings. The readings might be strings or integers depending on the raw data type.

data.times

^listSampling times for each corresponding element in the "readings" list

data.lineTypes

^list

Line type of each corresponding element in the "readings" list.

The line type " " matches data readings. Additionally, ">" and "<" indicate command lines.

All the properties in the response have the same structure and behavior described for the getRawDirectByLocation() method.






  • No labels