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

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

Requires

 

 

Requires R 3.3+

Installation

The ONC client library is an R Package that can be installed in RStudio by performing the following

 Installation instructions
  1. Download the latest version of the ONC Package.
  2. Open RStudio, select the Tools/Install Packages... menu item.
  3. Select Install from: Package Archive File (.zip: .tar.gz).
  4. Click the Browse button and navigate to the downloaded package tar.gz file.
  5. Click the Install button.



  6. The Oceans 2.0 Client Library will appear in the Packages list.

 

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=TRUE, showInfo=FALSE, outPath="c:/ONC/data", timeout=60)
Parameter
Type
Description
Example
Required   
tokenchrAll 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   
productionlogical

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
showInfological

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
outPathchr

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'
timeoutnumeric

The web service request timeout in seconds

  • Default is 60
30

 

Usage

library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

Or

library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE',production=TRUE,showInfo=TRUE,outPath="c:/ONC/Data/R")

 

Discovery methods

getLocations()

getLocations(obj,parameters)

 

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

 

Parameter
Type
Description
Example
objobjectONC class objectonc
Optional   
parameterslist()

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

list(locationCode="BACAX")

Returns

A list of location objects.

List of 1
 $ :List of 11
  ..$ deployments    : int 50
  ..$ locationName   : chr "Axis "
  ..$ depth          : num 984
  ..$ bbox           :List of 6
  .. ..$ maxDepth: num 987
  .. ..$ maxLat  : num 48.3
  .. ..$ maxLon  : num -126
  .. ..$ minDepth: num 981
  .. ..$ minLat  : num 48.3
  .. ..$ minLon  : num -126
  ..$ description    : chr "Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biod"| __truncated__
  ..$ hasDeviceData  : chr "true"
  ..$ lon            : num -126
  ..$ locationCode   : chr "BACAX"
  ..$ hasPropertyData: chr "true"
  ..$ lat            : num 48.3
  ..$ dataSearchURL  : chr "https://data.oceannetworks.ca/DataSearch?location=BACAX"
Property
Type
Description
Example
locationlistA list of location objects. 

location[]$deployments

intThe number of instrument deployments that meet the filter criteria.$deployments : num 10
location[]$locationNamestringThe full name of the location.
$locationName : chr "Axis (POD 1)"
location[]$depthdoubleThe average depth of the deployments.
$depth : num 75
location[]$bboxlistA Bounding Box list object. 
location[]$bbox$maxDepthdoubleThe maximum depth of the deployments.

 

$maxDepth : num 100

location[]$.bbox$maxLatdoubleThe maximum Latitude of bounding box of the deployments.$maxLat : num 48.476740
location[]$bbox$maxLondoubleThe maximum Longitude of the bounding box of the deployments.$maxLon : num -123.294904
location[]$bbox$minDepthdoubleThe minimum Depth of the deployments.$minDepth : num 50
location[]$bbox$minLatdoubleThe minimum Latitude of bounding box of the deployments.$minLat : num 48.47670
location[]$bbox$minLondoubleThe minimum Longitude of the bounding box of the deployments.minLon : num -123.294900
location[]$descriptionstringThe description of the location.
description : chr "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 : chr 'true'
location[]$londoubleThe average longitude of the deployments. lon : num -123.294902
location[]$locationCodestringA code that unquely identifies a location.
locationCode: chr "BACAX"
location[]$hasPropertyDatastringIndicates that data products can be requested using property code for the location.
hasPropertyData: chr "true"
location[]$latdoubleThe average latitude of the deployments.lat : num 48.47672
location[]$dataSearchUrlstringThe location specific Data Search web page URL.
dataSearchURL: chr "https://data.oceannetworks.ca/DataSearch?location=BACAX"
Example - Print all locations in North East Pacific with Hydrophones deployed
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

locations = onc.getLocations(onc, list(deviceCategoryCode="ADCP2MHZ"))

for (location in locations){
  str(location)
}

getLocationHierarchy()

getLocationHierarchy(obj,parameters)

 

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

objobjectONC class objectonc
Optional   
parameterslist()

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 list(<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.
list(locationCode="BACAX")

Returns

A list of location objects.

List of 1
 $ :List of 11
  ..$ locationName   : chr "Axis "
  ..$ children       : null
  ..$ depth          : num 984
  ..$ description    : chr "Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biod"| __truncated__
  ..$ hasDeviceData  : chr "true"
  ..$ locationCode   : chr "BACAX"
  ..$ hasPropertyData: chr "true"

Property

Type

Description

Example
locationlistA list of location objects. 
location[]$locationNamestringThe full name of the location.
$locationName : chr "Axis (POD 1)"

location[]$children

listA list of location objects that are the children of this location object.$children: null
location[]$depthdoubleThe average depth of the deployments.
$depth : num 75
location[]$descriptionstringThe description of the location.
description : chr "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 : chr 'true'
location[]$locationCodestringA code that unquely identifies a location.
locationCode: chr "BACAX"
location[]$hasPropertyDatastringIndicates that data products can be requested using property code for the location.
hasPropertyData: chr "true"
Example - Print all locations in Barkley Upper South Slope with Hydrophones deployed
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

locations = onc.getLocationHierarchy(onc, list(locationCode="BACUS"))

for (location in locations){
  str(location)
}

 

getDevices()

onc.getDevices(obj, parameters=list())

 

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

 

Parameter
Type
Description
Example
objobjectONC class objectonc
Optional   
parameterslist()

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

list(deviceCode="NORTEKADCP9917")

 

Returns

A list of device objects.

List of 1
 $ :List of 6
  ..$ cvTerm    :List of 1
  .. ..$ device:List of 1
  .. .. ..$ :List of 2
  .. .. .. ..$ uri       : chr "http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
  .. .. .. ..$ vocabulary: chr "SeaVoX Device Catalogue"
  ..$ dataRating:List of 2
  .. ..$ :List of 4
  .. .. ..$ dateFrom    : chr "2008-11-01T00:00:00.000Z"
  .. .. ..$ dateTo      : chr "2010-05-27T19:27:04.000Z"
  .. .. ..$ samplePeriod: int 1
  .. .. ..$ sampleSize  : int 1
  .. ..$ :List of 4
  .. .. ..$ dateFrom    : chr "2010-05-27T19:27:04.000Z"
  .. .. ..$ dateTo      : NULL
  .. .. ..$ samplePeriod: int 10
  .. .. ..$ sampleSize  : int 1
  ..$ deviceCode: chr "BC_POD1_AD2M"
  ..$ deviceId  : int 11302
  ..$ deviceLink: chr "https://data.oceannetworks.ca/DeviceListing?DeviceId=11302"
  ..$ deviceName: chr "Nortek Aquadopp HR-Profiler 2965"
Property
Type
Description
Example
devicelistA list of devices.
List of 1
device[]$cvTermlistA list object of controlled vocabulary terms.
$cvTerm    :List of 1
device[]$cvTerm$device[]listA list of list objects of controlled vocabulary term information for the device.
$device: List of 1
device[]$cvTerm$device[]$uristringThe URI of the controlled vocabulary term.
$uri       : chr "http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
device[]$cvTerm$device[]$vocabularystringThe name of the controlled vocabulary to which the term belongs.
$vocabulary: chr "SeaVoX Device Catalogue"
device[]$dataRating[]listA list of data ratings list objects.
$dataRating: List of 2
device[]$dataRating[]$dateFromdatetime string

The starting datetime for a data rating.

$dateTo      : chr "2010-05-27T19:27:04.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).

$dateFrom    : chr "2008-11-01T00:00:00.000Z"
device[]$dataRating[]$samplePerioddoubleThe sample period, in seconds, for the data rating.
$samplePeriod: int 1
device[]$dataRating[]$sampleSizeintThe size of the data sample for the data rating.
$sampleSize : int 1
device[]$deviceCodestringA code that unquely identifes a device.
$deviceCode: chr "BC_POD1_AD2M"
device[].deviceIdintA numeric id that uniquely identifies a device.
$deviceId  : int 11302
device[]$deviceLinkstringThe URL link to the Devices Listing page for the specific device.
$deviceLink: chr "https://data.oceannetworks.ca/DeviceListing?DeviceId=11302"
device[]$deviceNamestringThe name of the device.
$deviceName: chr "Nortek Aquadopp HR-Profiler 2965"
Example - Print all devices deployed at Barkley Canyon - Axis, between June 1, 2016 and May 31, 2017
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

devices = onc.getDevices(onc,
                         list(locationCode="BACAX", 				#BACAX - Barkley Canyon / Axis
						      dateFrom="2016-06-01T00:00:00.000Z",
						      dateTo="2017-05-31T23:59:59.999Z"))  

for (device in devices){
  str(device)
}

 

getDeployments()

getDeployments(filters={})

 

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

 

Parameter
Type
Description
Example
Optional   
filterslist()

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.

List of 10
 $ :List of 11
  ..$ begin        : chr "2016-06-14T08:58:41.000Z"
  ..$ depth        : num 982
  ..$ deviceCode   : chr "WLFLNTU1087"
  ..$ end          : NULL
  ..$ hasDeviceData: logi TRUE
  ..$ heading      : NULL
  ..$ lat          : num 48.3
  ..$ locationCode : chr "BACAX"
  ..$ lon          : num -126
  ..$ pitch        : NULL
  ..$ roll         : NULL
 $ :List of 11
  ..$ begin        : chr "2016-06-14T06:05:24.000Z"
  ..$ depth        : num 985
  ..$ deviceCode   : chr "BC_POD1_ROTSONAR"
  ..$ end          : NULL
  ..$ hasDeviceData: logi TRUE
  ..$ heading      : int 90
  ..$ lat          : num 48.3
  ..$ locationCode : chr "BACAX"
  ..$ lon          : num -126
  ..$ pitch        : NULL
  ..$ roll         : NULL
 $ :List of 11
  ..$ begin        : chr "2016-06-14T06:05:24.000Z"
  ..$ depth        : num 985
  ..$ deviceCode   : chr "NORTEKSIGNATURE550056"
  ..$ end          : NULL
  ..$ hasDeviceData: logi TRUE
  ..$ heading      : int 340
  ..$ lat          : num 48.3
  ..$ locationCode : chr "BACAX"
  ..$ lon          : num -126
  ..$ pitch        : NULL
  ..$ roll         : NULL
Property
Type
Description
Example
deployment[]  
List of 10
deployment[]$locationCodestringThe locationCode for the deployment location.
$locationCode : chr "BACAX"

deployment[]$deviceCode

stringThe deviceCode for a deployed device.
$deviceCode: chr "SBECTD19p6813"
deployment[]$begindatetime

The beginning datetime of the deployment.

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

$begin: chr "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'.

$end : chr "2016-08-01T00:00:00.000Z"

deployment[]$hasDeviceData

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

The latitude of the device deployment.

$lat : num 48.31658
deployment[]$londoubleThe longitude of the device deployment.$lon : num -126.0508
deployment[]$headingdoubleThe heading of the device deployment.$heading : num 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
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

deployments = onc.getDeployments(onc, list(locationCode='BACAX',
                                           dateFrom='2016-06-01T00:00:00.000Z',
                                           dateTo='2017-05-31T23:59:59.999Z'))
for (deployment in deployments){
  str(deployment)
}


getDeviceCategories()

onc.getDeviceCategories(obj, parameters=list())

 

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

 

Parameter
Type
Description
Example
objobjectONC class objectonc
Optional   
parameterslist()

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

list(deviceCategoryCode="HYDROPHONE")

 

Returns

A list of device category objects.

List of 1
 $ :List of 6
  ..$ cvTerm            :List of 1
  .. ..$ deviceCategory:List of 1
  .. .. ..$ :List of 2
  .. .. .. ..$ uri       : chr "http://vocab.nerc.ac.uk/collection/L05/current/130/"
  .. .. .. ..$ vocabulary: chr "SeaDataNet device categories"
  ..$ description       : chr "Conductivity Temperature (and Depth Sensor)"
  ..$ deviceCategoryCode: chr "CTD"
  ..$ deviceCategoryName: chr "CTD"
  ..$ hasDeviceData     : chr "true"
  ..$ longDescription   : chr " Conductivity Temperature Depth (CTD) is an abbreviated name for an instrument package that contains sensors for measuring the "| __truncated__
Property
Type
Description
Example
deviceCategory[]listA list of device categories.
List of 1
deviceCategory[]$cvTermlistA list object of controlled vocabulary terms.
$cvTerm:List of 1
deviceCategory[]$cvTerm$deviceCategory[]listA list of list objects of controlled vocabulary term information for the device category.
$deviceCategory:List of 1
deviceCategory[]$cvTerm$deviceCategory[]$uristringThe Uri of the controlled vocabulary term.
$uri : chr "http://vocab.nerc.ac.uk/collection/L05/current/130/"
deviceCategory[]$cvTerm$deviceCategory[]$vocabularystringThe name of the controlled vocabulary that the term belongs to.
$vocabulary : chr "SeaDataNet device categories"
deviceCategory[]$descriptionstringThe short description of the device category.
$description : chr "Conductivity Temperature (and Depth Sensor)"
deviceCategory[]$deviceCategoryCodestringA code to uniquely identify a device category.
$deviceCategoryCode: chr "CTD"
deviceCategory[]$deviceCategoryNamestringThe name of the device category.
$deviceCategoryName: chr "CTD"
deviceCategory[]$hasDeviceDatastringIndicates that data products can be requested using the device category for a location.
$hasDeviceData : chr "true"
deviceCategory[]$longDescriptionstringThe long description of the device category.
$longDescription : chr " Conductivity Temperature Depth (CTD) is an abbreviated name ..."
Example - Print all device categories available at Barkley Canyon - Upper Slope
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

deviceCategories = onc.getDeviceCategories(onc, list(locationCode="NCBC"))  #NCBC - Barkely Canyon / Upper Slope

for (deviceCategory in deviceCategories){
  str(deviceCategory)
}

 

getProperties()

onc.getProperties(obj, parameters)

 

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

 

Parameter
Type
Description
Example
objobjectONC class objectonc
Optional   
parameterslist()

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

list(propertyCode="seawatertemperature")

 

Returns

A list of property objects.

List of 1
 $ :List of 7
  ..$ cvTerm         :List of 2
  .. ..$ property: list()
  .. ..$ uom     :List of 1
  .. .. ..$ :List of 2
  .. .. .. ..$ uri       : chr "http://vocab.nerc.ac.uk/collection/P06/current/UPDB/"
  .. .. .. ..$ vocabulary: chr "BODC data storage units"
  ..$ description    : chr "Pressure"
  ..$ hasDeviceData  : chr "true"
  ..$ hasPropertyData: chr "true"
  ..$ propertyCode   : chr "pressure"
  ..$ propertyName   : chr "Pressure"
  ..$ uom            : chr "decibar"
Property
Type
Description
Example
property[]listA list of properties.
List of 1
property[]$cvTermlist()A list object of controlled vocabulary terms.
$cvTerm : List of 2
property[]$cvTerm$property[]list()A list of list objects of controlled vocabulary term information for the property.
$property : list()
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[]list()A list of list objects of controlled vocabulary term information for the unit of measure.
$uom : List of 1
property[]$cvTerm$uom[]$uristringThe URI of the controlled vocabulary term.
$uri : chr "http://vocab.nerc.ac.uk/collection/P06/current/UPDB/"
property[]$cvTerm$uom[]$vocabularystringThe name of the controlled vocabulary to which the term belongs.
$vocabulary : chr "BODC data storage units"
property[]$descriptionstringThe short description of the device category.
$description : chr "Pressure"
property[]$hasDeviceDatastringIndicates that data products can be requrested using the property code, along with a device category for a location.
$hasDeviceData : chr "true"
property[]$hasPropertyDatastringIndicates that data products can be requested using the property code for a location.
$hasPropertyData : chr "true"
property[]$propertyCodestringA code that uniquely identifies the property.
$propertyCode : chr "pressure"
property[]$propertyNamestringThe name of the property.
$propertyName : chr "Pressure"
property[]$uomstringThe Unit of Measure used for the property measurements.
$uom : chr "decibar"

 

 

Example - Print all properties that are available at Barkley Canyon - Axis
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

properties = onc.getProperties(onc, list(locationCode="BACAX"))   #BACAX - Barkley Canyon / Axis

for (property in properties){
  str(property)
}

 

getDataProducts()

onc.getDataProducts(obj, parameters=list())

 

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

 

Parameter
Type
Description
Example
objobjectONC class objectonc
Optional   
parameterslist()

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

list(dataProductCode="TSSD",
     extension="json")

 

Returns

A list of data product objects.

List of 1
 $ :List of 6
  ..$ dataProductCode: chr "TSSD"
  ..$ dataProductName: chr "Time Series Scalar Data"
  ..$ extension      : chr "json"
  ..$ hasDeviceData  : logi TRUE
  ..$ hasPropertyData: logi TRUE
  ..$ helpDocument   : chr "https://wiki.oceannetworks.ca/display/DP/1"

 

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

 

 

Example - Print all MatLab data product
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

dataProducts = onc.getDataProducts(onc, list(extension="mat"))

for (dataProduct in dataProducts){
  str(dataProduct)
}

 

Data Product Download methods

orderDataProduct()

onc.orderDataProduct(obj, filters, maxRetries=100, downloadResultsOnly=FALSE, includeMetadataFile=TRUE)

 

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   
objobjectONC class objectonc
filterslist

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

list(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   
maxRetriesnum

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

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

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 list object.
  • If excluded, the default of FALSE is used.
 
includeMetadataFilelogical

Indicates if 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

An object representing download results and run time statistics.

 $ :List of 7
  ..$ message   :List of 2
  .. ..$ : chr "Querying data: 0% of time range completed."
  .. ..$ : chr "Transferring (BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean.csv) to the FTP server"
  ..$ status    : chr "complete"
  ..$ url       : chr "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=471624"| __truncated__
  ..$ file      : chr "c:/ONC/Data/R/BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean.csv"
  ..$ index     : num 1
  ..$ size      : num 3060227
  ..$ downloaded: logi TRUE
 $ :List of 7
  ..$ message   : list()
  ..$ status    : chr "complete"
  ..$ url       : chr "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=471624"| __truncated__
  ..$ file      : chr "c:/ONC/Data/R/BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean_CSV_META.pdf"
  ..$ index     : chr "meta"
  ..$ size      : num 27498
  ..$ downloaded: logi TRUE

 

 

Property
Type
Description
downloadResultslist()A list of download results objects.
downloadResults[]$urlchrThe URL used to make the download request.
downloadResults[]$messagelist()A list of the messages that were returned from the dataProductDelivery download method when it was polled.
downloadResult[]$statuschr

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[]$sizenumThe actual size of the file in bytes.
downloadResults[]$filechrThe full path of the file that was downloaded.
downloadResults[]$indexchrThe index of the file downloaded. The index can either be a number 1-* or "meta" for the data product metadata file.
downloadResults[]$downloadedlogicalIndicates 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
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

results = onc.orderDataProduct(onc,
                               list(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))
            
for (result in results) {
    str(result)
}

 

requestDataProduct()
onc.requestDataProduct(obj, 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 list object 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   
objobjectONC class objectonc
filters

list

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

list(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 list() object.

 

for archived files (AD):

List of 5
 $ compressedFileSize: int 47076848
 $ downloadTimes     :List of 3
  ..$ 10Mbps : num 26.6
  ..$ 50Mbps : num 5.32
  ..$ 150Mbps: num 1.77
 $ dpRequestId       : int 2063727
 $ fileSize          : int 265833289
 $ numFiles          : int 12

 

for generated files:

List of 4
 $ disclaimer             : chr "Software Engineering is implementing estimates of processing times and file sizes for data requests. These are extremely rough "| __truncated__
 $ dpRequestId            : int 2063726
 $ estimatedFileSize      : chr "3 MB"
 $ estimatedProcessingTime: chr "5 s"

 

Property
Type
Description
Example
Always contains
dpRequestIdintA unique id for a data product request.
$ dpRequestId: int 2063727
May contain
compressedFileSizeintThe compressed size of the known file(s) in bytes.
$ compressedFileSize: int 47076848
fileSizeintThe size of known file(s) in bytes.
$ fileSize: int 265833289
numFilesintThe number of files.
$ numFiles: int 12
downloadTimeslist()A list of estimated download times.
$ downloadTimes: List of 3
..$ 10Mbps : num 26.6
..$ 50Mbps : num 5.32
..$ 150Mbps: num 1.77
estimatedFileSizechrThe estimated file size of the generated data product.
$ estimatedFileSize: chr "3 MB"
estimatedProcessingTimechrThe estimated time, in seconds, that it will take to run the data product request.
$ estimatedProcessingTime: chr "5 s"

 

runDataProduct()
onc.runDataProduct(obj, 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   
objobjectONC class objectonc
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

 

a list of runIds

List of 1
 $ :List of 2
  ..$ dpRunId: int 4716198
  ..$ status : chr "data product running"

 

Example - Run a requested data product
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

runs = onc.runDataProduct(onc, YOUR_REQUEST_ID_HERE)
 
str(runs)

 

downloadDataProduct()
onc.downloadDataProduct(obj, 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   
objobjectONC class objectonc
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
downloadResultsOnlylogical

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 list.
  • If excluded, the default of false is used.
true
includeMetadataFilelogical

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 as a vector of list() objects.

List of 2
 $ :List of 7
  ..$ message   :List of 2
  .. ..$ : chr "Querying data: 0% of time range completed."
  .. ..$ : chr "Transferring (BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean.csv) to the FTP server"
  ..$ status    : chr "complete"
  ..$ url       : chr "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=<YOUR_INDEX>"
  ..$ file      : chr "c:/ONC/Data/R/BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean.csv"
  ..$ index     : num 1
  ..$ size      : num 3060227
  ..$ downloaded: logi TRUE
 $ :List of 7
  ..$ message   : list()
  ..$ status    : chr "complete"
  ..$ url       : chr "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=<YOUR_INDEX>"
  ..$ file      : chr "c:/ONC/Data/R/BarkleyCanyon_Axis_ADCP2MHz_20160727T000005Z_20160731T235958Z-clean_CSV_META.pdf"
  ..$ index     : chr "meta"
  ..$ size      : num 27500
  ..$ downloaded: logi TRUE
Property
Type
Description
urlchrThe URL used to make the download request.
messagelistA list of the messages that were returned from the dataProductDelivery download method when it was polled.
statuschr

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.
sizenumThe actual size of the file in bytes.
filechrThe full path of the file that was downloaded.
indexchrThe index of the file downloaded. The index can either be a number 1-* or "meta" for the data product metadata file.
downloadedlogicalIndicates 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
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

results = onc.downloadDataProduct(onc,YOUR_RUN_ID_HERE, 1)
 
for (result in results)
    str(result);
end

 

getDataProductUrls()

onc.getDataProductUrls(obj, 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   
objobjectONC class objectonc
filters

 

 

 
list

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

list(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.

List of 3
 $ : chr "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=1"
 $ : chr "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=2"
 $ : chr "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=3"

 

Example - Order a data product and get a list of the download urls
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
urls = onc.getDataProductUrls(onc,
                               list(locationCode="CBYIP",
                                    deviceCategoryCode="VIDEOCAM",
                                    dataProductCode="MP4V",
                                    extension="mp4",
                                    dateFrom="2016-04-14T00:00:00.000Z",
                                    dateTo="2016-04-14T06:00:00.000Z"))
for (url in urls) {
  str(url)
}

 

downloadFile()

onc.downloadFile(obj, 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   
objobjectONC class objectonc
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 list object.

 $ url       : chr "https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN>&dpRunId=<YOUR_RUN_ID>&index=1"
 $ file      : chr "c:/ONC/Data/R/mytest.mp4"
 $ messages  : list()
 $ size      : num 27852223
 $ downloaded: logi TRUE
 $ status    : chr "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
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
url = 'https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN_HERE>&dpRunId=<YOUR_RUN_ID_HERE>&index=1';
file = 'c:/temp/myDownload.csv';

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

 

decodeJsonFromUrl()

onc.decodeJsonFromUrl(obj,url)

 

Returns an object from the JSON returned from a URL.

 

Parameter
Type
Description
Example
Required   
objobjectONC class object.onc
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>

 

Example - Get dictionary of results from json data product request
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')

urls = onc.getDataProductUrls(onc,
                              list(locationCode="BACAX",
                                  deviceCategoryCode="ADCP2MHZ",
                                  dataProductCode="TSSD",
                                  extension="json",
                                  dateFrom="2016-07-27T00:00:00.000Z",
                                  dateTo="2016-07-27T00:00:10.000Z",
                                  dpo_qualityControl=1,
                                  dpo_resample="none",
                                  dpo_dataGaps=0,
                                  dpo_jsonOutputEncoding="OM"))
for (url in urls) {
  object = onc.decodeJsonFromUrl(onc,url)
  str(object)
}

 

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   
filterslist

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

list(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 list objects 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.
Array
metadatastring

The amount of metadata detail included in the response output.

  • Minimum - Provides only basic property information. Response includes serviceMetadata list object only.
  • Full - Provides all property information. Response includes both metadata and serviceMetadata dictionaries.
  • If excluded, the default 'Minimum' is used.
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.
5000

 

Returns

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

 

List of 3
 $ metadata       :List of 8
  ..$ bbox              :List of 6
  .. ..$ maxDepth: num 3
  .. ..$ maxLat  : num 49.2
  .. ..$ maxLon  : num -124
  .. ..$ minDepth: num 3
  .. ..$ minLat  : num 49.2
  .. ..$ minLon  : num -124
  ..$ begin             : chr "2017-02-15T00:00:00.000Z"
  ..$ end               : NULL
  ..$ depth             : num 3
  ..$ deviceCategoryName: chr "TSG"
  ..$ latitude          : num 49.2
  ..$ longitude         : num -124
  ..$ locationCode      : chr "TWDP"
 $ sensorData     :List of 3
  ..$ :List of 5
  .. ..$ actualSamples: int 1
  .. ..$ data         :List of 1
  .. .. ..$ :List of 3
  .. .. .. ..$ qaqcFlag  : int 1
  .. .. .. ..$ sampleTime: chr "2017-08-15T21:34:43.677Z"
  .. .. .. ..$ value     : num 2.98
  .. ..$ sensor       : chr "Conductivity"
  .. ..$ sensorName   : chr "Conductivity"
  .. ..$ unitOfMeasure: chr "S/m"
  ..$ :List of 5
  .. ..$ actualSamples: int 1
  .. ..$ data         :List of 1
  .. .. ..$ :List of 3
  .. .. .. ..$ qaqcFlag  : int 1
  .. .. .. ..$ sampleTime: chr "2017-08-15T21:34:43.677Z"
  .. .. .. ..$ value     : num 22
  .. ..$ sensor       : chr "salinity"
  .. ..$ sensorName   : chr "Practical Salinity"
  .. ..$ unitOfMeasure: chr "psu"
  ..$ :List of 5
  .. ..$ actualSamples: int 1
  .. ..$ data         :List of 1
  .. .. ..$ :List of 3
  .. .. .. ..$ qaqcFlag  : int 1
  .. .. .. ..$ sampleTime: chr "2017-08-15T21:34:42.677Z"
  .. .. .. ..$ value     : num 17.5
  .. ..$ sensor       : chr "temperature"
  .. ..$ sensorName   : chr "Temperature"
  .. ..$ unitOfMeasure: chr "C"
 $ serviceMetadata:List of 10
  ..$ begin             : NULL
  ..$ end               : NULL
  ..$ deviceCategoryCode: chr "TSG"
  ..$ metadata          : chr "Full"
  ..$ nextDateFrom      : NULL
  ..$ outputFormat      : chr "Object"
  ..$ rowLimit          : int 100000
  ..$ sensors           : NULL
  ..$ locationCode      : chr "TWDP"
  ..$ totalActualSamples: int 3

 

Property
Type
Description
metadatalistA list object of metadata, if metadata='Full' input parameter is used.
metadata$bboxlistA Bounding Box list object.
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 list objects.
sensorData[]$acutalSamplesintThe number of samples in the data list.
sensorData[]$datalistA list of observation list objects.
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.
serviceMetadatalistA list object of 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 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
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectScalarByStation(onc,list(locationCode='TWDP', deviceCategoryCode='TSG'))

str(result)
Example - Print 1 hour of Thermosalinograph readings from Tswwassen - Duke Point Ferry
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectScalarByStation(onc,list(locationCode='TWDP', deviceCategoryCode='TSG', begin='2016-09-01T00:00:00.000Z', 'end','2016-09-01T01:00:00.000Z'))

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

str(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   
filterslist

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 list(<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.

list(locationCode='TWDP',

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

 

Returns

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

 

List of 6
 $ boundingBox       :List of 6
  ..$ maxDepth: num 3
  ..$ maxLat  : num 49.2
  ..$ maxLon  : num -124
  ..$ minDepth: num 3
  ..$ minLat  : num 49.2
  ..$ minLon  : num -124
 $ depth             : num 3
 $ deviceCategoryCode: chr "Thermosalinograph"
 $ lat               : num 49.2
 $ locationName      : chr "Tsawwassen - Duke Point"
 $ lon               : num -124
List of 2
 $ parameters:List of 8
  ..$ metadata          : chr "Full"
  ..$ method            : chr "getByLocation"
  ..$ end               : chr "2016-09-01T00:00:10.000Z"
  ..$ rowLimit          : chr "10"
  ..$ locationCode      : chr "TWDP"
  ..$ deviceCategoryCode: chr "TSG"
  ..$ begin             : chr "2016-09-01T00:00:17.042Z"
  ..$ token             : chr "f68bc7e1-f231-481d-b32e-590c5c1e1ee8"
 $ url       : chr "https://data.oceannetworks.ca/api/scalardata?metadata=Full&method=getByLocation&end=2016-09-01T00%3A00%3A10.000Z&rowLimit=10&lo"| __truncated__
 chr "https://data.oceannetworks.ca/api/scalardata?locationCode=TWDP&deviceCategoryCode=TSG&begin=2016-09-01T00%3A00%3A00.000Z&end=20"| __truncated__
List of 3
 $ :List of 4
  ..$ data         :List of 3
  .. ..$ qaqcFlags  :List of 1
  .. .. ..$ : int 1
  .. ..$ sampleTimes:List of 1
  .. .. ..$ : chr "2016-09-01T00:00:07.037Z"
  .. ..$ values     :List of 1
  .. .. ..$ : num 3.44
  ..$ sensorCode   : NULL
  ..$ sensorName   : chr "Conductivity"
  ..$ unitOfMeasure: chr "S/m"
 $ :List of 4
  ..$ data         :List of 3
  .. ..$ qaqcFlags  :List of 1
  .. .. ..$ : int 1
  .. ..$ sampleTimes:List of 1
  .. .. ..$ : chr "2016-09-01T00:00:07.037Z"
  .. ..$ values     :List of 1
  .. .. ..$ : num 28.9
  ..$ sensorCode   : NULL
  ..$ sensorName   : chr "Practical Salinity"
  ..$ unitOfMeasure: chr "psu"
 $ :List of 4
  ..$ data         :List of 3
  .. ..$ qaqcFlags  :List of 1
  .. .. ..$ : int 1
  .. ..$ sampleTimes:List of 1
  .. .. ..$ : chr "2016-09-01T00:00:07.037Z"
  .. ..$ values     :List of 1
  .. .. ..$ : num 12.9
  ..$ sensorCode   : NULL
  ..$ sensorName   : chr "Temperature"
  ..$ unitOfMeasure: chr "C"

 

Property

Type

Description

metadatalistA list object of metadata, if metadata='Full' input parameter is used.
metadata$boundingBoxlistA Bounding Box list object.
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 list objects.
sensorData[]$acutalSamplesintThe number of samples in the data list.
sensorData[]$datalistA list of observation list objects.
sensorData[]$data$qaqcFlags[]intThe QAQC Flag for the observation.
sensorData[]$data$sampleTimes[]datetime string

The recorded time of the observation.

sensorData[]$data$values[]floatThe value of the observation.
sensorData[]$sensorCodestringThe 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.
serviceMetadatalistA list object of 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 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
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectScalar(onc,list(locationCode='TWDP', deviceCategoryCode='TSG'))

str(result)
Example - Print 1 hour of Thermosalinograph readings from Tswwassen - Duke Point Ferry
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectScalar(onc,list(locationCode='TWDP', deviceCategoryCode='TSG', dateFrom='2016-09-01T00:00:00.000Z', dateTo='2016-09-01T01:00:00.000Z'))

str(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

list

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

list(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.
5000

 

Returns

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

 

List of 2
 $ data    :List of 1
  ..$ :List of 2
  .. ..$ rawData   : chr "!AIVDM,1,1,,A,14eGnq7000G<GbfL6MvBdH9H0L2h,0*59"
  .. ..$ sampleTime: chr "2017-08-15T20:43:45.735Z"
 $ metadata:List of 2
  ..$ dataMetadata :List of 5
  .. ..$ firstTimestamp    : chr "2017-08-15T20:43:45.735Z"
  .. ..$ hasMoreDataInRange: logi TRUE
  .. ..$ lastTimestamp     : chr "2017-08-15T20:43:45.735Z"
  .. ..$ numberOfData      : int 1
  .. ..$ locationCode      : chr "Iona Shore Station"
  ..$ queryMetadata:List of 5
  .. ..$ begin             : NULL
  .. ..$ end               : NULL
  .. ..$ deviceCategoryCode: chr "AISRECEIVER"
  .. ..$ rowLimit          : int 1
  .. ..$ stationCode       : chr "IONA"

 

Property
Type
Description
datalist 
data[]$rawDatastringA raw data string representing a sample at a specific time.
data[]$sampleTimedatetime string

The recorded time of the observation.

metadatalistA list object containing metadata.
metadata$dataMetadatalistA list object 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 should 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$queryMetadatalistA list object 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
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectRawByStation(onc,list(locationCode='BACAX', deviceCategoryCode='CTD'),1)

str(result)
Example - Print the last raw instrument reading from AIS Reviever at the Underwater Listening Station at IONA
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectRawByStation(onc,list(locationCode='IONA', deviceCategoryCode='AISRECEIVER'),1)

str(result)
Example - Print 1 hour of raw CTD readings from Barkley Canyon Axis
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectRawByStation(onc,list(locationCode='BACAX', deviceCategoryCode='CTD', begin='2017-05-23T00:00:00.000Z',end='2017-05-23T01:00:00.000Z'))

str(result)

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

list

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 list(<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.

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

 

Returns

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

 

List of 2
 $ data    :List of 1
 $ metadata:List of 2
 $ next    :List of 1

 

Property

Type

Description

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

The recorded time of the observation.

nextlistA list object containing metadata.
next$parameterslistA list object containing metadata about the data.
metadata$locationNamestringThe full name of the location.
next$urlstringA string object 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
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectRawByLocation(onc,list(locationCode='BACAX', deviceCategoryCode='CTD',rowLimit=1))

str(result)
Example - Print the last raw instrument reading from AIS Reviever at the Underwater Listening Station at IONA
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectRawByLocation(onc,list(locationCode='IONA', deviceCategoryCode='AISRECEIVER',rowLimit=1))

str(result)
Example - Print 1 hour of raw CTD readings from Barkley Canyon Axis
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectRawByLocation(onc,list(locationCode='BACAX', deviceCategoryCode='CTD', dateFrom='2017-05-23T00:00:00.000Z',dateTo='2017-05-23T01:00:00.000Z'))

str(result)

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

list

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 list(<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.

list(deviceCode='SBECTD16p6002',
dateFrom='2016-09-01T00:00:00.000Z',
dateTo='2016-09-01T08:00:00.000Z')

 

Returns

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

 

List of 2
 $ data    :List of 1
 $ next    :List of 2

 

Property

Type

Description

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

The recorded time of the observation.

nextlistA list object containing metadata.
next$parameterslistA list object containing metadata about the data.
next$urlstringA string object 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
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectRawByDevice(onc,list(deviceCode='SBECTD16p6002',rowLimit=1))

str(result)
Example - Print the last raw instrument reading from AIS Reviever at the Underwater Listening Station at IONA
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectRawByDevice(onc,list(deviceCode='DIGITALYACHTAISNET1302-0097-01',rowLimit=1))

str(result)
Example - Print 1 hour of raw CTD readings from Barkley Canyon Axis
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectRawByDevice(onc,list(deviceCode='SBECTD16p6002', dateFrom='2017-05-23T00:00:00.000Z',dateTo='2017-05-23T01:00:00.000Z'))

str(result)


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

list

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 list(<filter_1>='<value_1>='<filter_2>='<value_2>',...).
  • Filters must include locationCode.
  • Filters can optionally Include dateFrom and dateTo (a date range).
  • See locations Discovery Service for more information on filter usage.

list('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

datalist 
Example - Print the last raw instrument reading from the CTD at Barkley Canyon Axis
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectFiles(list(locationCode='BACAX',deviceCategoryCode='CTD'),1);

str(result);
Example - Print the last raw instrument reading from AIS Reviever at the Underwater Listening Station at IONA
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectFiles(list(locationCode','IONA',deviceCategoryCode='AISRECEIVER'),1);

str(result);
Example - Print 1 hour of raw CTD readings from Barkley Canyon Axis
library("onc")
onc = new("onc",token='YOUR_TOKEN_HERE')
 
result = onc.getDirectFiles(list(locationCode='BACAX',deviceCategoryCode='CTD',dateFrom='2017-05-23T00:00:00.000Z',dateTo='2017-05-23T01:00:00.000Z'));

str(result);


Versions

version

Date

Description

Package

Source
1.0905/12/2018

Re-formatted the class declaration to match the new S4 class definitions and prepare for the upcoming S6 changes

Added the optional timeout parameter to the onc constructor

Added dependency on package httr

Source can be obtained by decompressing the .tar.gz package


1.08

16/04/2018

Added UserTestCase_EMP_UTC_001.py to demonstrate use of discovery services

Added UserTestCase_EMP_UTC_004.py to demonstrate use of archivefiles service

Updated getDirectFiles() for changes in archivefiles service

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

onc_1.08.tar.gzonc-1.08-source.zip
1.07

02/02/2018


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

Updated getDirectScalar*() functions for changes in scalardata service

onc_1.07.tar.gzonc-1.07-source.zip
1.06

19/01/2018


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

Added getDirectFiles() function to access archivefiles service

Added getDirectRawBy*() functions for changes in rawdata service

onc-1.06.tar.gzonc-1.06-source.zip
1.0509/28/2017

Updated orderDataProduct() function to handle estimatedProcessingTime string format

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

onc-1.05.tar.gzonc-1.5-source.zip
1.0408/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.04.tar.gzonc-1.04-source.zip
1.0308/15/2017

Added getDataProductUrls(), downloadFile(), decodeJsonFromUrl(), getDirectScalar() and getDirectRaw() functions.

onc-1.03.tar.gzonc-1.03-source.zip
1.0208/11/2017Rename 'parameters' parameter to 'filters' in all applicable ONC class functions.onc-1.02.tar.gzonc-1.02-source.zip
1.0108/03/2017Update production url from http://dmas.uvic.ca to http://data.oceannetworks.ca.onc-1.01.tar.gzonc-1.01-source.zip
1.007/25/2017Alpha version.

onc-1.0.tar.gz

onc-1.0-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.


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