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
Versions
version | Date | Description | Toolbox | Source |
---|---|---|---|---|
1.0 | 6/28/2017 | Alpha version. | ||
1.01 | 7/18/2017 | Added getDirectScalar(), getDirectRaw() and getDirectFiles() functions. | onc-1.01.mltbx | onc-1.02-source.zip |
1.02 | 7/28/2017 | Resolve unhandled exception with invalid parameters. Resolved naming inconsistencies. | onc-1.02.mltbx | onc-1.02-source.zip |
1.03 | 8/01/2017 | Added getDataProductUrls(), downloadFile() and decodeJsonFromUrl() functions | onc-1.03.mltbx | onc-1.03-source.zip |
1.04 | 8/03/2017 | Updated production URL from http://dmas.uvic.ca to http://data.oceannetworks.ca. | onc-1.04.mltbx | onc-1.04-source.zip |
1.05 | 8/11/2017 | Rename 'parameters' parameter to 'filters' in all applicable onc class functions. | onc-1.05.mltbx | onc-1.04-source.zip |
1.06 | 8/15/2017 | Added file parameter defult to the download() function. | onc-1.06.mltbx | onc-1.06-source.zip |
1.07 | 8/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.mltbx | onc-1.07-source.zip |
1.08 | 9/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.mltbx | onc-1.08-source.zip |
1.09 | 2018-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.mltbx | onc-1.09-source.zip |
1.10 | 2018-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.mltbx | onc-1.10-source.zip |
To download an attachment, please right click on the link and select Save Link As, Save 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 |
---|---|
onc | A 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 | |||
token | string | All 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=5ba514e8-1203-428c-8835-879c8173e387 |
Optional | |||
production | boolean | Indicates whether the ONC Production server URL is used for service requests.
| true or false |
showInfo | boolean | Indicates whether verbose script messages, such as request URL and processing time information, are displayed.
| true or false |
outPath | string | The path that downloaded files are saved to.
| 'c:/ONC/Download' |
timeout | int | The web service request timeout in seconds
| 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 | |||
filters | struct 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 |
---|---|---|---|
location[] | list | A list of location structures. | |
location[].deployments | int | The number of instrument deployments that meet the filter criteria. | deployments : 10 |
location[].locationName | string | The full name of the location. | locationName: "Axis (POD 1)" |
location[].depth | double | The average depth of the deployments. |
|
location[].bbox | struct | A Bounding Box structure. | |
location[].bbox.maxDepth | double | The maximum depth of the deployments. | maxDepth : 100 |
location[].bbox.maxLat | double | The maximum Latitude of bounding box of the deployments. | maxLat : 48.476740 |
location[].bbox.maxLon | double | The maximum Longitude of the bounding box of the deployments. | maxLon : - 123.294904 |
location[].bbox.minDepth | double | The minimum Depth of the deployments. | minDepth : 50 |
location[].bbox.minLat | double | The minimum Latitude of bounding box of the deployments. | minLat : 48.47670 |
location[].bbox.minLon | double | The minimum Longitude of the bounding box of the deployments. | minLon : - 123.294900 |
location[].description | string | The 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[].hasDeviceData | string | Indicates that data products can be requrested using a device category for the location. | hasDeviceData: "true" |
location[].lon | double | The average longitude of the deployments. | lon : - 123.294902 |
location[].locationCode | string | A code that unquely identifies a location. | locationCode: "BACAX" |
location[].hasPropertyData | string | Indicates that data products can be requested using property code for the location. | hasPropertyData: "true" |
location[].lat | double | The average latitude of the deployments. | lat : 48.47672 |
location[].dataSearchUrl | string | The location specific Data Search web page URL. | dataSearchURL: "https://data.oceannetworks.ca/DataSearch?location=BACAX" |
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 | |||
filters | struct 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[] | list | A list of devices. | [] |
device[].cvTerm | struct | A structure of controlled vocabulary terms. | cvTerm: [1×1 struct] |
device[].cvTerm.device[] | struct | A list of structures of controlled vocabulary term information for the device. | device: [1×1 struct] |
device[].cvTerm.device[].uri | string | The URI of the controlled vocabulary term. | uri: 'http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/' |
device[].cvTerm.device[].vocabulary | string | The name of the controlled vocabulary to which the term belongs. | vocabulary: 'SeaVoX Device Catalogue' |
device[].dataRating[] | list | A list of data ratings structures. | dataRating: [2×1 struct] |
device[].dataRating[].dateFrom | datetime string | The starting datetime for a data rating.
| dateFrom: '2008-11-01T00:00:00.000Z' |
device[].dataRating[].dateTo | datetime string | The ending datetime for a data rating.
| dateTo: '2010-05-27T19:27:04.000Z' |
device[].dataRating[].samplePeriod | double | The sample period, in seconds for the data rating. | samplePeriod: 1 |
device[].dataRating[].sampleSize | int | The size of the data sample for the data rating. | sampleSize: 1 |
device[].deviceCode | string | A code that unquely identifes a device. | deviceCode: 'BC_POD1_AD2M' |
device[].deviceId | int | A numeric id that uniquely identifies a device. | deviceId: 11302 |
device[].deviceLink | string | The URL link to the Devices Listing page for the specific device. | deviceLink: 'https://data.oceannetworks.ca/DeviceListing?DeviceId=11302' |
device[].deviceName | string | The name of the device. | deviceName: 'Nortek Aquadopp HR-Profiler 2965' |
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 | |||
filters | struct 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[].locationCode | string | The locationCode for the deployment location. | locationCode: "BACAX" |
deployment[].deviceCode | string | The deviceCode for a deployed device. | deviceCode: "SBECTD19p6813" |
deployment[].begin | datetime | The beginning datetime of the deployment. Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
| begin: '2010-07-27T00:00:00.000Z' |
deployment[].end | datetime | The ending datetime of the deployment.
Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
| end: '2016-08-01T00:00:00.000Z' |
deployment[].hasDeviceData | string | Indicates that data products can be requested using a device category code for the deployment. | hasDeviceData: 1 |
deployment[].depth | double | The depth of the device deployment. | depth : 982 |
deployment[].lat | double | The latitude of the device deployment. | lat : 48.31658 |
deployment[].lon | double | The longitude of the device deployment. | lon : - 126.0508 |
deployment[].heading | double | The heading of the device deployment. | heading : 244 |
deployment[].pitch | double | The pitch of the device deployment. | pitch : null |
deployment[].roll | double | The pitch of the device deployment. | roll : null |
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 | |||
filters | struct 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[] | list | A list of device categories. | |
deviceCategory[].cvTerm | struct | A structure of controlled vocabulary terms. | cvTerm: [1×1 struct] |
deviceCategory[].cvTerm.deviceCategory[] | struct | A list of structure of controlled vocabulary term information for the device category. | deviceCategory: [1×1 struct] |
deviceCategory[].cvTerm.deviceCategory[].uri | string | The URI of the controlled vocabulary term. | uri: 'http://vocab.nerc.ac.uk/collection/L05/current/130/' |
deviceCategory[].cvTerm.deviceCategory[].vocabulary | string | The name of the controlled vocabulary to which the term belongs. | vocabulary: 'SeaDataNet device categories' |
deviceCategory[].description | string | The short description of the device category. | description: 'Conductivity Temperature (and Depth Sensor)' |
deviceCategory[].deviceCategoryCode | string | A code to uniquely identify a device category. | deviceCategoryCode: 'CTD' |
deviceCategory[].deviceCategoryName | string | The name of the device category. | deviceCategoryName: 'CTD' |
deviceCategory[].hasDeviceData | string | Indicates that data products can be requested using the device category for a location. | hasDeviceData: 'true' |
deviceCategory[].longDescription | string | The long description of the device category. | longDescription: ' Conductivity Temperature Depth (CTD) is an abbreviated |
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 | |||
filters | struct 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[] | list | A list of properties. | |
property[].cvTerm | struct | A structure of controlled vocabulary terms. | cvTerm: [1×1 struct] |
property[].cvTerm.property[] | struct | A list of structures of controlled vocabulary term information for the property. | property: [] |
property[].cvTerm.property[].uri | string | The URI of the controlled vocabulary term. | |
property[].cvTerm.property[].vocabulary | string | The name of the controlled vocabulary to which the term belongs. | |
property[].cvTerm.uom[] | struct | A list of structures of controlled vocabulary term information for the unit of measure. | uom: [1×1 struct] |
property[].cvTerm.uom[].uri | string | The URI of the controlled vocabulary term. | uri: 'http://vocab.nerc.ac.uk/collection/P06/current/UPDB/' |
property[].cvTerm.uom[].vocabulary | string | The name of the controlled vocabulary to which the term belongs. | vocabulary: 'BODC data storage units' |
property[].description | string | The short description of the device category. | description: 'Pressure' |
property[].hasDeviceData | string | Indicates whether data products can be requested using the property code, along with a device category for a location. | hasDeviceData: 'true' |
property[].hasPropertyData | string | Indicates whether data products can be requested using the property code for a location. | hasPropertyData: 'true' |
property[].propertyCode | string | A code that uniquely identifies the property. | propertyCode: 'pressure' |
property[].propertyName | string | The name of the property. | propertyName: 'Pressure' |
property[].uom | string | The Unit of Measure used for the property measurements. | uom: 'decibar' |
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 | |||
filters | struct 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[] | list | A list of data products. | [] |
dataProduct[].dataProductCode | string | A code that uniquely identifies a data product. | dataProductCode: 'TSSD' |
dataProduct[].dataProductName | string | The name of the data product. | dataProductName: 'Time Series Scalar Data' |
dataProduct[].extension | string | The file name extension for a data product. | extension: 'json' |
dataProduct[].hasDeviceData | string | Indicates whether the data product can be requested using a device category code and a location code. | hasDeviceData: 1 |
dataProduct[].hasPropertyData | string | Indicates whether the data product can be requested using a property code and a location code or device code. | hasPropertyData: 1 |
dataProduct[].helpDocument | string | A Link URL to the Oceans 2.0 Help documentation for the specific Data Product. | helpDocument: 'https://wiki.oceannetworks.ca/display/DP/1' |
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 | |||
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',... or {'locationCode','BACAX',... |
Option | |||
maxRetries | int | The number of times to retry the service before the function aborts.
| |
downloadResultsOnly | boolean | Indicates whether the files will be downloaded or if only the URL to the file will be returned.
| |
includeMetadataFile | boolean | Indicates whether the metadata file associated with the data product request will be downloaded.
|
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 |
---|---|---|
downloadResults | list | A cell array of download results struct objects. |
downloadResults{}.url | string | The URL used to make the download request. |
downloadResults{}.message | list | A cell array of the messages that were returned from the dataProductDelivery download method when it was polled. |
downloadResults{}.status | string | The status of the download process at the request. Possible values are:
|
downloadResults{}.size | float | The actual size of the file in bytes. |
downloadResults{}.file | string | The full path of the file that was downloaded. |
downloadResults{}.index | string | The index of the file downloaded. The index can either be a number 1-* or "meta" for the data product metadata file. |
downloadResults{}.downloaded | boolean | Indicates whether the file was downloaded. If the filter downloadResultsOnly=True is used, the data product is not downloaded and the value will be False. |
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',... or {'locationCode','BACAX', ... |
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 | |||
dpRequestId | int | A unique id for a data product request. |
|
May contain | |||
compressedFileSize | int | The compressed size of the known file(s) in bytes. | compressedFileSize : 12563408 |
fileSize | int | The size of known file(s) in bytes. | fileSize : 70766230 |
numFiles | int | The number of files. | numFiles : 4 |
downloadTimes | cell array | A structure of estimated download times. | downloadTimes: {1x3 cell} 10Mbps: 7.076623 50Mbps: 1.4153247 150Mbps: 0.47177488 |
estimatedFileSize | int | The estimated file size of the generated data product. | estimatedFileSize: 8348187 |
estimatedProcessingTime | int | The estimated time, in seconds, that it will take to run the data product request. | estimatedProcessingTime: 16 |
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 | |||
requestId | int | 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'
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 | |||
runId | int | 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 | |||
fileCount | int | The actual or estimated file count, which is returned from the dataProductDelivery request method.
| 1 |
estimatedProcessingTime | int | The estimated time in seconds, to run the request on the task machine.
| 2 |
maxRetries | int | The number of times to retry the service before the function aborts.
| 10 |
downloadResultsOnly | boolean | Determines whether the files will be downloaded or if only the URL to the file will be returned.
| true |
includeMetadataFile | boolean | Indicates whether the metadata file associated with the data product request will be downloaded.
| 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 |
---|---|---|
url | string | The URL used to make the download request. |
message | list | A list of the messages that were returned from the dataProductDelivery download method when it was polled. |
status | string | The status of the download process at the request. Possible values are:
|
size | float | The actual size of the file in bytes. |
file | string | The full path of the file that was downloaded. |
index | string | The index of the file downloaded. The index can either be a number 1-* or "meta" for the data product metadata file. |
downloaded | boolean | Indicates whether the file was downloaded. If the filter downloadResultsOnly=True is used, the data product is not downloaded and the value will be False |
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 | |||
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',... or {'locationCode','BACAX', ... |
Option | |||
maxRetries | int | The number of times to retry the service before the function aborts.
| 10 |
Returns
A list of urls.
["https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=1"]
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 | |||
url | string | 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> |
file | string | The full path of the file download destination.
| 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 |
---|---|---|
url | string | The URL used to make the download request. |
file | string | The full path of the file that was downloaded. |
message | list | A list of the messages that were returned from the dataProductDelivery download method when it was polled. |
downloaded | boolean | Indicates whether the file was downloaded. |
status | string | The status of the download process at the request. Possible values are:
|
decodeJsonFromUrl()
decodeJsonFromUrl(url)
Returns a structure object from the JSON returned from a URL
Parameter | Type | Description | Example |
---|---|---|---|
Required | |||
url | string | 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.
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 | |||
filters | struct 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', ... |
Option | |||
outputFormat | string | The encoding of the response output.
| "outputFormat","Array" |
metadata | string | The amount of metadata detail included in the response output.
| "metadata","Full" |
rowLimit | integer | The maximum number of rows of scalar data that will be returned for each sensor.
| "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 |
---|---|---|
metadata | struct | A structure of metadata, if metadata='Full' input parameter is used. |
metadata.bbox | struct | A Bounding Box structure. |
metadata.bbox.maxDepth | float | The maximum depth of the instruments contributing to the results. |
metadata.bbox.maxLat | float | The maximum Latitude of bounding box of the instruments contributing to the results. |
metadata.bbox.maxLon | float | The maximum Longitude of the bounding box of the instruments contributing to the results. |
metadata.bbox.minDepth | float | The minimum Depth of the instruments contributing to the results. |
metadata.bbox.minLat | float | The minimum Latitude of bounding box of the instruments contributing to the results. |
metadata.bbox.minLon | float | The minimum Longitude of the bounding box of the instruments contributing to the results. |
sensorData | list | A list of sensor structures. |
sensorData[].acutalSamples | int | The number of samples in the data list. |
sensorData[].data | list | A list of observation structures. |
sensorData[].data[].qaqcFlag | int | The QAQC Flag for the observation. |
sensorData[].data[].sampleTime | datetime string | The recorded time of the observation.
|
sensorData[].data[].value | float | The value of the observation. |
sensorData[].sensor | string | The code of the sensor that is being observed. |
sensorData[].sensorName | string | The name of the sensor that is being observed. |
sensorData[].unitOfMeasure | string | The unit of measure of the observation. |
serviceMetadata | struct | A structure of the metadata for the service request. |
serviceMetadata.metadata | string | The requested metadata filter. |
serviceMetadata.nextDataFrom | datetime string | The begin date for next reading in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
serviceMetadata.outputFormat | string | The requested JSON output format. |
serviceMetadata.rowLimit | int | The requested row limit per sensor. |
serviceMetadata.sensors | string | A comma separated list of the requested sensors. |
serviceMetadata.totalActualSamples | int | The number of observations expected for all specified sensors. |
serviceMetadata.begin | datetime string | The begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
serviceMetadata.end | datetime string | The end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
serviceMetadata.deviceCategoryCode | string | The Device Category Code of the request. See Available Device Categories for further details. |
serviceMetadata.locationCode | string | The Location Code of the request. See Available Locations for further details. |
getDirectScalar()
getDirectScalar(filters)
Returns scalar data in the response payload that meet the criteria defined by the input filters.
Parameter | Type | Description | Example |
---|---|---|---|
Required | |||
filters | struct 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', ... 'dateFrom','2016-09-01T00:00:00.000Z', ...'dateTo','2016-09-01T08:00:00.000Z') or {'locationCode','TWDP', ... |
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 |
---|---|---|
metadata | struct | A structure of metadata, if metadata='Full' input parameter is used. |
metadata.boundingBox | struct | A Bounding Box structure. |
metadata.boundingBox.maxDepth | float | The maximum depth of the instruments contributing to the results. |
metadata.boundingBox.maxLat | float | The maximum Latitude of bounding box of the instruments contributing to the results. |
metadata.boundingBox.maxLon | float | The maximum Longitude of the bounding box of the instruments contributing to the results. |
metadata.boundingBox.minDepth | float | The minimum Depth of the instruments contributing to the results. |
metadata.boundingBox.minLat | float | The minimum Latitude of bounding box of the instruments contributing to the results. |
metadata.boundingBox.minLon | float | The minimum Longitude of the bounding box of the instruments contributing to the results. |
sensorData | list | A list of sensor structures. |
sensorData[].acutalSamples | int | The number of samples in the data list. |
sensorData[].data | struct | A structure of observation data lists. |
sensorData[].data.qaqcFlags | list of int | The QAQC Flag for the observation. |
sensorData[].data.sampleTimes | list of datetime string | The recorded time of the observation.
|
sensorData[].data.values | list of float | The value of the observation. |
sensorData[].sensorCode | list | The code of the sensor that is being observed. |
sensorData[].sensorName | string | The name of the sensor that is being observed. |
sensorData[].unitOfMeasure | string | The unit of measure of the observation. |
next | struct | A structure of the metadata for the service request. |
next.url | string | The request url. |
next.parameters | struct | A structure of the metadata for the service request. |
next.parameters.rowLimit | int | The requested row limit per sensor. |
next.parameters.token | string | The user's token. |
next.parameters.method | string | 'getByLocation'. |
next.parameters.begin | datetime string | The begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
next.parameters.end | datetime string | The end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
next.parameters.deviceCategoryCode | string | The Device Category Code of the request. See Available Device Categories for further details. |
next.parameters.locationCode | string | The Location Code of the request. See Available Locations for further details. |
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', ... or {'locationCode','TWDP', ... |
Option | |||
rowLimit | integer | The maximum number of rows of raw data that will be returned
| "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 |
---|---|---|
data | struct | |
data[].rawData | string | A raw data string representing a sample at a specific time. |
data[].sampleTime | datetime string | The recorded time of the observation.
|
metadata | struct | A structure containing metadata. |
metadata.dataMetadata | struct | A structure containing metadata about the data. |
metadata.dataMetadata.firstTimestamp | datetime string | The date time of the first record in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
metadata.dataMetadata.hasMoreDataInRange | int | 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.
|
metadata.dataMetadata.lastTimestamp | datetime string | The date time of the last record in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
metadata.dataMetadata.numberOfData | int | The number of samples in the data list. |
metadata.dataMetadata.locationName | string | The full name of the location. |
metadata.queryMetadata | struct | A structure containing metadata about the data request (query). |
metadata.queryMetadata.rowLimit | int | The requested row limit per sensor. |
metadata.queryMetadata.begin | datetime string | The begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
metadata.queryMetadata.end | datetime string | The end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
metadata.queryMetadata.deviceCategoryCode | string | The Device Category Code of the request. See Available Device Categories for further details. |
metadata.queryMetadata.locationCode | string | The Location Code of the request. See Available Locations for further details. |
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.
| struct('locationCode','TWDP', ... or {'locationCode','TWDP', ... |
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 |
---|---|---|
data | struct | |
data.readings[] | string | A raw data string representing a sample at a specific time. |
data.times[] | datetime string | The recorded time of the observation.
|
metadata.locationName | string | The full name of the location. |
next | struct | A structure containing metadata. |
next.parameters | struct | A structure containing metadata about the data. |
next.url | string | A string containing the query url. |
next.parameters.rowLimit | int | The requested row limit per sensor. |
next.parameters.begin | datetime string | The begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
next.parameters.end | datetime string | The end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
next.parameters.deviceCategoryCode | string | The Device Category Code of the request. See Available Device Categories for further details. |
next.parameters.locationCode | string | The Location Code of the request. See Available Locations for further details. |
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.
| struct('deviceCode','ICLISTENHF1293', ... or {'deviceCode','ICLISTENHF1293', ... |
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 |
---|---|---|
data | struct | |
data.readings[] | string | A raw data string representing a sample at a specific time. |
data.times[] | datetime string | The recorded time of the observation.
|
next | struct | A structure containing metadata. |
next.parameters | struct | A structure containing metadata about the data. |
next.url | string | A string containing the query url. |
next.parameters.rowLimit | int | The requested row limit per sensor. |
next.parameters.begin | datetime string | The begin date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
next.parameters.end | datetime string | The end date of the request in yyyy-MM-ddTHH:mm:ss.SSSZ format. |
next.parameters.deviceCode | string | The Device Code of the request. See Available Device Categories for further details. |
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.
| struct('locationCode','TWDP', ... or {'locationCode','TWDP', ... |
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 |
---|---|---|
data | struct |
Please report all issues with the web services, documentation, samples and client libraries to the Oceans 2.0 Help Centre