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

After installing a client library, the ONC class will be made available to your scripts. This class includes functionality you can use to consume our discovery, data product download, archive file download and near real-time data services, to explore and download our data.

  • We provide documentation for Python, MATLAB and R. Please select your language at the top of the screen.
  • All code examples in the documentation require you to replace 'YOUR_TOKEN_HERE' with a token of your own.

1. Obtaining a token

All requests require a unique Oceans 3.0 API token that authorizes you to access our data. If you don't have a token yet, generate it as follows:

  1. Register for an Oceans 3.0 account at https://data.oceannetworks.ca/Registration
  2. Log-in into your account at https://data.oceannetworks.ca by clicking the Login link
  3. Click the Profile link to access your account profile
  4. Access the Web Services API tab and click "Generate Token"

If you forget your token, you can always find it again in your Oceans 3.0 account profile.

2. Searching with discovery methods

To download ONC data, you need to specify the type of data you require and where in particular (i.e. location, device) it originates from.

In the Oceans 3.0 API, there's a unique code that identifies every location, device, property, data product type, etc. You include these codes in a group of filters that determine the data you're interested in.

Discovery methods allow you to explore the hierarchy of the ONC database to obtain the codes for your filters (they work like a "search" function).

The example below uses the getLocations method to search for locations that include "Burrard" in their name (i.e. "Burrard Inlet"):

Code exampleResult





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

filters = {'locationName': 'Burrard'}
result = onc.getLocations(filters)

onc.print(result)


[
  {
    "deployments": 10,
    "locationName": "Burrard Inlet",
    "depth": 30.4,
    "bbox": { (...) },
    "description": "",
    "hasDeviceData": true,
    "lon": -123.110356,
    "locationCode": "JDATF",
    "hasPropertyData": false,
    "lat": 49.300866,
    "dataSearchURL": "data.oceannetworks.ca/DataSearch?location=JDATF"
  }
]



Use the ^onc.print() | onc.print() | onc$print()  method to print any result returned by the client library in a format easier to read.

You can find more information on this function at the Utility methods documentation.

The previous code prints a list with a location that matches the search filters provided; this location includes a "locationCode" that can be used to continue searching "inside" it, as in the following example:


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

# what device categories are available here?
result = onc.getDeviceCategories({'locationCode': 'BIIP'})
onc.print(result)

# what data product types are available for the CTD category at this location?
result = onc.getDataProducts({'locationCode': 'BIIP', 'deviceCategoryCode': 'CTD'})
onc.print(result)


You can continue reading about Discovery methods or review Code examples.

3. Downloading data products

Once you determine the exact dictionary of filters that identifies the data you are interested in, there are multiple methods to download it.

One method is to request the ONC servers to generate a custom data product with the data; This is done through the data product download methods.

The following example downloads two PNG files with plots for 30 seconds of data from a CTD in Campbell River:



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'
};
onc.orderDataProduct(filters, 'includeMetadataFile', false);
onc.print(result);





Request Id: 3225809
Estimated File Size: 209 kB
Estimated Processing Time: 20 s

Downloading data product files with runId 9556053...

 Running...
 Running... getting data for time segment 1 of 1...
 Running... writing data products, time range 1 of 1...

Total run time: 2 seconds
Total download Time: 0.135 seconds
2 files (249.4 kB) downloaded


The filters above include codes for location, deviceCategory and dataProduct, as well as the file extension and a time interval (in UTC). They also include a couple of filters to configure this specific data product type (starting with the "dpo_" prefix) which can be obtained from the Data Product Options documentation. You can download more than 120 different types of data products including audio & video.

You can continue reading about Data Product Download methods or review Code examples.

4. Obtaining sensor readings in (near) real-time

Another method to obtain ONC data is by directly obtaining time-series of sensor readings (available as soon as they reach our database).

In the following example, we obtain 5 seconds of conductivity readings from the CTD at Burrard Inlet:


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

filters = {
'locationCode': 'BIIP',
'deviceCategoryCode': 'CTD',
'propertyCode': 'conductivity',
'dateFrom': '2019-06-20T00:00:00.000Z',
'dateTo': '2019-06-20T00:00:05.000Z'
}
result = onc.getDirectByLocation(filters)

onc.print(result)



"sensorData": [
  {
    "data": {
      "qaqcFlags": [1,1,1,1,1],
      "sampleTimes": [
        "2019-06-20T00:00:00.060Z",
        "2019-06-20T00:00:01.060Z",
        "2019-06-20T00:00:02.060Z",
        "2019-06-20T00:00:03.060Z",
        "2019-06-20T00:00:04.060Z"
      ],
      "values": [3.3043, 3.3045, 3.3047, 3.3044, 3.3046]
   },
   "sensorName": "Conductivity",
   "unitOfMeasure": "S/m"
   (...)


The result includes matching lists of "values" and "sampleTimes" (increases performance for long time ranges). We also use the property code "conductivity" to limit results to a specific property available in this CTD.

You can continue reading about Near real-time data access methods or review Code examples.

5. Downloading archived files

ONC scripts auto-generate and archive data products of different types at set time intervals. You can directly download these data product files from our files archive, as long as you know their unique filename.

In the following example, we get the list of archived files available for a camera at Ridley Island (in a certain time span), and download one of the files:


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

# get the list of files
filters = {
'locationCode': 'RISS',
'deviceCategoryCode': 'VIDEOCAM',
'dateFrom': '2016-12-01T00:00:00.000Z',
'dateTo' : '2016-12-01T00:05:00.000Z'
}
result = onc.getListByLocation(filters, allPages=True)
onc.print(result)

# download one of the files
onc.getFile('AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg')



{
  "next": null,
  "queryUrl": "https://data.oceannetworks.ca/(...)",
  "files": [
     "AXISQ6044PTZACCC8E334C53_20161201T000000.000Z.an",
     "AXISQ6044PTZACCC8E334C53_20161201T000000.000Z.mp4",
     "AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg"
  ]
}


You can use the method "getFile()" as above to download individual files or the method "getDirectFiles()" to download all the files that match your filters.

You can continue reading about Archive file download methods or review Code examples.