<script src="https://wiki.oceannetworks.ca/download/attachments/75170291/docs-client-libraries.js"></script>

This page contains common usage examples of client library methods that fit common use cases. The examples work with the latest client library version available.

Click "> Expand source" to display each code example.

Discovery examples

1.1. Get all locations in North East Pacific with hydrophones deployed
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

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


Link to this example

1.2. Get deployments for a device
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'deviceCode': 'WLFLNTU1087'    # WET Labs ECO FLNTU 1087
}
deployments = onc.getDeployments(filters)
onc.print(deployments)


Link to this example

1.3. Get devices deployed at a location in a time range
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

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


Link to this example

1.4. Get all device categories available in a location
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

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


Link to this example

1.5. Get all properties available in a location
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

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


Link to this example

1.6. Get all data products available with MATLAB .mat extension
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'extension': 'mat'    # mat - MATLAB
}
dataProducts = onc.getDataProducts(filters)
onc.print(dataProducts)


Link to this example

Data product download examples

2.1. Download a PNG plot of data from a CTD
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode': 'BIIP',
    'deviceCategoryCode': 'CTD',
    'dataProductCode': 'TSSP',
    'extension': 'png',
    'dateFrom': '2019-06-20T00:00:00.000Z',
    'dateTo': '2019-06-20T00:30:00.000Z',
    'dpo_qualityControl': '1',
    'dpo_resample': 'none'
}
result = onc.orderDataProduct(filters, includeMetadataFile=False)
onc.print(result)


Link to this example

2.2. Download time series readings from a device in CSV format
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    '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
}
results = onc.orderDataProduct(filters)
onc.print(results)


Link to this example

2.3. Download 6 months of hydrophone files, 1 hour at a time
# If your data is in the ONC archive, the archive files example 7
# might be noticeably faster for downloading files

from datetime import datetime, timedelta
from dateutil.parser import parse
from onc.onc import ONC

onc = ONC('YOUR_TOKEN')

# start and end date
dateFrom = parse('2019-01-01T00:00:00.000Z')
dateTo = parse('2019-06-01T00:00:00.000Z')

# time to add to dateFrom
step = timedelta(hours=1)

# use a loop to download 1 hour at a time
while dateFrom < dateTo:
    txtDate = dateFrom.strftime("%Y-%m-%dT%H:%M:%S.000Z")
    print("\nDownloading data from: {:s}\n".format(txtDate))

    filters = {
        'dataProductCode' : 'AD',
        'locationCode' : 'BACND',
        'deviceCategoryCode': 'HYDROPHONE',
        'dateFrom' : txtDate,
        'dateTo' : 'PT1H',
        'extension' : 'wav',
        'dpo_hydrophoneDataDiversionMode': 'OD'
    }
    result = onc.orderDataProduct(filters, includeMetadataFile=False)
    dateFrom += step

print("\nFinished!")
% If your data is in the ONC archive, the archive files example 7
% might be noticeably faster for downloading files

onc = ONC('YOUR_TOKEN')

% start and end date
dateFrom = datenum('2019-01-01T00:00:00.000Z','yyyy-mm-ddTHH:MM:SS.FFFZ');
dateTo = datenum('2019-06-01T00:00:00.000Z','yyyy-mm-ddTHH:MM:SS.FFFZ');

% time to add to dateFrom
step = hours(1);

% use a loop to download 1 hour at a time
while dateFrom < dateTo
    txtDate = datestr(dateFrom,'yyyy-mm-ddTHH:MM:SS.FFFZ');
    disp(['Downloading data from: ',txtDate]);
    filters = {
        'dataProductCode' , 'AD'
        'locationCode' , 'BACND'
        'deviceCategoryCode', 'HYDROPHONE'
        'dateFrom' , txtDate
        'dateTo' , 'PT1H'
        'extension' , 'wav'
        'dpo_hydrophoneDataDiversionMode', 'OD'
    };
    result = onc.orderDataProduct(filters, 'includeMetadataFile', false);
    dateFrom = dateFrom + step;
end

disp("Finished!");
# If your data is in the ONC archive, the archive files example 7
# might be noticeably faster for downloading files

onc = ONC('YOUR_TOKEN')
# start and end date
dateFrom = parse('2019-01-01T00:00:00.000Z')
dateTo = parse('2019-06-01T00:00:00.000Z')

# time to add to dateFrom
step = timedelta(hours=1)

# use a loop to download 1 hour at a time
while dateFrom < dateTo:
    txtDate = dateFrom.strftime("%Y-%m-%dT%H:%M:%S.000Z")

    print("\nDownloading data from: {:s}\n".format(txtDate))
    filters <- list(
        'dataProductCode' = 'AD',
        'locationCode' = 'BACND',
        'deviceCategoryCode' = 'HYDROPHONE',
        'dateFrom' : txtDate,
        'dateTo' = 'PT1H',
        'extension' = 'wav',
        'dpo_hydrophoneDataDiversionMode' = 'OD'
    )
    result = onc.orderDataProduct(filters, includeMetadataFile=False)
    dateFrom += step

print("\nFinished!")


Link to this example

Near real-time data examples

3.1. Get the last reading available from a device in a location
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode': 'TWDP',
    'deviceCategoryCode':'TSG',
    'rowLimit': '1',
    'getLatest': 'true'
}
result = onc.getDirectByLocation(filters)
onc.print(result)


Link to this example

3.2. Get 1 minute of time-series readings from a a device in a location
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode': 'TWDP',
    'deviceCategoryCode':'TSG',
    'dateFrom':'2016-09-01T00:00:00.000Z',
    'dateTo':'2016-09-01T00:01:00.000Z'
}
result = onc.getDirectByLocation(filters)
onc.print(result)


Link to this example

3.3. Get 10 seconds of readings from a specific device
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

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


Link to this example

3.4. Get the last raw, unprocessed instrument reading from a device
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode': 'IONA',
    'deviceCategoryCode': 'AISRECEIVER',
    'rowLimit': '1',
    'getLatest': 'true'
}
result = onc.getDirectRawByLocation(filters)
onc.print(result)


Link to this example

3.5. Get 10 seconds of raw CTD readings from a location
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode':'BACAX',
    'deviceCategoryCode':'CTD',
    'dateFrom':'2017-05-23T00:00:00.000Z',
    'dateTo':'2017-05-23T00:00:10.000Z'
}
result = onc.getDirectRawByLocation(filters)
onc.print(result)


Link to this example

Archived file download examples

4.1. Get a list of ".ruv" archived files available from a radar in 24 hours
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode': 'VION',
    'deviceCategoryCode': 'OCEANOGRAPHICRADAR',
    'extension': 'ruv',
    'dateFrom': '2018-11-07T00:00:00.000Z',
    'dateTo': '2018-11-08T00:00:00.000Z'
}
results = onc.getListByLocation(filters)
onc.print(results)


Link to this example

4.2. Get a list of all archived files available in a device in one day
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
'deviceCode':'RDIADCP600WH25471',    # AML CTD Metrec X 50348 in Burrard Inlet
'dateFrom': '2019-06-07T00:00:00.000Z',
'dateTo': '2019-06-08T00:00:00.000Z'
}
results = onc.getListByDevice(filters)
onc.print(results)


Link to this example

4.3. Download a file by its filename
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

result = onc.getFile('BC_POD2_JB_20181107T000000.000Z.txt')
onc.print(result)


Link to this example

4.4. List .wav files from a hydrophone in the last 2 hours
import datetime
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

# Get the current ISO8601 timestamp, without milliseconds
now = datetime.datetime.utcnow().replace(microsecond=0).isoformat() + '.000Z'

filters = {
    'locationCode': 'SEVIP',               # Strait of Georgia East
    'deviceCategoryCode': 'HYDROPHONE',    # Hydrophones
    'dateFrom': '-PT2H',                   # Minus 2 hours from dateTo
    'dateTo': now,
    'extension': 'wav'
}

# list available files
result = onc.getListByDevice(filters)
onc.print(result)


Link to this example

4.5. Download all .wav files from a hydrophone in the last 2 hours
import datetime
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

# Get the current ISO8601 timestamp, without milliseconds
now = datetime.datetime.utcnow().replace(microsecond=0).isoformat() + '.000Z'

filters = {
    'locationCode': 'SEVIP',               # Strait of Georgia East
    'deviceCategoryCode': 'HYDROPHONE',    # Hydrophones
    'dateFrom': '-PT2H',                   # Minus 2 hours from dateTo
    'dateTo': now,
    'extension': 'wav'
}

# download available files (will skip existing files)
result = onc.getDirectFiles(filters)
onc.print(result)


Link to this example

4.6. Download the latest .wav files available from a hydrophone in a loop every 2 hours
import datetime
import time
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

while True:
    # Get the current ISO8601 timestamp, without milliseconds
    now = datetime.datetime.utcnow().replace(microsecond=0).isoformat() + '.000Z'

    filters = {
        'locationCode': 'SEVIP',               # Strait of Georgia East
        'deviceCategoryCode': 'HYDROPHONE',    # Hydrophones
        'dateFrom': '-PT2H',                   # Minus 2 hours from dateTo
        'dateTo': now,
        'extension': 'wav'
    }

    # download files found, skip existing files
    result = onc.getDirectFiles(filters)

    # wait 2 hours (7200 seconds)
    time.sleep(60 * 60 * 2)


Link to this example

4.7. Download 6 months of hydrophone files, 1 hour at a time
from datetime import datetime, timedelta
from dateutil.parser import parse
from onc.onc import ONC
onc = ONC('YOUR_TOKEN')

# start and end date
dateFrom = parse('2019-01-01T00:00:00.000Z')
dateTo = parse('2019-06-01T00:00:00.000Z')

# time to add to dateFrom
step = timedelta(hours=1)

# use a loop to download 1 hour at a time
while dateFrom < dateTo:
    txtDate = dateFrom.strftime("%Y-%m-%dT%H:%M:%S.000Z")
    print("\nDownloading data from: {:s}\n".format(txtDate))

    filters = {
        'locationCode' : 'BACND',
        'deviceCategoryCode': 'HYDROPHONE',
        'dateFrom' : txtDate,
        'dateTo' : 'PT1H',
        'extension' : 'wav'
    }

    result = onc.getDirectFiles(filters)
    dateFrom += step

print("\nFinished!")


Link to this example