Page tree
Skip to end of metadata
Go to start of metadata

The ONC MatLab client library contains a number of classes and functions that access ONC data, through the Oceans 2.0 API.

Requires

Currently, only R2017a is supported, due to updates to the HTTP library that support payloads with non-200 status codes.

Installation

The ONC client library is an Add-On Toolbox that can be installed in MatLab by performing the following

 Installation instructions
  1. Download the latest version of the ONC Toolbox
  2. Open MATLAB R2017a and click the 'Open' button.



  3. Select the downloaded file and click the Open button.



  4. When presented with the Install onc dialog, click the Install button.



  5. To view the ONC Add-On toolbox click the Add-On button on the Home ribbon and select Manage Add-Ons.






Versions

version
Date
Description
Toolbox
Source
1.06/28/2017Alpha version.

onc-1.0.mltbx


1.017/18/2017Added getDirectScalar(), getDirectRaw() and getDirectFiles() functions.onc-1.01.mltbxonc-1.02-source.zip
1.027/28/2017

Resolve unhandled exception with invalid parameters.

Resolved naming inconsistencies.

onc-1.02.mltbxonc-1.02-source.zip
1.038/01/2017Added getDataProductUrls(), downloadFile() and decodeJsonFromUrl() functionsonc-1.03.mltbxonc-1.03-source.zip
1.048/03/2017Updated production URL from http://dmas.uvic.ca to http://data.oceannetworks.ca.onc-1.04.mltbxonc-1.04-source.zip
1.058/11/2017Rename 'parameters' parameter to 'filters' in all applicable onc class functions.onc-1.05.mltbxonc-1.04-source.zip
1.068/15/2017Added file parameter defult to the download() function.onc-1.06.mltbxonc-1.06-source.zip
1.078/23/2017

Added getDeployments() function.

Updated QA url from http://qaweb2.neptune.uvic.ca to https://qa.oceannetworks.ca.

Updated production url to https.

onc-1.07.mltbxonc-1.07-source.zip
1.089/28/2017

Updated orderDataProduct() function to handle estimatedProcessingTime string format

Updated downloadDataProduct() function to throttle calls using onc.callsPerSecond when downloadResultsOnly=true

onc-1.08.mltbxonc-1.08-source.zip
1.092018-01-18

Updated Matlab versions of discovery functions to handle empty parameter lists

Added getLocationHerarchy() function to access getTree method of locations service

Fixed file counting bug in getDirectFiles() function

Added getDirectRawBy*() functions for changes in rawdata service

Added initial versions of UserTestCase_EMP_UTC_001.m and UserTestCase_EMP_UTC_002.m

Updated functions to return more meaningful info when URL call fails

onc-1.09.mltbxonc-1.09-source.zip
1.102018-02-02

Added UserTestCase_EMP_UTC*.m scripts to demonstrate use of client library functions

Updated getDirectScalar*() functions for changes in scalardata service

Improved error reporting

onc-1.10.mltbxonc-1.10-source.zip
1.112018-04-16

Added UserTestCase_EMP_UTC_004.m to demonstrate use of archivefiles service

Updated getDirectFiles() for changes in archivefiles service

Improved error handling and reporting in user test case example scripts

Updated user test case scripts for change of begin/end to dateFrom/dateTo

onc-1.11.mltbxonc-1.11-source.zip

To download an attachment, please right click on the link and select Save Link AsSave Target As or a similar option provided by your browser. This will open a Save dialog.

New versions are created to resolve known client library issues, add new functionality or handle changes to the underlying Web Services.

The latest version works with the current deployment of the underlying web services. See API Reference.

Classes


class
description
oncA wrapper class for access to Oceans 2.0 API web services


ONC Class

Description

This class provides a wrapper for some for the most common Oceans 2.0 API requests, including the discovery services (locations, devices, deviceCategories, properties) and delivery (dataProductDelivery, scalardata and rawdata).

Constructor

onc()

onc(token, production, showInfo, outPath, timeout)
Parameter
Type
Description
Example
Required


tokenstringAll Web Services require a token. Once logged in at https://data.oceannetworks.ca/login, your token can be retrieved or generated at https://data.oceannetworks.ca/Profile. Click on the "Web Services" tab, then click "Generate Token".token=YOUR_TOKEN_HERE
Optional


productionboolean

Indicates whether the ONC Production server URL is used for service requests.

  • Default is true.
  • false is intended for internal ONC testing only.
  • All non-ONC users must use true or leave blank. Non-ONC user IP addresses are blocked from accessing the Oceans 2.0 QA server.
true or false
showInfoboolean

Indicates whether verbose script messages, such as request URL and processing time information, are displayed.

  • Default is false.
  • True is intended for script debugging.
true or false
outPathstring

The path that downloaded files are saved to.

  • Default is 'c:/Temp'.
  • Full path will be created if it does not already exist.
'c:/ONC/Download'
timeoutint

The web service request timeout in seconds

  • Default is 60
30


Usage

o = onc('YOUR_TOKEN_HERE');

or

production = true;
showInfo = false;
outPath = 'c:/ONC/Data';
timeout = 30;
o = onc('YOUR_TOKEN_HERE',production,showInfo,outPath,timeout);


Discovery methods

getLocations()

getLocations(filters)


Returns a list of locations, as a list of struct objects that meet the criteria defined by the input filters.


Parameter
Type
Description
Example
Optional


filtersstruct or array

A comma separated list of one or more filter criteria, used to return an exclusive set of location elements from the ONC locations endpoint.

struct('locationCode','BACAX')

or

{'locationCode','BACAX'}


Returns

A list of location objects.

        deployments: 50
       locationName: 'Axis '
              depth: 984.3076
               bbox: [1×1 struct]
        description: 'Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biodiversity, sediment dynamics.'
      hasDeviceData: 'true'
                lon: -126.0503
       locationCode: 'BACAX'
    hasPropertyData: 'true'
                lat: 48.3167
      dataSearchURL: 'https://data.oceannetworks.ca/DataSearch?location=BACAX'
Property
Type
Description
Example
locationlistA structure array of locations.

location[].deployments

intThe number of instrument deployments that meet the filter criteria.deployments 10
location[].locationNamestringThe full name of the location.
locationName: "Axis (POD 1)"
location[].depthdoubleThe average depth of the deployments.
depth75
location[].bboxstructA Bounding Box structure.
location[].bbox.maxDepthdoubleThe maximum depth of the deployments.maxDepth100
location[].bbox.maxLatdoubleThe maximum Latitude of bounding box of the deployments.maxLat48.476740
location[].bbox.maxLondoubleThe maximum Longitude of the bounding box of the deployments.maxLon: -123.294904
location[].bbox.minDepthdoubleThe minimum Depth of the deployments.minDepth50
location[].bbox.minLatdoubleThe minimum Latitude of bounding box of the deployments.minLat48.47670
location[].bbox.minLondoubleThe minimum Longitude of the bounding box of the deployments.minLon: -123.294900
location[].descriptionstringThe description of the location.
description: "Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform 
               Description: Canyon axis: benthic processes, biodiversity, sediment dynamics."
location[].hasDeviceDatastringIndicates that data products can be requrested using a device category for the location.
hasDeviceData: "true"
location[].londoubleThe average longitude of the deployments. lon: -123.294902
location[].locationCodestringA code that unquely identifies a location.
locationCode: "BACAX"
location[].hasPropertyDatastringIndicates that data products can be requested using property code for the location.
hasPropertyData: "true"
location[].latdoubleThe average latitude of the deployments.lat48.47672
location[].dataSearchURLstringThe location specific Data Search web page URL.
dataSearchURL: "https://data.oceannetworks.ca/DataSearch?location=BACAX"
Example - Print all locations with 2 MHz ADCP deployed
o = onc('YOUR_TOKEN_HERE');

locations = o.getLocations({'deviceCategoryCode','ADCP2MHZ'});
for i=1:numel(locations)
    disp(locations(i));
end

getLocationHierarchy()

getLocationHierarchy(filters)


Returns a hierarchical subtree of locations whose root is defined by the input filter. In this case the only valid input filter is locationCode. In Oceans 2.0 Instruments and Variables are organized by Location so that users can easily drill down by place name or mobile platform name to find the instruments or properties they are interested in. 


Parameter

Type

Description

Example

Optional


filtersstruct or array

A comma separated list of one or more filter criteria, used to return an exclusive set of location elements from the ONC locations endpoint.

  • A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
  • If excluded, all locations are returned.
  • Valid filters: locationCode
  • See locations Discovery Service for more information on filter usage.
struct('locationCode','BACAX')

or

{'locationCode','BACAX'}


Returns

A hierarchy of location objects.

       locationName: 'Axis '
           children: null
              depth: 984.3076
        description: 'Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biodiversity, sediment dynamics.'
      hasDeviceData: 'true'
       locationCode: 'BACAX'
    hasPropertyData: 'true'


Property

Type

Description

Example
location[]listA list of location structures.
location[].locationNamestringThe full name of the location.
locationName: "Axis (POD 1)"
location[].children[]listA list of location structures that are the children of this location structure.children: null
location[].depthdoubleThe average depth of the deployments.
depth75
location[].descriptionstringThe description of the location.
description: "Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform 
               Description: Canyon axis: benthic processes, biodiversity, sediment dynamics."
location[].hasDeviceDatastringIndicates that data products can be requrested using a device category for the location.
hasDeviceData: "true"
location[].locationCodestringA code that unquely identifies a location.
locationCode: "BACAX"
location[].hasPropertyDatastringIndicates that data products can be requested using property code for the location.
hasPropertyData: "true"
Example - Print locations at Barkley Upper South Slope
o = onc('YOUR_TOKEN_HERE');

locations = o.getLocationHierarchy({'locationCode','BACUS'});
if isfield( locations, 'children' )
    for i = 1 : numel( locations.children )
        locations.children(i)
    end
end


getDevices()

getDevices(filters)


Returns a list of devices, as a list of struct objects that meet the criteria defined by the input filters.


Parameter
Type
Description
Example
Optional


filtersstruct or array

A comma separated list of one or more filter criteria, used to return an exclusive set of device elements from the ONC devices endpoint.

struct('deviceCode','NORTEKADCP9917')

or

{'deviceCode','NORTEKADCP9917'}


Returns

A list of device objects

        cvTerm: [1×1 struct]
				device: [1×1 struct]
			           uri: 'http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/'
			    vocabulary: 'SeaVoX Device Catalogue'

    dataRating: [2×1 struct]
		        dateFrom: '2008-11-01T00:00:00.000Z'
		          dateTo: '2010-05-27T19:27:04.000Z'
		    samplePeriod: 1
		      sampleSize: 1
 
		        dateFrom: '2010-05-27T19:27:04.000Z'
		          dateTo: []
		    samplePeriod: 10
		      sampleSize: 1


    deviceCode: 'BC_POD1_AD2M'
      deviceId: 11302
    deviceLink: 'https://data.oceannetworks.ca/DeviceListing?DeviceId=11302'
    deviceName: 'Nortek Aquadopp HR-Profiler 2965'
Property
Type
Description
Example
device[]listA list of devices.
[]
device[].cvTermstructA structure of controlled vocabulary terms.
cvTerm: [1×1 struct]
device[].cvTerm.device[]structA list of structures of controlled vocabulary term information for the device.
device: [1×1 struct]
device[].cvTerm.device[].uristringThe URI of the controlled vocabulary term.
uri: 'http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/'
device[].cvTerm.device[].vocabularystringThe name of the controlled vocabulary to which the term belongs.
vocabulary: 'SeaVoX Device Catalogue'
device[].dataRating[]listA list of data ratings structures.
dataRating: [2×1 struct]
device[].dataRating[].dateFromdatetime string

The starting datetime for a data rating.

dateFrom: '2008-11-01T00:00:00.000Z'
device[].dataRating[].dateTodatetime string

The ending datetime for a data rating.

  • If None, the data rating was still in affect when the request was made.
  • Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
  • datetime is represented in Coordinated Universal Time (UTC).

dateTo: '2010-05-27T19:27:04.000Z'
device[].dataRating[].samplePerioddoubleThe sample period, in seconds for the data rating.
samplePeriod: 1
device[].dataRating[].sampleSizeintThe size of the data sample for the data rating.
sampleSize: 1
device[].deviceCodestringA code that unquely identifes a device.
deviceCode: 'BC_POD1_AD2M'
device[].deviceIdintA numeric id that uniquely identifies a device.
deviceId: 11302
device[].deviceLinkstringThe URL link to the Devices Listing page for the specific device.deviceLink: 'https://data.oceannetworks.ca/DeviceListing?DeviceId=11302'
device[].deviceNamestringThe name of the device. deviceName: 'Nortek Aquadopp HR-Profiler 2965'
Example - Print all devices deployed at Barkley Canyon - Axis, between June 1, 2016 and May 31, 2017
o = onc('YOUR_TOKEN_HERE');

devices = o.getDevices({'locationCode','BACAX', ... 				%BACAX - Barkley Canyon / Axis
						'dateFrom','2016-06-01T00:00:00.000Z', ...
						'dateTo','2017-05-31T23:59:59.999Z'});  

for i=1:numel(devices)
    disp(devices(i));
end


getDeployments()

getDeployments(filters={})


Returns a list of deployments, as a list of structure objects that meet the criteria defined by the input filters.


Parameter
Type
Description
Example
Optional


filtersstruct or array

A comma separated list of one or more filter criteria, used to return an exclusive set of deployment elements from the ONC deployments endpoint.

{'deviceCode':'NORTEKADCP9917'}


Returns

A list of deployment objects.

            begin: '2016-06-14T08:58:41.000Z'
            depth: 982
       deviceCode: 'WLFLNTU1087'
              end: []
    hasDeviceData: 1
          heading: []
              lat: 48.3166
     locationCode: 'BACAX'
              lon: -126.0508
            pitch: []
             roll: []

            begin: '2016-06-14T06:05:24.000Z'
            depth: 985
       deviceCode: 'BC_POD1_ROTSONAR'
              end: []
    hasDeviceData: 1
          heading: 90
              lat: 48.3166
     locationCode: 'BACAX'
              lon: -126.0508
            pitch: []
             roll: []

            begin: '2016-06-14T06:05:24.000Z'
            depth: 985
       deviceCode: 'NORTEKSIGNATURE550056'
              end: []
    hasDeviceData: 1
          heading: 340
              lat: 48.3166
     locationCode: 'BACAX'
              lon: -126.0508
            pitch: []
             roll: []



Property
Type
Description
Example
deployment[]

[]
deployment[].locationCodestringThe locationCode for the deployment location.
locationCode: "BACAX"
deployment[].deviceCodestringThe deviceCode for a deployed device.
deviceCode: "SBECTD19p6813"
deployment[].begindatetime

The beginning datetime of the deployment.

Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

dateFrom: '2010-07-27T00:00:00.000Z'
deployment[].enddatetime

The ending datetime of the deployment.

  • If the deployment is current, the value is null.

Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

dateTo: '2016-08-01T00:00:00.000Z'

deployment[].hasDeviceData

stringIndicates that data products can be requested using a device category code for the deployment.
hasDeviceData: 1
deployment[].depthdoubleThe depth of the device deployment.depth: 982
deployment[].latdouble

The latitude of the device deployment.

lat: 48.31658
deployment[].londoubleThe longitude of the device deployment.lon: -126.0508
deployment[].headingdoubleThe heading of the device deployment.heading: 244
deployment[].pitchdoubleThe pitch of the device deployment.pitch: null
deployment[].rolldoubleThe pitch of the device deployment.roll: null
Example - Print all devices deployed at Barkley Canyon - Axis, between June 1, 2016 and May 31, 2017
o = onc('YOUR_TOKEN_HERE');

deployments = o.getDeployments({'locationCode':'BACAX','dateFrom':'2016-06-01T00:00:00.000Z','dateTo':'2017-05-31T23:59:59.999Z'})  #BACAX - Barkley Canyon / Axis

for i=1:numel(deployments)
    disp(deployments(i));
end


getDeviceCategories()

getDeviceCategories(filters)


Returns a list of deviceCategories, as a list of struct objects that meet the criteria defined by the input filters.


Parameter
Type
Description
Example
Optional


filtersstruct or array

A comma separated list of one or more filter criteria, used to return an exclusive set of deviceCategory elements from the ONC deviceCategories endpoint.

struct('deviceCategoryCode','HYDROPHONE')

or

{'deviceCategoryCode','HYDROPHONE'}


Returns

A list of device category objects.

                cvTerm: [1×1 struct]
			    deviceCategory: [1×1 struct]
						           uri: 'http://vocab.nerc.ac.uk/collection/L05/current/130/'
    						vocabulary: 'SeaDataNet device categories'

           description: 'Conductivity Temperature (and Depth Sensor)'
    deviceCategoryCode: 'CTD'
    deviceCategoryName: 'CTD'
         hasDeviceData: 'true'
       longDescription: ' Conductivity Temperature Depth (CTD) is an abbreviated name for an instrument package that contains sensors for measuring the conductivity, temperature, and pressure of seawater. Salinity, sound velocity, and density are variables derived from sensor measurements. CTDs can carry additional instruments and sensors such as oxygen sensors, turbidity sensors and fluorometers. '
Property
Type
Description
Example
deviceCategory[]listA list of device categories.
deviceCategory[].cvTermstructA structure of controlled vocabulary terms.
cvTerm: [1×1 struct]
deviceCategory[].cvTerm.deviceCategory[]structA list of structure of controlled vocabulary term information for the device category.
deviceCategory: [1×1 struct]
deviceCategory[].cvTerm.deviceCategory[].uristringThe URI of the controlled vocabulary term.
uri: 'http://vocab.nerc.ac.uk/collection/L05/current/130/'
deviceCategory[].cvTerm.deviceCategory[].vocabularystringThe name of the controlled vocabulary to which the term belongs.
vocabulary: 'SeaDataNet device categories'
deviceCategory[].descriptionstringThe short description of the device category.
description: 'Conductivity Temperature (and Depth Sensor)'
deviceCategory[].deviceCategoryCodestringA code to uniquely identify a device category.
deviceCategoryCode: 'CTD'
deviceCategory[].deviceCategoryNamestringThe name of the device category.
deviceCategoryName: 'CTD'
deviceCategory[].hasDeviceDatastringIndicates that data products can be requested using the device category for a location.
hasDeviceData: 'true'
deviceCategory[].longDescriptionstringThe long description of the device category.
longDescription: ' Conductivity Temperature Depth (CTD) is an abbreviated 
name for an instrument package that contains sensors for
measuring the conductivity, temperature, and pressure of
seawater. Salinity, sound velocity, and density are variables
derived from sensor measurements. CTDs can carry additional
instruments and sensors such as oxygen sensors, turbidity
sensors and fluorometers. '
Example - Print all device categories available at Barkley Canyon - Upper Slope
o = ONC('YOUR_TOKEN_HERE');

deviceCategories = o.getDeviceCategories({'locationCode','NCBC'});    #NCBC - Barkely Canyon / Upper Slope

for i=1:numel(deviceCategories)
    disp(deviceCategories(i));
end


getProperties()

getProperties(filters)


Returns a list of properties, as a list of struct objects that meet the criteria defined by the input filters.


Parameter
Type
Description
Example
Optional


filtersstruct or array

A comma separated list of one or more filter criteria, used to return an exclusive set of properties elements from the ONC properties endpoint.

struct('propertyCode','seawatertemperature')

or

{'propertyCode','seawatertemperature'}


Returns

A list of property objects.

             cvTerm: [1×1 struct]
				    property: []
				         uom: [1×1 struct]
						           uri: 'http://vocab.nerc.ac.uk/collection/P06/current/UPDB/'
						    vocabulary: 'BODC data storage units'

        description: 'Pressure'
      hasDeviceData: 'true'
    hasPropertyData: 'true'
       propertyCode: 'pressure'
       propertyName: 'Pressure'
                uom: 'decibar'
Property
Type
Description
Example
property[]listA list of properties.

property[].cvTermstructA structure of controlled vocabulary terms.
cvTerm: [1×1 struct]
property[].cvTerm.property[]structA list of structures of controlled vocabulary term information for the property.
property: []
property[].cvTerm.property[].uristringThe URI of the controlled vocabulary term.
property[].cvTerm.property[].vocabularystringThe name of the controlled vocabulary to which the term belongs.
property[].cvTerm.uom[]structA list of structures of controlled vocabulary term information for the unit of measure.
uom: [1×1 struct]
property[].cvTerm.uom[].uristringThe URI of the controlled vocabulary term.
uri: 'http://vocab.nerc.ac.uk/collection/P06/current/UPDB/'
property[].cvTerm.uom[].vocabularystringThe name of the controlled vocabulary to which the term belongs.
vocabulary: 'BODC data storage units'
property[].descriptionstringThe short description of the device category.
description: 'Pressure'
property[].hasDeviceDatastringIndicates whether data products can be requested using the property code, along with a device category for a location.
hasDeviceData: 'true'
property[].hasPropertyDatastringIndicates whether data products can be requested using the property code for a location.
hasPropertyData: 'true'
property[].propertyCodestringA code that uniquely identifies the property.
propertyCode: 'pressure'
property[].propertyNamestringThe name of the property.
propertyName: 'Pressure'
property[].uomstringThe Unit of Measure used for the property measurements.
uom: 'decibar'
Example - Print all properties that are available at Barkley Canyon - Axis
o = onc('YOUR_TOKEN_HERE');

properties = o.getProperties({'locationCode','BACAX'});  #BACAX - Barkley Canyon / Axis

for i=1:numel(properties)
    disp(properties(i));
end


getDataProducts()

getDataProducts(filters)


Returns a list of data products as a list of struct objects that meet the criteria defined by the input filters.


Parameter
Type
Description
Example
Optional


filtersstruct or array

A comma separated list of one or more filter criteria, used to return an exclusive set of data product & extension elements from the ONC dataProducts endpoint.

struct('dataProductCode','TSSD', ...
       'extension','json')
or
{'dataProductCode','TSSD', ...
 'extension','json'}


Returns

A list of data product objects.

    dataProductCode: 'TSSD'
    dataProductName: 'Time Series Scalar Data'
          extension: 'json'
      hasDeviceData: 1
    hasPropertyData: 1
       helpDocument: 'https://wiki.oceannetworks.ca/display/DP/1'
Property
Type
Description
Example
dataProduct[]listA list of data products.
[]
dataProduct[].dataProductCodestringA code that uniquely identifies a data product.
dataProductCode: 'TSSD'
dataProduct[].dataProductNamestringThe name of the data product.
dataProductName: 'Time Series Scalar Data'
dataProduct[].extensionstringThe file name extension for a data product.
extension: 'json'
dataProduct[].hasDeviceDatastringIndicates whether the data product can be requested using a device category code and a location code.
hasDeviceData: 1
dataProduct[].hasPropertyDatastringIndicates whether the data product can be requested using a property code and a location code or device code.
hasPropertyData: 1
dataProduct[].helpDocumentstringA Link URL to the Oceans 2.0 Help documentation for the specific Data Product.
helpDocument: 'https://wiki.oceannetworks.ca/display/DP/1'



Example - Print all MatLab data product
o = onc('YOUR_TOKEN_HERE');

dataProducts = o.getDataProducts({'extension','mat'}); %mat - MatLab

for i=1:numel(dataProducts)
    disp(dataProducts(i));
end


Data Product Download methods

orderDataProduct()

orderDataProduct(filters, maxRetries, downloadResultsOnly, includeMetadataFile)


Requests a data product and downloads the generated files to the class's outPath.

This method performs the complete data product download workflow by calling additional methods to perform the following steps:

 1. Request a data product, which includes estimates for download size and time.

 2. Run a requested data product, which kicks off a process on the task machine to generate the data product.

 3. Download the data product to disk. The process will continue to poll the web service to determine if the product is ready to download. If it is not ready, status messages will be provided. Once it is ready, it will download the data product to disk.


Parameter
Type
Description
Example
Required


filtersstruct or array

A comma separated list of filter criteria parameters, used to request data as a data product from the ONC dataProductDelivery endpoint.

struct('locationCode','BACAX',...
'deviceCategoryCode','ADCP2MHZ',...
'dataProductCode','TSSD',...
'extension','csv',...
'dateFrom','2016-07-27T00:00:00.000Z',...
'dateTo','2016-08-01T00:00:00.000Z',...
'dpo_qualityControl',1,...
'dpo_resample','none',...
'dpo_dataGaps',0)

or

{'locationCode','BACAX',...
'deviceCategoryCode','ADCP2MHZ',...
'dataProductCode','TSSD',...
'extension','csv',...
'dateFrom','2016-07-27T00:00:00.000Z',...
'dateTo','2016-08-01T00:00:00.000Z',...
'dpo_qualityControl',1,...
'dpo_resample','none',...
'dpo_dataGaps',0}

Option


maxRetriesint

The number of times to retry the service before the function aborts.

  • If excluded, the default of 100 is used.

downloadResultsOnlyboolean

Indicates whether the files will be downloaded or if only the URL to the file will be returned.

  • false - Files are downloaded to the ONC class outPath property location.
  • true - Files will not be downloaded. The download URLs are available from the url property for each downloadResult in downloadResults in the returned struct.
  • If excluded, the default of false is used.

includeMetadataFileboolean

Indicates whether the metadata file associated with the data product request will be downloaded.

  • false - Metadata file is not downloaded.
  • true - Metadata file is downloaded.
  • If excluded, the default of false is used.


Returns

A structure of download results and run time statistics.

           url: "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=b6ede000-1865-4ac3-94ad-e87d8bdfd307&dpRunId=4658962&index=1"
      messages: {1×2 cell}
        status: 'complete'
          size: 3060227
          file: 'c:\ONC\data\BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean.csv'
         index: 1
    downloaded: 1

           url: "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=b6ede000-1865-4ac3-94ad-e87d8bdfd307&dpRunId=4658962&index=meta"
      messages: {}
        status: 'complete'
          size: 27504
          file: 'c:\ONC\data\BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean_CSV_META.pdf'
         index: 'meta'
    downloaded: 1
Property
Type
Description
downloadResultslistA cell array of download results struct objects.
downloadResults{}.urlstringThe URL used to make the download request.
downloadResults{}.messageslistA cell array of the messages that were returned from the dataProductDelivery download method when it was polled.
downloadResults{}.statusstring

The status of the download process at the request. Possible values are:

  • "running" - The data product request is running on the Task server.
  • "complete" - The data product request Task has completed and file has been downloaded or URL has been returned.
  • "error" - An error, preventing the task execution or download from completing successfully, has occurred.
downloadResults{}.sizefloatThe actual size of the file in bytes.
downloadResults{}.filestringThe full path of the file that was downloaded.
downloadResults{}.indexstringThe index of the file downloaded. The index can either be a number 1-* or "meta" for the data product metadata file.
downloadResults{}.downloadedbooleanIndicates whether the file was downloaded. If the filter downloadResultsOnly=True is used, the data product is not downloaded and the value will be False.
Example - Download Time Series Scalar Data Product in CSV format for ADCP 2 MHZ at Barkley Canyon - Axis
o = onc('YOUR_TOKEN_HERE');

results = o.orderDataProduct(struct('locationCode','BACAX',...
                				    'deviceCategoryCode','ADCP2MHZ',...
                				    'dataProductCode','TSSD',...
                				    'extension','csv',...
                				    'dateFrom','2016-07-27T00:00:00.000Z',...
                				    'dateTo','2016-08-01T00:00:00.000Z',...
                				    'dpo_qualityControl',1,...
                				    'dpo_resample','none',...
                				    'dpo_dataGaps',0),100,false,true);
            
for i=1:numel(results)
    disp(results{i});
end


requestDataProduct()
requestDataProduct(filters)


Requests a data product using the dataProductDelivery service and provides request information so that the calling function can decide whether to run the data product.
The struct of information it returns includes a requestID, which is used to run the data product, and estimates of the expected download times and file sizes.


Parameter
Type
Description
Example
Required


filters

struct or array

A comma separated list of filter criteria parameters, used to request data as a data product from the ONC dataProductDelivery endpoint.

struct('locationCode','BACAX',...
'deviceCategoryCode','ADCP2MHZ',...
'dataProductCode','TSSD',...
'extension','csv',...
'dateFrom','2016-07-27T00:00:00.000Z',...
'dateTo','2016-08-01T00:00:00.000Z',...
'dpo_qualityControl',1,...
'dpo_resample','none',...
'dpo_dataGaps',0)
or
{'locationCode','BACAX', ...
'deviceCategoryCode','ADCP2MHZ', ...
'dataProductCode','TSSD', ...
'extension','csv', ...
'dateFrom','2016-07-27T00:00:00.000Z', ...
'dateTo','2016-08-01T00:00:00.000Z', ...
'dpo_qualityControl',1, ...
'dpo_resample','none', ...
'dpo_dataGaps',0}


Returns

A data product request structure

for archived files (AD):

           dpRequestId: 2046404
    compressedFileSize: 12563408
              fileSize: 70766230
              numFiles: 4
         downloadTimes: {1x3 cell}
 
 
                         10Mbps: 7.076623
                         50Mbps: 1.4153247
                         150Mbps: 0.47177488


for generated files:

                dpRequestId: 2046404
          estimatedFileSize: 8348187
    estimatedProcessingTime: 16
Property
Type
Description
Example
Always contains
dpRequestIdintA unique id for a data product request.
dpRequestId: 2046404
May contain
compressedFileSizeintThe compressed size of the known file(s) in bytes.compressedFileSize: 12563408
fileSizeintThe size of known file(s) in bytes.fileSize: 70766230
numFilesintThe number of files.numFiles: 4
downloadTimescell arrayA structure of estimated download times.
downloadTimes: {1x3 cell}
              10Mbps: 7.076623
              50Mbps: 1.4153247
              150Mbps: 0.47177488
estimatedFileSizeintThe estimated file size of the generated data product.estimatedFileSize: 8348187
estimatedProcessingTimeintThe estimated time, in seconds, that it will take to run the data product request.estimatedProcessingTime: 16
Example - Download Time Series Scalar Data Product in CSV format for ADCP 2 MHZ at Barkley Canyon - Axis
o = onc('YOUR_TOKEN_HERE');

requestInfo = o.requestDataProduct(struct('locationCode','BACAX',...
                				          'deviceCategoryCode','ADCP2MHZ',...
                				          'dataProductCode','TSSD',...
                				          'extension','csv',...
                				          'dateFrom','2016-07-27T00:00:00.000Z',...
                				          'dateTo','2016-08-01T00:00:00.000Z',...
                				          'dpo_qualityControl',1,...
                				          'dpo_resample','none',...
                				          'dpo_dataGaps',0));
            
disp(requestInfo);


runDataProduct()
runDataProduct(requestId)


Runs a data product request using the dataProductDelivery service with a Request Id and returns a list of run ids


Parameter
Type
Description
Example
Required


requestIdint

A dataProductDelivery dpRequestId, which is returned by the dataProductDelivery service request method, or as the 'dpRequestId' property in the dpRequest returned by the requestDataProduct() method.

2046404


Returns

A list of runIds.

    dpRunId: 4659102
     status: 'data product running'
Example - Run a requested data product
o = onc('YOUR_TOKEN_HERE');

runs = o.runDataProduct(YOUR_REQUEST_ID_HERE);
 
disp(runs);


downloadDataProduct()
downloadDataProduct(runId, fileCount, estimatedProcessingTime, maxRetries, downloadResultsOnly, includeMetadataFile)


Polls the dataProductDelivery service until data product generation task is complete and downloads all of the files and/or retrieves the file information (URL, file and download status).


Parameter
Type
Description
Example
Required


runIdint

A dataProductDelivery dpRunId, which is returned by the dataProductDelivery service run method, or as the dpRunId property in the list returned by the runDataProduct() method.

4629218
Option


fileCountint

The actual or estimated file count, which is returned from the dataProductDelivery request method.

  • If there is no estimated file count, use 0.
  • If excluded, the default of 0 is used.
1
estimatedProcessingTimeint

The estimated time in seconds, to run the request on the task machine.

  • Used to determine how often the dataProductDelivery service is called to determine whether the task processing is complete.
  • Estimated processing time is provided by the dataProductDelivery request method.
2
maxRetriesint

The number of times to retry the service before the function aborts.

  • If excluded, the default of 100 is used.
10
downloadResultsOnlyboolean

Determines whether the files will be downloaded or if only the URL to the file will be returned.

  • false - Files are downloaded to the ONC class outPath property location.
  • true - Files will not be downloaded. The download URLs are available from the url property for each downloadResult in downloadResults in the returned struct.
  • If excluded, the default of false is used.
true
includeMetadataFileboolean

Indicates whether the metadata file associated with the data product request will be downloaded.

  • false - Metadata file is not downloaded.
  • true - Metadata file is downloaded.
  • If excluded, the default of false is used.

true


Returns

A list of download results struct objects.

           url: "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=1"
      messages: {1×2 cell}
        status: 'complete'
          size: 3060227
          file: 'c:\ONC\data\BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean.csv'
         index: 1
    downloaded: 1

           url: "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=meta"
      messages: {}
        status: 'complete'
          size: 27504
          file: 'c:\ONC\data\BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean_CSV_META.pdf'
         index: 'meta'
    downloaded: 1
Property
Type
Description
urlstringThe URL used to make the download request.
messagelistA list of the messages that were returned from the dataProductDelivery download method when it was polled.
statusstring

The status of the download process at the request. Possible values are:

  • "running" - The data product request is running on the Task server.
  • "complete" - The data product request Task has completed and file has been downloaded or URL has been returned.
  • "error" - An error, preventing the task execution or download from completing successfully, has occurred.
sizefloatThe actual size of the file in bytes.
filestringThe full path of the file that was downloaded.
indexstringThe index of the file downloaded. The index can either be a number 1-* or "meta" for the data product metadata file.
downloadedbooleanIndicates whether the file was downloaded. If the filter downloadResultsOnly=True is used, the data product is not downloaded and the value will be False
Example - Download the results of requested data product run
o = onc('YOUR_TOKEN_HERE');

results = o.downloadDataProduct(YOUR_RUN_ID_HERE, 1);
 
for i=1:numel(results)
    disp(results{i});
end


getDataProductUrls()

getDataProductUrls(filters, maxRetries=100)


Orders a data product and return only the URLs, for download at a later time. URLs can be used with the downloadFile() or getJsonFromUrl() methods.


Parameter
Type
Description
Example
Required


filtersstruct or array

A comma separated list of filter criteria parameters, used to request data as a data product from the ONC dataProductDelivery endpoint.

struct('locationCode','BACAX',...
'deviceCategoryCode','ADCP2MHZ',...
'dataProductCode','TSSD',...
'extension','csv',...
'dateFrom','2016-07-27T00:00:00.000Z',...
'dateTo','2016-08-01T00:00:00.000Z',...
'dpo_qualityControl',1,...
'dpo_resample','none',...
'dpo_dataGaps',0)
or
{'locationCode','BACAX', ...
'deviceCategoryCode','ADCP2MHZ', ...
'dataProductCode','TSSD', ...
'extension','csv', ...
'dateFrom','2016-07-27T00:00:00.000Z', ...
'dateTo','2016-08-01T00:00:00.000Z', ...
'dpo_qualityControl',1, ...
'dpo_resample','none', ...
'dpo_dataGaps',0}
Option


maxRetriesint

The number of times to retry the service before the function aborts.

  • If excluded, the default of 100 is used.
10


Returns

A list of urls.

["https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=1"]
Example - Order a data product and get a list of the download urls
o = onc('YOUR_TOKEN_HERE');
 
urls = o.getDataProductUrls(struct('locationCode','BACAX',...
							       'deviceCategoryCode','ADCP2MHZ',...
                                   'dataProductCode','TSSD',...
							       'extension','json',...
							       'dateFrom','2016-07-27T00:00:00.000Z',...
							       'dateTo','2016-08-01T00:00:00.000Z',...
							       'dpo_qualityControl',1,...
							       'dpo_resample','none',...
							       'dpo_dataGaps',0,...
							       'dpo_jsonOutputEncoding','OM'),100);


for i=1:numel(urls)
    disp(urls{i});
end


downloadFile()

downloadFile(url, file=[])


Downloads a file from a URL, write it to a file and return download results information (URL, file, message and download status).


Parameter
Type
Description
Example
Required


urlstring

The URL to be downloaded.

https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN_HERE>
&dpRunId=<YOUR_RUN_ID_HERE>&index=<YOUR_INDEX_HERE>
filestring

The full path of the file download destination.

  • If excluded, the file name from the content disposition in the header is used, along with the onc class object outPath to create a full file name path.
c:/temp/myDownload.csv


Returns

A downloadResults structure.

           url: "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=b6ede000-1865-4ac3-94ad-e87d8bdfd307&dpRunId=4722272&index=1"
      messages: {}
          file: 'c:\ONC\data\matlab\myDownload.json'
    downloaded: 1
        status: 'complete'
Property
Type
Description
urlstringThe URL used to make the download request.
filestringThe full path of the file that was downloaded.
messagelistA list of the messages that were returned from the dataProductDelivery download method when it was polled.
downloadedbooleanIndicates whether the file was downloaded.
statusstring

The status of the download process at the request. Possible values are:

  • "running" - The data product request is running on the Task server.
  • "complete" - The data product request Task has completed and file has been downloaded or URL has been returned.
  • "error" - An error, preventing the task execution or download from completing successfully, has occurred.
Example - Download a file from a url
o = onc('YOUR_TOKEN_HERE');
 
url = 'https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN_HERE>&dpRunId=<YOUR_RUN_ID_HERE>&index=<YOUR_INDEX_HERE>';
file = 'c:/temp/myDownload.csv';

downloadResult = o.downloadFile(url, file);
 
disp(downloadResult);


decodeJsonFromUrl()

decodeJsonFromUrl(url)


Returns a structure object from the JSON returned from a URL


Parameter
Type
Description
Example
Required


urlstring

The URL to a JSON data product delivery result.

https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN_HERE>&dpRunId=<YOUR_RUN_ID_HERE>&index=<YOUR_INDEX_HERE>


Returns

A structure encoded from a JSON string.


Example - Get dictionary of results from json data product request
o = onc('YOUR_TOKEN_HERE');
 
urls = o.getDataProductUrls(struct('locationCode','BACAX',...
							       'deviceCategoryCode','ADCP2MHZ',...
                                   'dataProductCode','TSSD',...
							       'extension','json',...
							       'dateFrom','2016-07-27T00:00:00.000Z',...
							       'dateTo','2016-08-01T00:00:00.000Z',...
							       'dpo_qualityControl',1,...
							       'dpo_resample','none',...
							       'dpo_dataGaps',0,...
							       'dpo_jsonOutputEncoding','OM'),100);
 
for i=1:numel(urls)
	object = o.decodeJsonFromUrl(url);
 	disp(object);
end


Near Real-Time data product methods

getDirectScalarByStation() - deprecated

getDirectScalarByStation(filters, outputFormat, metadata, rowLimit) - deprecated in favour of getDirectScalar()


Returns scalar data, in JSON Object or Array format, in the response payload that meet the criteria defined by the input filters.


Parameter
Type
Description
Example
Required


filtersstruct or array

A comma separated list of filter criteria parameters, used to request data and metadata from the scalardata endpoint.

struct('locationCode','TWDP', ...

'deviceCategoryCode','TSG', ...
'begin','2016-09-01T00:00:00.000Z', ...
'end','2016-09-01T08:00:00.000Z')

or

{'locationCode','TWDP', ...
'deviceCategoryCode','TSG', ...
'begin','2016-09-01T00:00:00.000Z', ...
'end','2016-09-01T08:00:00.000Z'}

Option


outputFormatstring

The encoding of the response output.

  • Object - Data are a list of structures with sampleTime, value and qaqcFlag for a given sensor.
  • Array - Data have 3 arrays for a given sensor. Array of sampleTime, array of values and array of qaqcFlags.
  • If excluded, the default 'Object' is used.
"outputFormat","Array"
metadatastring

The amount of metadata detail included in the response output.

  • Minimum - Provides only basic property information. Response includes serviceMetadata structure only.
  • Full - Provides all property information. Response includes both metadata and serviceMetadata structures.
  • If excluded, the default 'Minimum' is used.
"metadata","Full"
rowLimitinteger

The maximum number of rows of scalar data that will be returned for each sensor.

  • Maximum is 100,000.
  • If excluded, the default 100,000 is used.
"rowLimit",5000


Returns

A structure that contains sensor data that matches the filter criteria defined in the input parameters, metadata and service metadata.

 metadata: [1×1 struct]
 
                  bbox: [1×1 struct]
				    	maxDepth: 3
					      maxLat: 49.1139
					      maxLon: -123.5264
					    minDepth: 3
					      minLat: 49.1139
				      	  minLon: -123.5264
                 depth: 3
    deviceCategoryName: 'TSG'
              latitude: 49.1139
             longitude: -123.5264
                 begin: '2016-09-01T00:00:00.000Z'
                   end: '2016-09-01T00:00:30.000Z'
          locationCode: 'TWDP'
 
sensorData: [3×1 struct]
 
        actualSamples: 1
                 data: [1×1 struct]
     				 qaqcFlag: 1
    			   sampleTime: '2016-09-01T00:00:07.037Z'
                        value: 3.4429
               sensor: 'Conductivity'
           sensorName: 'Conductivity'
        unitOfMeasure: 'S/m'
 
 
serviceMetadata: [1×1 struct]
              metadata: 'Full'
          nextDateFrom: '2016-09-01T00:00:17.041Z'
          outputFormat: 'Object'
              rowLimit: 100000
               sensors: []
    totalActualSamples: 3
                 begin: '2016-09-01T00:00:00.000Z'
                   end: '2016-09-01T00:00:10.000Z'
    deviceCategoryCode: 'TSG'
          locationCode: 'TWDP'
Property
Type
Description
metadatastructA structure of metadata, if metadata='Full' input parameter is used.
metadata.bboxstructA Bounding Box structure.
metadata.bbox.maxDepthfloatThe maximum depth of the instruments contributing to the results.
metadata.bbox.maxLatfloatThe maximum Latitude of bounding box of the instruments contributing to the results.
metadata.bbox.maxLonfloatThe maximum Longitude of the bounding box of the instruments contributing to the results.
metadata.bbox.minDepthfloatThe minimum Depth of the instruments contributing to the results.
metadata.bbox.minLatfloatThe minimum Latitude of bounding box of the instruments contributing to the results.
metadata.bbox.minLonfloatThe minimum Longitude of the bounding box of the instruments contributing to the results.
sensorDatalistA list of sensor structures.
sensorData[].acutalSamplesintThe number of samples in the data list.
sensorData[].datalistA list of observation structures.
sensorData[].data[].qaqcFlagintThe QAQC Flag for the observation.
sensorData[].data[].sampleTimedatetime string

The recorded time of the observation.

sensorData[].data[].valuefloatThe value of the observation.
sensorData[].sensorstringThe code of the sensor that is being observed.
sensorData[].sensorNamestringThe name of the sensor that is being observed.
sensorData[].unitOfMeasurestringThe unit of measure of the observation.
serviceMetadatastructA structure of the metadata for the service request.
serviceMetadata.metadatastringThe requested metadata filter.
serviceMetadata.nextDataFromdatetime stringThe begin date for next reading in yyyy-MM-ddTHH:mm:ss.SSSZ format.
serviceMetadata.outputFormatstringThe requested JSON output format.
serviceMetadata.rowLimitintThe requested row limit per sensor.
serviceMetadata.sensorsstringA comma separated list of the requested sensors.
serviceMetadata.totalActualSamplesintThe number of observations expected for all specified sensors.
serviceMetadata.begindatetime stringThe begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
serviceMetadata.enddatetime stringThe end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
serviceMetadata.deviceCategoryCodestringThe Device Category Code of the request. See Available Device Categories for further details.
serviceMetadata.locationCodestringThe Location Code of the request. See Available Locations for further details.
Example - Print the last Thermosalinograph reading from Tswwassen - Duke Point Ferry
o = onc('YOUR_TOKEN_HERE');
 
result = o.getDirectScalarByStation({'locationCode','TWDP','deviceCategoryCode','TSG'});

disp(result);
Example - Print 1 hour of Thermosalinograph readings from Tswwassen - Duke Point Ferry
o = onc('YOUR_TOKEN_HERE');
 
result = o.getDirectScalarByStation(struct('locationCode','TWDP','deviceCategoryCode','TSG', 'begin','2016-09-01T00:00:00.000Z', 'end','2016-09-01T01:00:00.000Z'));

disp(result);
Example - Print 1 hour of Thermosalinograph readings from Tswwassen - Duke Point Ferry as an Array
o = onc('YOUR_TOKEN_HERE');
 
result = o.getDirectScalarByStation(struct('locationCode':'TWDP','deviceCategoryCode':'TSG', 'begin':'2016-09-01T00:00:00.000Z', 'end':'2016-09-01T01:00:00.000Z'),'Array');

disp(result);


getDirectScalar()

getDirectScalar(filters)


Returns scalar data in the response payload that meet the criteria defined by the input filters.


Parameter

Type

Description

Example

Required


filtersstruct or array

A comma separated list of filter criteria parameters, used to request data and metadata from the scalardata endpoint.

  • A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
  • Filters must include locationCode and deviceCategoryCode.
  • Filters can optionally Include dateFrom and dateTo (a date range).
  • Filters can optionally specify "metadata" as "minimum" (default) or "full".
    • Minimum provides only basic property information.
    • Full provides all property information. Response includes metadata structure.
  • Filters can optionally specify "rowLimit", the maximum number of rows of data that will be returned for each sensor.
    • The maximum is 100,000. If omitted or a higher or invalid limit is specified, the default of 100,000 is used.
  • See locations Discovery Service and deviceCategories Discovery Service  for more information on filter usage.

struct('locationCode','TWDP', ...

'deviceCategoryCode','TSG', ... 'dateFrom','2016-09-01T00:00:00.000Z', ...
'dateTo','2016-09-01T08:00:00.000Z')

or

{'locationCode','TWDP', ...
'deviceCategoryCode','TSG', ...
'dateFrom','2016-09-01T00:00:00.000Z', ...
'dateTo','2016-09-01T08:00:00.000Z'}


Returns

A structure that contains sensor data that matches the filter criteria defined in the input parameters, metadata and service metadata.

 metadata: [1×1 struct]
 
                  boundingBox: [1×1 struct]
				    	maxDepth: 3
					      maxLat: 49.1139
					      maxLon: -123.5264
					    minDepth: 3
					      minLat: 49.1139
				      	  minLon: -123.5264
                 depth: 3
    deviceCategoryCode: 'Thermosalinograph'
              latitude: 49.1139
             longitude: -123.5264
          locationName: 'Tsawwassen - Duke Point'
 
sensorData: [3×1 struct]
 
        actualSamples: 1
                 data: [1×1 struct]
     				 qaqcFlag: 1
    			   sampleTime: '2016-09-01T00:00:07.037Z'
                        value: 3.4429
               sensor: 'Conductivity'
           sensorName: 'Conductivity'
        unitOfMeasure: 'S/m'
 
 
queryURL: 'https://data.oceannetworks.ca/api/scalardata?method=getByLocation&token=f68bc7e1-f231-481d-b32e-590c5c1e1ee8&locationCode=TWDP&d...' <Preview truncated at 128 characters>


next: [1×1 struct]
           url: 'https://data.oceannetworks.ca/api/scalardata?metadata=full&method=getByLocation&end=2016-08-01T00%3A00%3A00.000Z&rowLimit=10&loc...' <Preview truncated at 128 characters>
    parameters: [1x1 struct]
              metadata: 'Full'
                 token: 'YOUR_TOKEN_HERE'
              rowLimit: 10
                 begin: '2016-09-01T00:00:00.000Z'
                   end: '2016-09-01T00:00:10.000Z'
    deviceCategoryCode: 'TSG'
          locationCode: 'TWDP'

Property

Type

Description

metadatastructA structure of metadata, if metadata='Full' input parameter is used.
metadata.boundingBoxstructA Bounding Box structure.
metadata.boundingBox.maxDepthfloatThe maximum depth of the instruments contributing to the results.
metadata.boundingBox.maxLatfloatThe maximum Latitude of bounding box of the instruments contributing to the results.
metadata.boundingBox.maxLonfloatThe maximum Longitude of the bounding box of the instruments contributing to the results.
metadata.boundingBox.minDepthfloatThe minimum Depth of the instruments contributing to the results.
metadata.boundingBox.minLatfloatThe minimum Latitude of bounding box of the instruments contributing to the results.
metadata.boundingBox.minLonfloatThe minimum Longitude of the bounding box of the instruments contributing to the results.
sensorDatalistA list of sensor structures.
sensorData[].acutalSamplesintThe number of samples in the data list.
sensorData[].datastructA structure of observation data lists.
sensorData[].data.qaqcFlagslist of intThe QAQC Flag for the observation.
sensorData[].data.sampleTimeslist of datetime string

The recorded time of the observation.

sensorData[].data.valueslist of floatThe value of the observation.
sensorData[].sensorCodelistThe code of the sensor that is being observed.
sensorData[].sensorNamestringThe name of the sensor that is being observed.
sensorData[].unitOfMeasurestringThe unit of measure of the observation.
nextstructA structure of the metadata for the service request.
next.urlstringThe request url.
next.parametersstructA structure of the metadata for the service request.
next.parameters.rowLimitintThe requested row limit per sensor.
next.parameters.tokenstringThe user's token.
next.parameters.methodstring'getByLocation'.
next.parameters.begindatetime stringThe begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
next.parameters.enddatetime stringThe end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
next.parameters.deviceCategoryCodestringThe Device Category Code of the request. See Available Device Categories for further details.
next.parameters.locationCodestringThe Location Code of the request. See Available Locations for further details.
Example - Print the last Thermosalinograph reading from Tswwassen - Duke Point Ferry
o = onc('YOUR_TOKEN_HERE');
 
result = o.getDirectScalar({'locationCode','TWDP','deviceCategoryCode','TSG'});

disp(result);
Example - Print 1 hour of Thermosalinograph readings from Tswwassen - Duke Point Ferry
o = onc('YOUR_TOKEN_HERE');
 
result = o.getDirectScalar(struct('locationCode','TWDP','deviceCategoryCode','TSG', 'dateFrom','2016-09-01T00:00:00.000Z', 'dateTo','2016-09-01T01:00:00.000Z'));

disp(result);


getDirectRawByStation() - deprecated

getDirectRawByStation(filters, rowLimit) - deprecated in favour of getDirectRawByLocation()


Returns raw data from an instrument in the payload, in JSON format that meet the criteria defined by the input filters.


Parameter
Type
Description
Example
Required


filter

struct

or

cell array

A comma separated list of filter criteria parameters, used to request data and metadata from the rawdata endpoint.

struct('locationCode','TWDP', ...
'deviceCategoryCode','TSG', ...
'begin','2016-09-01T00:00:00.000Z', ...
'end','2016-09-01T08:00:00.000Z')

or

{'locationCode','TWDP', ...
'deviceCategoryCode','TSG', ...
'begin','2016-09-01T00:00:00.000Z', ...
'end','2016-09-01T08:00:00.000Z'}

Option


rowLimitinteger

The maximum number of rows of raw data that will be returned

  • Maximum is 100,000.
  • If excluded, the default 100,000 is used.
"rowLimit",5000


Returns

A structure that contains sensor data matching the filter criteria defined in the input parameters, metadata and service metadata.

        data: [1×1 struct]
       		   rawData: '20160901-00:00:07.037, 12.9162,  3.44294,  28.9096'
    		sampleTime: '2016-09-01T00:00:07.037Z'

    metadata: [1×1 struct]
	     dataMetadata: [1×1 struct]
		        firstTimestamp: '2016-09-01T00:00:07.037Z'
		    hasMoreDataInRange: 0
		         lastTimestamp: '2016-09-01T00:00:07.037Z'
		          numberOfData: 1
		          locationName: 'Tsawwassen - Duke Point'

	    queryMetadata: [1×1 struct]
		              rowLimit: 100000
		                 begin: '2016-09-01T00:00:00.000Z'
		                   end: '2016-09-01T00:00:10.000Z'
		    deviceCategoryCode: 'TSG'
		          locationCode: 'TWDP'
Property
Type
Description
datastruct
data[].rawDatastringA raw data string representing a sample at a specific time.
data[].sampleTimedatetime string

The recorded time of the observation.

metadatastructA structure containing metadata.
metadata.dataMetadatastructA structure containing metadata about the data.
metadata.dataMetadata.firstTimestampdatetime stringThe date time of the first record in yyyy-MM-ddTHH:mm:ss.SSSZ format.
metadata.dataMetadata.hasMoreDataInRangeint

Whether more data are available within the range of the request. For example if 1,000 records are returned (because the rowLimit=1000), but there chould be 200,000 rows as defined by the filter criteria.

  • 0 = False
  • 1 = True
metadata.dataMetadata.lastTimestampdatetime stringThe date time of the last record in yyyy-MM-ddTHH:mm:ss.SSSZ format.
metadata.dataMetadata.numberOfDataintThe number of samples in the data list.
metadata.dataMetadata.locationNamestringThe full name of the location.
metadata.queryMetadatastructA structure containing metadata about the data request (query).
metadata.queryMetadata.rowLimitintThe requested row limit per sensor.
metadata.queryMetadata.begindatetime stringThe begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
metadata.queryMetadata.enddatetime stringThe end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
metadata.queryMetadata.deviceCategoryCodestringThe Device Category Code of the request. See Available Device Categories for further details.
metadata.queryMetadata.locationCodestringThe Location Code of the request. See Available Locations for further details.
Example - Print the last raw instrument reading from the CTD at Barkley Canyon Axis
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectRawByStation(struct('locationCode','BACAX','deviceCategoryCode','CTD'),1);

disp(payload);
Example - Print the last raw instrument reading from AIS Reviever at the Underwater Listening Station at IONA
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectRawByStation(struct('locationCode','IONA','deviceCategoryCode','AISRECEIVER'),1);

disp(payload);
Example - Print 1 hour of raw CTD readings from Barkley Canyon Axis
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectRawByStation(struct('locationCode','BACAX','deviceCategoryCode','CTD','begin','2017-05-23T00:00:00.000Z','end','2017-05-23T01:00:00.000Z'));

disp(payload);


getDirectRawByLocation()

getDirectRawByLocation(filters)


Returns raw data from an instrument in the payload, in JSON format that meet the criteria defined by the input filters.


Parameter

Type

Description

Example

Required


filter

struct

or

cell array

A comma separated list of filter criteria parameters, used to request data and metadata from the rawdata endpoint.

  • A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
  • Filters must include locationCode and deviceCategoryCode.
  • Filters can optionally Include dateFrom and dateTo (a date range).
  • Filters can optionally specify "rowLimit", the maximum number of rows of data that will be returned for each sensor.
    • The maximum is 100,000. If omitted or a higher or invalid limit is specified, the default of 100,000 is used.
  • See locations Discovery Service and deviceCategories Discovery Service  for more information on filter usage.

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

or

{'locationCode','TWDP', ...
'deviceCategoryCode','TSG', ...
'dateFrom','2016-09-01T00:00:00.000Z', ...
'dateTo','2016-09-01T08:00:00.000Z'}


Returns

A structure that contains sensor data matching the filter criteria defined in the input parameters, metadata and service metadata.

        data: [1×1 struct]
    metadata: [1×1 struct]

        next: [1×1 struct]


Property

Type

Description

datastruct
data.readings[]stringA raw data string representing a sample at a specific time.
data.times[]datetime string

The recorded time of the observation.

metadata.locationNamestringThe full name of the location.
nextstructA structure containing metadata.
next.parametersstructA structure containing metadata about the data.
next.urlstringA string containing the query url.
next.parameters.rowLimitintThe requested row limit per sensor.
next.parameters.begindatetime stringThe begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
next.parameters.enddatetime stringThe end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
next.parameters.deviceCategoryCodestringThe Device Category Code of the request. See Available Device Categories for further details.
next.parameters.locationCodestringThe Location Code of the request. See Available Locations for further details.
Example - Print the last raw instrument reading from the CTD at Barkley Canyon Axis
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectRawByLocation(struct('locationCode','BACAX','deviceCategoryCode','CTD','rowLimit',1));

disp(payload);
Example - Print the last raw instrument reading from AIS Reviever at the Underwater Listening Station at IONA
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectRawByLocation(struct('locationCode','IONA','deviceCategoryCode','AISRECEIVER','rowLimit',1));

disp(payload);
Example - Print 1 hour of raw CTD readings from Barkley Canyon Axis
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectRawByLocation(struct('locationCode','BACAX','deviceCategoryCode','CTD','dateFrom','2017-05-23T00:00:00.000Z','dateTo','2017-05-23T01:00:00.000Z'));

disp(payload);

getDirectRawByDevice()

getDirectRawByDevice(filters)


Returns raw data from an instrument in the payload, in JSON format that meet the criteria defined by the input filters.


Parameter

Type

Description

Example

Required


filter

struct

or

cell array

A comma separated list of filter criteria parameters, used to request data and metadata from the rawdata endpoint.

  • A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
  • Filters must include deviceCode.
  • Filters can optionally Include dateFrom and dateTo (a date range).
  • Filters can optionally specify "rowLimit", the maximum number of rows of data that will be returned for each sensor.
    • The maximum is 100,000. If omitted or a higher or invalid limit is specified, the default of 100,000 is used.
  • See locations Discovery Service and deviceCategories Discovery Service and devices Discovery Service for more information on filter usage.

struct('deviceCode','ICLISTENHF1293', ...
'dateFrom','2016-09-01T00:00:00.000Z', ...
'dateTo','2016-09-01T08:00:00.000Z')

or

{'deviceCode','ICLISTENHF1293', ...
'dateFrom','2016-09-01T00:00:00.000Z', ...
'dateTo','2016-09-01T08:00:00.000Z'}


Returns

A structure that contains sensor data matching the filter criteria defined in the input parameters, metadata and service metadata.

        data: [1×1 struct]
        next: [1×1 struct]

Property

Type

Description

datastruct
data.readings[]stringA raw data string representing a sample at a specific time.
data.times[]datetime string

The recorded time of the observation.

nextstructA structure containing metadata.
next.parametersstructA structure containing metadata about the data.
next.urlstringA string containing the query url.
next.parameters.rowLimitintThe requested row limit per sensor.
next.parameters.begindatetime stringThe begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
next.parameters.enddatetime stringThe end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format.
next.parameters.deviceCodestringThe Device Code of the request. See Available Device Categories for further details.
Example - Print the last raw instrument reading from the CTD at Barkley Canyon Axis
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectRawByDevice(struct('deviceCode','ICLISTENHF1293','rowLimit',1));

disp(payload);
Example - Print the last raw instrument reading from AIS Reviever at the Underwater Listening Station at IONA
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectRawByDevice(struct('deviceCode','ICLISTENHF1293','rowLimit',1));

disp(payload);
Example - Print 1 hour of raw CTD readings from Barkley Canyon Axis
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectRawByDevice(struct('deviceCode','BACAX','dateFrom','2017-05-23T00:00:00.000Z','dateTo','2017-05-23T01:00:00.000Z'));

disp(payload);


getDirectFiles()

getDirectFiles( filters )


Returns data files from an instrument in the payload, in JSON format that meet the criteria defined by the input filters.


Parameter

Type

Description

Example

Required


filters

struct

or

cell array

A comma separated list of filter criteria parameters, used to request data and metadata from the rawdata endpoint.

  • A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
  • Filters must include locationCode.
  • Filters can optionally Include dateFrom and dateTo.
  • See locations Discovery Service for more information on filter usage.

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

or

{'locationCode','TWDP', ...
'deviceCategoryCode','TSG', ...
'dateFrom','2016-09-01T00:00:00.000Z', ...
'dateTo','2016-09-01T08:00:00.000Z'}


Returns

A structure that contains sensor data matching the filter criteria defined in the input parameters, metadata and service metadata.

        data: [1×1 struct]
       		   rawData: '20160901-00:00:07.037, 12.9162,  3.44294,  28.9096'
    		sampleTime: '2016-09-01T00:00:07.037Z'

    metadata: [1×1 struct]
	     dataMetadata: [1×1 struct]
		        firstTimestamp: '2016-09-01T00:00:07.037Z'
		    hasMoreDataInRange: 0
		         lastTimestamp: '2016-09-01T00:00:07.037Z'
		          numberOfData: 1
		          locationName: 'Tsawwassen - Duke Point'

	    queryMetadata: [1×1 struct]
		              rowLimit: 100000
		                 begin: '2016-09-01T00:00:00.000Z'
		                   end: '2016-09-01T00:00:10.000Z'
		    deviceCategoryCode: 'TSG'
		          locationCode: 'TWDP'

Property

Type

Description

datastruct
Example - Print the last raw instrument reading from the CTD at Barkley Canyon Axis
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectFiles(struct('locationCode','BACAX','deviceCategoryCode','CTD'),1);

disp(payload);
Example - Print the last raw instrument reading from AIS Reviever at the Underwater Listening Station at IONA
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectFiles(struct('locationCode','IONA','deviceCategoryCode','AISRECEIVER'),1);

disp(payload);
Example - Print 1 hour of raw CTD readings from Barkley Canyon Axis
o = onc('YOUR_TOKEN_HERE');
 
payload = o.getDirectFiles(struct('locationCode','BACAX','deviceCategoryCode','CTD','dateFrom','2017-05-23T00:00:00.000Z','dateTo','2017-05-23T01:00:00.000Z'));

disp(payload);



Please report all issues with the web services, documentation, samples and client libraries to the Oceans 2.0 Help Centre