View Source

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

Method	Description
`getLocations (filters)`	Returns a filtered list of locations	link
`getLocationHierarchy (filters)`	Returns a filtered tree of locations with their children	link
`getDeployments (filters)`	Returns a filtered list of deployments	link
`getDeviceCategories (filters)`	Returns a filtered list of device categories	link
`getDevices (filters)`	Returns a filtered list of devices	link
`getProperties (filters)`	Returns a filtered list of properties	link
`getDataProducts (filters)`	Returns a filtered list of data products	link

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

filters

dictionary

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

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.

[
    {
        "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"
    }
]

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

Property	Type	Description	Example
locationCode	string	A code that uniquely identifies a location.	`"BACAX"`
locationName	string	The full name of the location.	`"Axis (POD 1)"`
description	string	The description of the location.	`"Canyon axis: benthic processes, biodiversity, sediment dynamics."`
deployments	int	The number of instrument deployments that meet the filter criteria.	`10`
lat	double	The average latitude of the deployments.	`48.47672`
lon	double	The average longitude of the deployments.	`-123.294902`
depth	double	The average depth of the deployments.	`75`
bbox	dictionary	A Bounding Box dictionary (see keys below)
hasDeviceData	boolean	Indicates that data products can be requested using a device category for the location.	`True`
hasPropertyData	boolean	Indicates that data products can be requested using property code for the location.	`True`
dataSearchUrl	string	The 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	double	The maximum depth of the deployments	`100`
maxLat	double	The maximum Latitude of the bounding box of the deployments	`48.476740`
maxLon	double	The maximum Longitude of the bounding box of the deployments	`-123.294904`
minDepth	double	The minimum Depth of the deployments	`50`
minLat	double	The minimum Latitude of the bounding box of the deployments	`48.47670`
minLon	double	The 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

filters

dictionary

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

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.

[
    {
        "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"
            }
        ]
    }
]

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
locationCode	string	A code that uniquely identifies a location.	`"locationCode":"BACAX"`
locationName	string	The full name of the location.	`"locationName": "Axis (POD 1)"`
description	string	The description of the location.	`"description":"Canyon axis: benthic processes, biodiversity, sediment dynamics."`
hasDeviceData	boolean	Indicates that data products can be requested using a device category for the location.	`True`
hasPropertyData	boolean	Indicates that data products can be requested using property code for the location.	`True`
children	list	A 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

filters

dictionary

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

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.

[
    {
        "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
    }
]

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

Property	Type	Description	Example
locationCode	string	The locationCode for the deployment location.	`"BACAX"`
deviceCode	string	The deviceCode for the deployed device.	`"SBECTD19p6813"`
begin	string	The beginning datetime string of the deployment (UTC).	`"2010-07-27T00:00:00.000Z"`
end	string	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	boolean	Indicates that data products can be requested using a device category code for the deployment.	`True`
depth	double	The depth of the device deployment.	`982`
lat	double	The latitude of the device deployment.	`48.31658`
lon	double	The longitude of the device deployment.	`-126.0508`
heading	double	The heading of the device deployment.	`244`
pitch	double	The pitch of the device deployment (if available).	`null`
roll	double	The 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

filters

dictionary

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

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.

 [
   {
      "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"
            }
         ]
      }
   }
]

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

Key	Type	Description	Example
deviceCategoryCode	string	A code to uniquely identify a device category.	`"CTD"`
deviceCategoryName	string	The name of the device category.	`"CTD"`
description	string	The short description of the device category.	`"Conductivity Temperature (and Depth Sensor)"`
longDescription	string	The long description of the device category.	`"` `an instrument package that contains sensors (...)"`
hasDeviceData	boolean	Indicates that data products can be requested using the device category for a location.	`True`
cvTerm	dictionary	A 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	list	A list of dictionaries of controlled vocabulary term information for the device category.	`[ { } ]`
deviceCategory[].uri	string	The URI of the controlled vocabulary term.	`"http://vocab.nerc.ac.uk/collection/L05/current/130/"`
deviceCategory[].vocabulary	string	The 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

filters

dictionary

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

Valid filters:

When excluded, all devices are returned.

{'deviceCode':'NORTEKADCP9917'}

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.

[
   {
      "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
         }
      ]
   }
]

Each device returned is a dictionary with the following keys:

Key	Type	Description	Example
deviceCode	string	A code that unquely identifes a device.	`"BC_POD1_AD2M"`
deviceId	int	A numeric id that uniquely identifies a device.	`11302`
deviceName	string	The name of the device.	`"Nortek Aquadopp HR-Profiler 2965"`
deviceLink	string	The URL link to the Devices Listing page for the specific device.	`"https://data.oceannetworks.ca/DeviceListing?DeviceId=11302"`
cvTerm	dictionary	A dictionary of controlled vocabulary terms (see below).	`{}`
dataRating	list	A 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	list	A 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	string	The URI of the controlled vocabulary term.	`"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"`
device[].vocabulary	string	The 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	double	The sample period, in seconds, for the data rating.	`1`
sampleSize	int	The 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

filters

dictionary

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

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.

[
    {
        "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"
                }
            ]
        }
    }
]

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

Key	Type	Description	Example
propertyCode	string	A code that uniquely identifies the property.	`"pressure"`
propertyName	string	The name of the property.	`"Pressure"`
description	string	The short description of the device category.	`"Pressure"`
uom	string	The Unit of Measure used for property measurements.	`"decibar"`
hasDeviceData	boolean	Indicates that data products can be requested using the property code, along with a device category for a location.	`True`
hasPropertyData	boolean	Indicates that data products can be requested using the property code for a location.	`True`
cvTerm	dictionary	A 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	list	A list of dictionaries of controlled vocabulary term information for the property.	`[ { "uri": "http://vocab.nerc.ac.uk/collection/(...)", "vocabulary": "SeaVoX Device Catalogue" } ]`
property[].uri	string	The URI of the controlled vocabulary term.	`"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"`
property[].vocabulary	string	The name of the controlled vocabulary to which the term belongs.	`"SeaVoX Device Catalogue"`
uom	list	A 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	string	The Uri of the controlled vocabulary term.	`"http://vocab.nerc.ac.uk/collection/P06/current/UPDB"`
uom[].vocabulary	string	The 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

filters

dictionary

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

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.

[
   {
      "dataProductCode": "TSSD",
      "dataProductName": "Time Series Scalar Data",
      "extension": "json",
      "hasDeviceData": true,
      "hasPropertyData": true,
      "helpDocument": "https://wiki.oceannetworks.ca/display/DP/1"
   }
]

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

Property	Type	Description	Example
dataProductCode	string	A code that uniquely identifies a data product.	`"TSSD"`
dataProductName	string	The name of the data product.	`"Time Series Scalar Data"`
extension	string	The file name extension for a data product.	`"json"`
hasDeviceData	boolean	Indicates that the data product can be requested using a device category code and a location code.	`True`
hasPropertyData	boolean	Indicates that the data product can be requested using a property code and a location code or device code.	`True`
helpDocument	string	A Link URL to the Oceans 2.0 Help documentation for the specific Data Product.	`"https://wiki.oceannetworks.ca/display/DP/1"`