The ONC Python client library contains a number of classes and functions that make access to the ONC data, through the Oceans 2.0 API, quick and easy to use.

Installation

The ONC Python client library can be installed using the pip command found in the Scripts folder of your python install.

$ pip install onc

History

version	Date	Description	Package
1.0	6/9/2017	Beta version	onc-1.0.tar.gz
1.1	6/12/2016	Rename onc.dap.DAP class to onc.dap.ERDDAP	onc-1.1.tar.gz

Classes

class	import	description
onc	from onc.onc import ONC	A wrapper class for access to Oceans 2.0 API web services
sos	from onc.sos import SOS	A wrapper class for access to ONC's implementation of Sensor Observation Service (SOS)
erddap	from onc.dap import ERDDAP	A wrapper class for access to datasets published on ONC's ERDDAP (OPeNDAP) server http://qadap.onc.uvic.ca/erddap/index.html
nerc	from onc.nerc import NERC	A wrapper class for access to controlled vocabularies stored on the NERC vocabulary server http://vocab.nerc.ac.uk/

onc

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(token, production=True, showInfo=False, outPath='c:/temp')

Parameter	Type	Description	Example
Required
token	string	All Web Services require a token. This can be generated at http://dmas.uvic.ca/Profile. Click on the "Web Services" tab and click "Generate Token"	token=5ba514e8-1203-428c-8835-879c8173e387
Optional
production	boolean	Indicates if the ONC Production server URL is used for service requests. Default is True. False is intended for internal ONC testing only. All external users should use False or leave blank.	True or False
showInfo	boolean	Indicates if verbose script messages are displayed, such as request url and processing time information. Default is False. True is intended for script debugging.	True or False
outPath	string	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'

Usage

from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

Or

from onc.onc import ONC

isProduction = True
showInfo = False
outPath = 'c:/ONC/Data'
onc = ONC('YOUR_TOKEN_HERE',isProduction,showInfo,outPath)

methods

getLocations(parameters={})

Returns a list of locations, as a list of dictionary objects.

Parameter

Type

Description

Example

Optional

parameters

dictionary

A dictionary of parameters, used to filter data from the ONC devices endpoint.

If excluded, all locations are returned.
See locations Discovery Service for available parameters (filters).

{'locationCode':'BACAX'}

Example - Print all locations in North East Pacific with Hydrophones deployed

from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

locations = onc.getLocations({'locationCode':'NEP', 'deviceCategoryCode':'HYDROPHONE'}) #NEP - North East Pacific
print('Locations')

for location in locations:
    locationCode = location['locationCode']
    locationName = location['locationName']
    hasDeviceData = location['hasDeviceData']
    hasPropertyData = location['hasPropertyData']
    if (len(locationCode.split('.')) == 2):
        parentName = onc.getLocationName(locationCode.split('.')[0])
        if (parentName):
            locationName = '{} / {}'.format(parentName,locationName)
    print('  {0} - {1}'.format(locationCode,locationName))
    print('     Request data product using Device Category (Site Device): {}'.format(hasDeviceData))
    print('     Request data product using Property (Primary Sensor): {}'.format(hasPropertyData))
print('{} locations'.format(len(locations)))

getDevices(parameters={})

Returns a list of devices, as a list of dictionary objects.

Parameter

Type

Description

Example

Optional

parameters

dictionary

A dictionary of parameters, used to filter data from the ONC devices endpoint.

If excluded, all devices are returned.
See devices Discovery Service for available parameters (filters).

{'deviceCode':'NORTEKADCP9917'}

Example - Print all devices deployed at Barkley Canyon - Axis, between June 1, 2016 and May 31, 2017

from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

devices = onc.getDevices({'locationCode':'BACAX','begin':'2016-06-01T00:00:00.000Z','end':'2017-05-31T23:59:59.999Z'})  #BACAX - Barkley Canyon / Axis

print('Devices:')

for device in devices:
    deviceCode = device['deviceCode']
    deviceName = device['deviceName']
    print('  {} - {}'.format(deviceCode,deviceName))
print('{} devices'.format(len(devices)))

getDeviceCategories(parameters={})

Returns a list of deviceCategories, as a list of dictionary objects.

Parameter

Type

Description

Example

Optional

parameters

dictionary

A dictionary of parameters, used to filter data from the ONC deviceCategories endpoint.

If excluded, all device categories are returned.
See deviceCategories Discovery Service for available parameters (filters).

{'deviceCategoryCode':'HYDROPHONE'}

Example - Print all device categories available at Barkley Canyon - Upper Slope

from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

deviceCategories = onc.getDeviceCategories({'locationCode':'NCBC'})    #NCBC - Barkely Canyon / Upper Slope

print('Device Categories:')

for deviceCategory in deviceCategories:
    deviceCategoryCode = deviceCategory['deviceCategoryCode']
    deviceCategoryName = deviceCategory['deviceCategoryName']
    print('  {} - {}'.format(deviceCategoryCode,deviceCategoryName))
print('{} device categories'.format(len(deviceCategories)))

getProperties(parameters={})

Returns a list of properties, as a list of dictionary objects.

Parameter

Type

Description

Example

Optional

parameters

dictionary

A dictionary of parameters, used to filter data from the ONC properties endpoint.

If excluded, all properties are returned.
See properties Discovery Service for available parameters (filters).

{'propertyCode':'seawatertemperature'}

Example - Print all properties that are available at Barkley Canyon - Axis

from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

properties = onc.getProperties({'locationCode':'BACAX'})  #BACAX - Barkley Canyon / Axis

print('Properties:')

for prprty in properties:
    propertyCode = prprty['propertyCode']
    propertyName = prprty['propertyName']
    description = prprty['description']
    print('  {} - {} ({})'.format(propertyCode,propertyName,description))
print('{} properties'.format(len(properties)))

getDataProducts(parameters={})

Returns a list of data products as a list of dictionary objects.

Parameter

Type

Description

Example

Optional

parameters

dictionary

A dictionary of parameters, used to filter data from the ONC dataProducts endpoint.

If excluded, all data products are returned.
See dataProducts Discovery Service for available parameters (filters).

{'dataProductCode':'TSSD','extension':'json'}

Example - Print all MatLab data product

from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

dataProducts = onc.getDataProducts({'extension':'mat'}) #mat - MatLab

print('Data Products:')

for c in sorted(set([str(dp['dataProductCode']) for dp in dataProducts])):
    name = [dp['dataProductName'] for dp in dataProducts if dp['dataProductCode'] == c][0]
    print ('{} - {}'.format(c,name))
    for e in sorted(set([dp['extension'] for dp in dataProducts if dp['dataProductCode'] == c])):
        print('  {}'.format(e))
print('{} data product extensions'.format(len(dataProducts)))

orderDataProduct(parameters={})

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

Parameter

Type

Description

Example

Required

parameters

dictionary

A dictionary of parameters, used to request data as a data product from the ONC dataProductDelivery endpoint.

See locations Discovery Service, devices Discovery Service, deviceCategories Discovery Service, properties Discovery Service and dataProducts Discovery Service for available parameters (filters).

{'dataProductCode':'TSSD','extension':'json'}

Example - Download Time Series Scalar Data Product in CSV format for ADCP 2 MHZ at Barkley Canyon - Axis

from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

onc.orderDataProduct({'locationCode':'BACAX',
                        'deviceCategoryCode':'ADCP2MHZ',
                        'dataProductCode':'TSSD',
                        'extension':'csv',
                        'begin':'2016-07-27T00:00:00.000Z',
                        'end':'2016-08-01T00:00:00.000Z',
                        'dpo_qualityControl':1,
                        'dpo_resample':'none',
                        'dpo_dataGaps':0},100)

orderDataProduct(parameters={}, returnError=False)

runDataProduct(requestId)

downloadDataProduct(runId, fileCount, estimatedProcessingTime=1, maxRetries=100, downloadResultsOnly=False, includeMetadataFile=False, multiThreadMessages=False)

downloadDataProductIndex(runId, url, parameters, downloadResultsOnly, includeMetadataFile, multiThreadMessages,indx=1, fileCount=1, estimatedProcessingTime=1, maxRetries=100)

downloadFile(url, file, multiThreadMessages=False)

getJsonDataProduct(parameters, maxRetries=100)

getJsonFromUrl(url)

getDataProductUrls(parameters, maxRetries=100)

Page tree

Python Client Library

Installation

History

Classes

onc

Description

constructor

Usage

methods