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

Discovery methods allow you to search for available locations, deployments, device categories, devices, properties, and data products. They support numerous filters and might resemble an "advanced search" function for ONC data sources.

Some usage examples are:

  • Obtain the codes required to use other API services
  • Explore what's available in a certain location or device
  • Obtain the deployment dates for a device
  • List available data products for download in a particular device or location


Note that from the ONC API perspective:

  • Locations can contain other locations (i.e. "Cambridge bay" may contain separate children locations for its underwater network and shore station)
  • Locations can contain device categories, which contain devices, which contain properties
  • You can also perform searches without considering the hierarchy mentioned above (i.e. search for locations with data on a specific property or search for all properties in a specific location)

Summary

MethodDescription

getLocations (filters)

Returns a filtered list of locationslink

getLocationHierarchy (filters)

Returns a filtered tree of locations with their childrenlink

getDeployments (filters)

Returns a filtered list of deploymentslink

getDeviceCategories (filters)

Returns a filtered list of device categorieslink

getDevices (filters)

Returns a filtered list of deviceslink

getProperties (filters)

Returns a filtered list of propertieslink

getDataProducts (filters)

Returns a filtered list of data productslink



getLocations

Returns a filtered list of locations as a list of dictionary objects. Visit locations Discovery Service for more information on filter usage.

Parameter

Type

Description

Example

filtersdictionary

A dictionary of one or more filters to refine the list of locations returned.

Valid filters:

When excluded, the method will return all locations available.

{'locationCode':'BACAX'}

Example: Print locations in North East Pacific with Hydrophones
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode': 'NEP',
    'deviceCategoryCode': 'HYDROPHONE',
    'includeChildren': 'true' # Include child locations of NEP in this search
}
result = onc.getLocations(filters)
onc.print(result)

Returns

A list of locations represented as dictionaries, with their detailed information.

Example of a returned location
[
    {
        "deployments": 50,
        "locationName": "Axis",
        "depth": 984.3076,
        "bbox": {
            "maxDepth": 987,
            "maxLat": 48.316837,
            "maxLon": -126.050125,
            "minDepth": 981,
            "minLat": 48.316517,
            "minLon": -126.05087
        },
        "description": "Canyon axis: benthic processes, biodiversity, sediment dynamics.",
        "hasDeviceData": "true",
        "lon": -126.05033,
        "locationCode": "BACAX",
        "hasPropertyData": "true",
        "lat": 48.31669,
        "dataSearchURL": "https://data.oceannetworks.ca/DataSearch?location=BACAX"
    }
]
 Detailed description of returned data [+]

Each location in the returned list is a dictionary with the following keys:

Property

Type

Description

Example
locationCodestringA code that uniquely identifies a location.

"BACAX"

locationNamestringThe full name of the location.

"Axis (POD 1)"

descriptionstringThe description of the location.

"Canyon axis: benthic processes, biodiversity, sediment dynamics."

deployments

intThe number of instrument deployments that meet the filter criteria.10
latdoubleThe average latitude of the deployments.48.47672
londoubleThe average longitude of the deployments.-123.294902
depthdoubleThe average depth of the deployments.
75
bboxdictionaryA Bounding Box dictionary (see keys below)
hasDeviceDatabooleanIndicates that data products can be requested using a device category for the location.

True

hasPropertyDatabooleanIndicates that data products can be requested using property code for the location.

True

dataSearchUrlstringThe location-specific Data Search web page URL.

"https://data.oceannetworks.ca/DataSearch?location=BACAX"


The "bbox" key holds a dictionary with the bounding box information, with the keys explained below:

Property

Type

Description

Example

maxDepth

doubleThe maximum depth of the deployments100

maxLat

doubleThe maximum Latitude of the bounding box of the deployments48.476740

maxLon

doubleThe maximum Longitude of the bounding box of the deployments-123.294904

minDepth

doubleThe minimum Depth of the deployments50

minLat

doubleThe minimum Latitude of the bounding box of the deployments48.47670

minLon

doubleThe minimum Longitude of the bounding box of the deployments-123.294900



getLocationHierarchy

Returns a hierarchical tree of locations whose root is defined by the location code provided as filter.

Parameter

Type

Description

Example

filtersdictionary

A dictionary with the key locationCode which specifies the base location from which children locations will be obtained.

If excluded, a tree with all locations is returned.

{'locationCode':'BACAX'}

Example - Print children of location with code STR01
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = { 'locationCode': 'STR01' }
result = onc.getLocationHierarchy(filters)
onc.print(result)

Returns

A list of location objects.

Example of a returned location with 2 children
[
    {
        "locationName": "Neutrino Project Mooring 01 (Yellow)",
        "description": "TBD",
        "hasDeviceData": true,
        "locationCode": "STR01",
        "hasPropertyData": false,
        "children": [
            {
                "locationName": "POCAM 110 mab",
                "children": null,
                "description": "",
                "hasDeviceData": "true",
                "locationCode": "STR01.PO1",
                "hasPropertyData": "false"
            },
            {
                "locationName": "POCAM 50 mab",
                "children": null,
                "description": "",
                "hasDeviceData": "true",
                "locationCode": "STR01.PO2",
                "hasPropertyData": "false"
            }
        ]
    }
]

 Detailed description of returned data [+]

Returns a list with the root location as a dictionary, which includes the key "children" with a list of children locations as dictionaries with the same structure (empty when no children are found). Children are included recursively.

Each location returned is a dictionary with the following keys:

Property

Type

Description

Example
locationCodestringA code that uniquely identifies a location.

"locationCode":"BACAX"

locationNamestringThe full name of the location.

"locationName": "Axis (POD 1)"

descriptionstringThe description of the location.

"description":"Canyon axis: benthic processes, biodiversity, sediment dynamics."

hasDeviceDatabooleanIndicates that data products can be requested using a device category for the location.

True

hasPropertyDatabooleanIndicates that data products can be requested using property code for the location.

True

childrenlistA list of location dictionaries that are the children of this location dictionary.

"children" : null



getDeployments

Returns a filtered list of device deployments as a list of dictionary objects. Visit Deployments Discovery Service for more information on filter usage.

Parameter

Type

Description

Example

filtersdictionary

A dictionary of one or more filters to refine the list of device deployments returned.

Valid filters:

When excluded, the method will return all device deployments.

{'deviceCode':'NORTEKADCP9917'}

Example - Get all deployments for a device
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'deviceCode': 'NORTEKADCP9917'
}
result = onc.getDeployments(filters)
onc.print(result)

Returns

A list of deployment objects.

Example of a returned deployment
[
    {
        "deviceCode": "NORTEKADCP9917",
        "locationCode": "BACWL",
        "begin": "2012-05-31T20:46:05.000Z",
        "end": "2014-05-10T01:40:00.000Z",
        "hasDeviceData": true,
        "lat": 48.311743,
        "lon": -126.065378,
        "depth": 860.0,
        "heading": null,
        "pitch": null,
        "roll": null
    }
]
 Detailed description of returned data [+]

Each deployment in the returned list is a dictionary with the following keys:

Property

Type

Description

Example

locationCodestringThe locationCode for the deployment location.

"BACAX"

deviceCodestringThe deviceCode for the deployed device.

"SBECTD19p6813"

beginstring

The beginning datetime string of the deployment (UTC).

"2010-07-27T00:00:00.000Z"

endstring

The ending datetime string of the deployment (UTC).

If this deployment is still active, the end value is null.

"2016-08-01T00:00:00.000Z"

hasDeviceData

booleanIndicates that data products can be requested using a device category code for the deployment.

True

depthdoubleThe depth of the device deployment.

982

latdouble

The latitude of the device deployment.

48.31658

londoubleThe longitude of the device deployment.

-126.0508

headingdoubleThe heading of the device deployment.

244

pitchdoubleThe pitch of the device deployment (if available).

null

rolldoubleThe roll of the device deployment (if available).

null



getDeviceCategories

Returns a filtered list of locations as a list of dictionary objects. Visit DeviceCategories Discovery Service for more information on filter usage.

Parameter

Type

Description

Example

filtersdictionary

A dictionary of one or more filters to refine the list of device categories returned. 

Valid filters:

When excluded, the method will return all device categories available.

{'deviceCategoryCode':'HYDROPHONE'}

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

filters = { 'locationCode': 'NCBC' }
result = onc.getDeviceCategories(filters)
onc.print(result)

Returns

A list of device categories represented as dictionaries, with their detailed information.

Example of a returned device category
 [
   {
      "deviceCategoryCode": "CTD",
      "deviceCategoryName": "CTD",
      "description": "Conductivity Temperature (and Depth Sensor)",
      "longDescription": " Conductivity Temperature Depth (CTD) is an abbreviated name for an (...)",
      "hasDeviceData": "true",
      "cvTerm": {
         "deviceCategory": [
            {
               "uri": "http://vocab.nerc.ac.uk/collection/L05/current/130/",
               "vocabulary": "SeaDataNet device categories"
            }
         ]
      }
   }
]
 Detailed description of returned data [+]

Each device category in the returned list is a dictionary with the following keys:

Key

Type

Description

Example
deviceCategoryCodestringA code to uniquely identify a device category.

"CTD"

deviceCategoryNamestringThe name of the device category.

"CTD"

descriptionstringThe short description of the device category.

"Conductivity Temperature (and Depth Sensor)"

longDescriptionstringThe long description of the device category.

" an instrument package that contains sensors (...)"

hasDeviceDatabooleanIndicates that data products can be requested using the device category for a location.

True

cvTermdictionaryA dictionary of controlled vocabulary terms (see below).

{ }


The "cvTerm" key holds a dictionary that describes the vocabulary term associated with this result (includying a URL with more information). This dictionary has the following keys:

Key

Type

Description

Example

deviceCategory

listA list of dictionaries of controlled vocabulary term information for the device category.

[ { } ]

deviceCategory[].uri

stringThe URI of the controlled vocabulary term.

"http://vocab.nerc.ac.uk/collection/L05/current/130/"

deviceCategory[].vocabulary

stringThe name of the controlled vocabulary to which the term belongs.

"SeaDataNet device categories"



getDevices

Returns a filtered list of devices as a list of dictionary objects. Visit devices Discovery Service for more information on filter usage.

Parameter

Type

Description

Example

filtersdictionary

A dictionary of one or more filters to refine the list of devices returned.

Valid filters:

When excluded, all devices are returned.

{'deviceCode':'NORTEKADCP9917'}

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

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

Returns

A list of devices represented as dictionaries, with their detailed information.

Example of a returned device
[
   {
      "deviceCode": "BC_POD1_AD2M",
      "deviceId": 11302,
      "deviceName": "Nortek Aquadopp HR-Profiler 2965",
      "deviceLink": "https://data.oceannetworks.ca/DeviceListing?DeviceId=11302",
      "cvTerm": {
         "device": [
            {
               "uri": "http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/",
               "vocabulary": "SeaVoX Device Catalogue"
            }
         ]
      },
      "dataRating": [
         {
            "dateFrom": "2008-11-01T00:00:00.000Z",
            "dateTo": "2010-05-27T19:27:04.000Z",
            "samplePeriod": 1,
            "sampleSize": 1
         },
         {
            "dateFrom": "2010-05-27T19:27:04.000Z",
            "dateTo": "None",
            "samplePeriod": 10,
            "sampleSize": 1
         }
      ]
   }
]
 Detailed description of returned data [+]

Each device returned is a dictionary with the following keys:

Key

Type

Description

Example
deviceCodestringA code that unquely identifes a device.

"BC_POD1_AD2M"

deviceIdintA numeric id that uniquely identifies a device.

11302

deviceNamestringThe name of the device.

"Nortek Aquadopp HR-Profiler 2965"

deviceLinkstringThe URL link to the Devices Listing page for the specific device.

"https://data.oceannetworks.ca/DeviceListing?DeviceId=11302"

cvTermdictionaryA dictionary of controlled vocabulary terms (see below).

{}

dataRatinglistA list of data ratings dictionaries (see below).

[]


The "cvTerm" key holds a dictionary that describes the vocabulary term associated with this result (includying a URL with more information). This dictionary has the following keys:

Key

Type

Description

Example

device

listA list of dictionaries of controlled vocabulary term information for the device.

[
  {
    "uri": "http://vocab.nerc.ac.uk/collection/L22/cur(...)",
    "vocabulary": "SeaVoX Device Catalogue"
  }
]

device[].uri

stringThe URI of the controlled vocabulary term.

"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"

device[].vocabulary

stringThe name of the controlled vocabulary to which the term belongs.

"SeaVoX Device Catalogue"


The "dataRating" key holds a list of dictionaries, each with a data rating for this device. Each element on this list holds the following keys:

Key

Type

Description

Example

dateFrom

string

The starting datetime (UTC) for a data rating.

"2008-11-01T00:00:00.000Z"

dateTo

string

The ending datetime (UTC) for a data rating.

"2010-05-27T19:27:04.000Z"

samplePeriod

doubleThe sample period, in seconds, for the data rating.

1

sampleSize

intThe size of the data sample for the data rating.

1



getProperties

Returns a filtered list of properties as a list of dictionary objects. Visit Properties Discovery Service for more information on filter usage.

Parameter

Type

Description

Example

filtersdictionary

A dictionary of one or more filters to refine the list of properties returned.

Valid filters:

When excluded, the method will return all properties available.

{'propertyCode':'seawatertemperature'}

Example - Get all properties available for a specific device
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = { 'deviceCode': 'BC_POD1_AD2M' }
result = onc.getProperties(filters)
onc.print(result)

Returns

A list of properties represented as dictionaries, with their detailed information.

Example of a property returned
[
    {
        "propertyCode": "soundspeed",
        "propertyName": "Sound Speed",
        "description": "Sound Speed: sound velocity sensor",
        "uom": "m/s",
        "hasDeviceData": true,
        "hasPropertyData": false,
        "cvTerm": {
            "property": [],
            "uom": [
                {
                    "uri": "http://vocab.nerc.ac.uk/collection/P06/current/UVAA/",
                    "vocabulary": "BODC data storage units"
                }
            ]
        }
    }
]
 Detailed description of returned data [+]

Each property in the returned list is a dictionary with the following keys:

Key

Type

Description

Example
propertyCodestringA code that uniquely identifies the property.

"pressure"

propertyNamestringThe name of the property.

"Pressure"

descriptionstringThe short description of the device category.

"Pressure"

uomstringThe Unit of Measure used for property measurements.

"decibar"

hasDeviceDatabooleanIndicates that data products can be requested using the property code, along with a device category for a location.

True

hasPropertyDatabooleanIndicates that data products can be requested using the property code for a location.

True

cvTermdictionaryA dictionary of controlled vocabulary terms (see below).

{ }


The "cvTerm" key holds a dictionary that describes the vocabulary term associated with this result (includying a URL with more information). This dictionary has the following keys:

Key

Type

Description

Example

property

listA list of dictionaries of controlled vocabulary term information for the property.

[
  {
    "uri": "http://vocab.nerc.ac.uk/collection/(...)",
    "vocabulary": "SeaVoX Device Catalogue"
  }
]

property[].uri

stringThe URI of the controlled vocabulary term.

"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"

property[].vocabulary

stringThe name of the controlled vocabulary to which the term belongs.

"SeaVoX Device Catalogue"

uom

listA list of dictionaries of controlled vocabulary term information for the unit of measure.

[
  {
    "uri": "http://vocab.nerc.ac.uk/collection/(...)",
    "vocabulary": "BODC data storage units"
  }
]

uom[].uri

stringThe Uri of the controlled vocabulary term.

"http://vocab.nerc.ac.uk/collection/P06/current/UPDB"

uom[].vocabulary

stringThe name of the controlled vocabulary to which the term belongs.

"BODC data storage units"




getDataProducts

Returns a filtered list of available data products as a list of dictionary objects. Visit DataProducts Discovery Service for more information on filter usage.

Data products can be downloaded using the methods for Delivery Services (requires the data product's code and extension).

Parameter

Type

Description

Example

filtersdictionary

A dictionary of one or more filters to refine the list of data products returned.

Valid filters:

When excluded, the method will return all data products available.

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

Example - Get data products with .mat extension in a location
from onc.onc import ONC
onc = ONC('YOUR_TOKEN_HERE')

filters = {
    'locationCode': 'PHYD',
    'extension': 'mat'
}
result = onc.getDataProducts(filters)
onc.print(result)

Returns

A list of data product descriptions represented as dictionaries, with their detailed information.

Example of a returned data product description
[
   {
      "dataProductCode": "TSSD",
      "dataProductName": "Time Series Scalar Data",
      "extension": "json",
      "hasDeviceData": true,
      "hasPropertyData": true,
      "helpDocument": "https://wiki.oceannetworks.ca/display/DP/1"
   }
]
 Detailed description of returned data [+]

Each data product description in the returned list is a dictionary with the following keys:

Property

Type

Description

Example
dataProductCodestringA code that uniquely identifies a data product.

"TSSD" 

dataProductNamestringThe name of the data product.

"Time Series Scalar Data"

extensionstringThe file name extension for a data product.

"json"

hasDeviceDatabooleanIndicates that the data product can be requested using a device category code and a location code.

True

hasPropertyDatabooleanIndicates that the data product can be requested using a property code and a location code or device code.

True

helpDocumentstringA Link URL to the Oceans 2.0 Help documentation for the specific Data Product.

"https://wiki.oceannetworks.ca/display/DP/1"

  • No labels