onc

Subpackages

onc.util

Classes

ONC

A wrapper class for Oceans 3.0 API requests.

Package Contents

class onc.ONC(token, production: bool = True, showInfo: bool = False, outPath: str | pathlib.Path = 'output', timeout: int = 60)[source]

A wrapper class for Oceans 3.0 API requests.

All the client library’s functionality is provided as methods of this class.

Parameters:

token (str) – The ONC API token, which could be retrieved at https://data.oceannetworks.ca/Profile once logged in.
production (boolean, default True) –
Whether the ONC Production server URL is used for service requests.
- True: Use the production server.
- False: Use the internal ONC test server (reserved for ONC staff IP addresses).
showInfo (boolean, default False) –
Whether verbose script messages are displayed, such as request url and processing time information.
- True: Print all information and debug messages (intended for debugging).
- False: Only print information messages.
outPath (str | Path, default "output") – The directory that files are saved to (relative to the current directory) when downloading files. The directory will be created if it does not exist during the download.
timeout (int, default 60) – Number of seconds before a request to the API is canceled due to a timeout.

Examples

>>> from onc import ONC
>>> onc = ONC("YOUR_TOKEN_HERE")  
>>> onc = ONC("YOUR_TOKEN_HERE", showInfo=True, outPath="onc-files")  

token

showInfo

timeout

property production: bool: Return whether the test is against the Production environment or not.

property outPath: pathlib.Path

Return the resolved directory path that files are saved to.

The setter method can take either str or Path as the parameter.

discovery

delivery

realTime

archive

print(obj, filename: str = '') → None[source]

Pretty print a collection to the console or a file.

Mainly used to print the results returned by other class methods.

Parameters:

obj (Any) – Any collection, including scalar values, dictionaries and lists (i.e. those returned by other class methods)
filename (str, default "") –
The filename that is used when saving the json file. It is relative to self._out_path. The .json extension could be omitted.
- if not empty, save the output to the file.
- if empty, print the output to the console.

Examples

>>> result = onc.getLocations()  
>>> onc.print(result)  

formatUtc(dateString: str = 'now') → str[source]

Format the provided date string as an ISO8601 UTC date string.

The ISO8601 UTC date format is required by the API.

Parameters:

dateString (str, default "now") –

A string that represents a date & time in any of the formats described in http://labix.org/python-dateutil#head-c0e81a473b647dfa787dc11e8c69557ec2c3ecd2. Examples are:

”2016-12-04”
”2016-Dec-04, 12:00:00”
”2016 Dec 04 03:00 PM”
”now” (returns current UTC date & time)

Examples

>>> onc.formatUtc("2019-Sept-09 03:00 PM")
'2019-09-09T15:00:00.000Z'

getLocations(filters: dict | None = None)[source]

Return locations.

The API endpoint is /locations.

Return a list of location names and location codes.

See https://data.oceannetworks.ca/OpenAPI#get-/locations for usage and available query string parameters.

Parameters:

filters (dict, optional) –

Query string parameters in the API request. Return all locations available if None.

Supported parameters are:

locationCode
deviceCategoryCode
propertyCode
dataProductCode
dateFrom
dateTo
locationName
deviceCode
includeChildren

Returns:

API response. Each location returned in the list is a dict with the following structure.

deployments: int
locationName: str
depth: float
bbox: dict
- bbox.maxDepth: float
- bbox.maxLat: float
- bbox.maxLon: float
- bbox.minDepth: float
- bbox.minLat: float
- bbox.minLon: float
description: str
hasDeviceData: bool
lon: float
locationCode: str
hasPropertyData: bool
lat: float
dataSearchURL: str

Check https://wiki.oceannetworks.ca/display/O2A/Glossary+of+Terms for more information.

Return type:

list of dict

Examples

>>> params = {
...     "locationCode": "FGPD",
...     "dateFrom": "2005-09-17T00:00:00.000Z",
...     "dateTo": "2020-09-17T13:00:00.000Z",
... }  
>>> onc.getLocations(params)  
[
    {
        "deployments": 46,
        "locationName": "Folger Deep",
        "depth": 96.569761,
        "bbox": {
            "maxDepth": 105.0,
            "maxLat": 48.814029,
            "maxLon": -125.274604,
            "minDepth": 94.0,
            "minLat": 48.813667,
            "minLon": -125.28195,
        },
        "description": " Folger Deep is a deep location in Folger Passage near a pillar-like seamount, where productivity and marine mammals are observed.",
        "hasDeviceData": True,
        "lon": -125.280572,
        "locationCode": "FGPD",
        "hasPropertyData": False,
        "lat": 48.813795,
        "dataSearchURL": "https://data.oceannetworks.ca/DataSearch?location=FGPD",
    }
]

getLocationsTree(filters: dict | None = None)[source]

Return a location tree.

The API endpoint is /locations/tree.

Return a hierarchical representation of the ONC Search Tree Nodes. The Search Tree is used in Oceans 3.0 to organize instruments and variables by location so that users can easily drill down by place name or mobile platform name to find the instruments or properties they are interested in.

See https://data.oceannetworks.ca/OpenAPI#get-/locations/tree for usage and available query string parameters.

The function getLocationHierarchy is an alias for this function.

Parameters:

filters (dict, optional) –

Query string parameters in the API request. Return a tree of all available locations if None.

Supported parameters are:

locationCode
deviceCategoryCode
propertyCode
dataProductCode
dateFrom
dateTo
locationName
deviceCode

Returns:

API response. Each location returned in the list is a dict with the following structure.

locationName: str
children: list of dict | None
description: string
hasDeviceData: bool
locationCode: str
hasPropertyData: bool

Check https://wiki.oceannetworks.ca/display/O2A/Glossary+of+Terms for more information.

Return type:

list of dict

Examples

>>> params = {
...     "locationCode": "BACCC",
... }  
>>> onc.getLocationsTree(params)  
[
    {
        "locationName": "Coral Cliff",
        "children": [
            {
                "locationName": "ADCP 2 MHz East",
                "children": None,
                "description": "",
                "hasDeviceData": True,
                "locationCode": "BACCC.A1",
                "hasPropertyData": False,
            },
            {
                "locationName": "ADCP 2 MHz West",
                "children": None,
                "description": "",
                "hasDeviceData": True,
                "locationCode": "BACCC.A2",
                "hasPropertyData": False,
            },
        ],
        "description": " The Coral Cliffs are located within Barkley Canyon. At this location, boundary layer flow near steep bathymetry, interaction of currents, and deep-sea corals are observed.",
        "hasDeviceData": False,
        "locationCode": "BACCC",
        "hasPropertyData": True,
    }
]

getDeployments(filters: dict | None = None)[source]

Return a list of device deployments.

The API endpoint is /deployments.

Return all deployments defined in Oceans 3.0 which meet the filter criteria, where a deployment is the installation of a device at a location. The deployments service assists in knowing when and where specific types of data are available.

The primary purpose for the deployments service is to find the dates and locations of deployments and use the dateFrom and dateTo datetimes when requesting a data product using the dataProductDelivery web service.

See https://data.oceannetworks.ca/OpenAPI#get-/deployments for usage and available filters.

Parameters:

filters (dict, optional) –

Query string parameters in the API request. Return all device deployment if None.

Supported parameters are:

locationCode
deviceCategoryCode
deviceCode
propertyCode
dateFrom
dateTo

Returns:

API response. Each deployment returned in the list is a dict with the following structure.

begin: str
citation: dict
depth: float
deviceCategoryCode: str
deviceCode: str
end: str | None
hasDeviceData: bool
heading: float | None
lat: float
locationCode: str
lon: float
pitch: float | None
roll: float | None

Check https://wiki.oceannetworks.ca/display/O2A/Glossary+of+Terms for more information.

Return type:

list of dict

Examples

>>> params = {
...     "locationCode": "BACAX",
...     "deviceCategoryCode": "CTD",
...     "dateFrom": "2015-09-17",
...     "dateTo": "2015-09-17T13:00:00.000Z",
... }  
>>> onc.getDeployments(params)  
[
    {
        "begin": "2014-05-09T15:50:42.000Z",
        "citation": {
            "citation": "Ocean Networks Canada Society. 2015. Barkley Canyon Axis Conductivity Temperature Depth Deployed 2014-05-09. Ocean Networks Canada Society. https://doi.org/10.80242/14d156f2-0146-40e5-a77e-f3637fb6b517.",
            "doi": "10.80242/14d156f2-0146-40e5-a77e-f3637fb6b517",
            "landingPageUrl": "https://doi.org/10.80242/14d156f2-0146-40e5-a77e-f3637fb6b517",
            "queryPid": None,
        },
        "depth": 982.0,
        "deviceCategoryCode": "CTD",
        "deviceCode": "SBECTD16p6002",
        "end": "2015-09-17T12:59:52.000Z",
        "hasDeviceData": True,
        "heading": None,
        "lat": 48.316583,
        "locationCode": "BACAX",
        "lon": -126.050796,
        "pitch": None,
        "roll": None,
    }
]

getDevices(filters: dict | None = None)[source]

Return a list of devices.

The API endpoint is /devices.

Return all the devices defined in Oceans 3.0 that meet a set of filter criteria. Devices are instruments that have one or more sensors that observe a property or phenomenon with a goal of producing an estimate of the value of a property. Devices are uniquely identified by a device code and can be deployed at multiple locations during their lifespan.

The primary purpose of the devices service is to find devices that have the data you are interested in and use the deviceCode when requesting a data product using the dataProductDelivery web service.

See https://data.oceannetworks.ca/OpenAPI#get-/devices for usage and available filters.

Parameters:

filters (dict, optional) –

Query string parameters in the API request. Return all devices available if None.

Supported parameters are:

locationCode
deviceCategoryCode
deviceCode
propertyCode
dateFrom
dateTo

Returns:

API response. Each device returned in the list is a dict with the following structure.

cvTerm: dict
- cvTerm.device: list of dict
  
  cvTerm.device[].uri: str
  
  cvTerm.device[].vocabulary: str
dataRating: list of dict
- dataRating[].dateFrom: str
- dataRating[].dateTo: str | None
- dataRating[].samplePeriod: float
- dataRating[].sampleSize: int
deviceCategoryCode: str
deviceCode: str
deviceId: int
deviceLink: str
deviceName: str
hasDeviceData: bool

Check https://wiki.oceannetworks.ca/display/O2A/Glossary+of+Terms for more information.

Return type:

list of dict

Examples

>>> params = {
...     "deviceCode": "BPR-Folger-59",
...     "dateFrom": "2005-09-17T00:00:00.000Z",
...     "dateTo": "2020-09-17T13:00:00.000Z",
... }  
>>> onc.getDevices(params)  
[
    {
        "cvTerm": {
            "device": [
                {
                    "uri": "http://vocab.nerc.ac.uk/collection/L22/current/TOOL1652/",
                    "vocabulary": "SeaVoX Device Catalogue",
                }
            ]
        },
        "dataRating": [
            {
                "dateFrom": "2007-01-01T00:00:00.000Z",
                "dateTo": None,
                "samplePeriod": 1.0,
                "sampleSize": 1,
            }
        ],
        "deviceCategoryCode": "BPR",
        "deviceCode": "BPR-Folger-59",
        "deviceId": 21503,
        "deviceLink": "https://data.oceannetworks.ca/DeviceListing?DeviceId=21503",
        "deviceName": "NRCan Bottom Pressure Recorder 59",
        "hasDeviceData": True,
    }
]

getDeviceCategories(filters: dict | None = None)[source]

Return a list of device categories

The API endpoint is /deviceCategories.

Return all device categories defined in Oceans 3.0 that meet a filter criteria. A Device Category represents an instrument type classification such as CTD (Conductivity, Temperature & Depth Instrument) or BPR (Bottom Pressure Recorder). Devices from a category can record data for one or more properties (variables).

The primary purpose of this service is to find device categories that have the data you want to access; the service provides the deviceCategoryCode you can use when requesting a data product via the dataProductDelivery web service.

See https://data.oceannetworks.ca/OpenAPI#get-/deviceCategories for usage and available filters.

Parameters:

filters (dict, optional) –

Query string parameters in the API request. Return all device categories available if None.

Supported parameters are:

deviceCategoryCode
deviceCategoryName
description
locationCode
propertyCode

Returns:

API response. Each device category returned in the list is a dict with the following structure.

cvTerm: dict
- cvTerm.deviceCategory: list of dict
  
  cvTerm.deviceCategory[].uri: str
  
  cvTerm.deviceCategory[].vocabulary: str
description: str
deviceCategoryCode: str
deviceCategoryName: str
hasDeviceData: bool
longDescription: str

Check https://wiki.oceannetworks.ca/display/O2A/Glossary+of+Terms for more information.

Return type:

list of dict

Examples

>>> params = {
...     "deviceCategoryCode": "CTD",
...     "deviceCategoryName": "Conductivity",
...     "description": "Temperature",
... }  
>>> onc.getDeviceCategories(params)  
[
    {
        "cvTerm": {
            "deviceCategory": [
                {
                    "uri": "http://vocab.nerc.ac.uk/collection/L05/current/130/",
                    "vocabulary": "SeaDataNet device categories",
                }
            ]
        },
        "description": "Conductivity Temperature (and Depth Sensor)",
        "deviceCategoryCode": "CTD",
        "deviceCategoryName": "Conductivity Temperature Depth",
        "hasDeviceData": True,
        "longDescription": " Conductivity Temperature Depth (CTD) is an instrument package that contains sensors for measuring the conductivity, temperature, and pressure of seawater. Salinity, sound velocity, depth and density are variables that can be derived from sensor measurements. CTDs can carry additional instruments and sensors such as oxygen sensors, turbidity sensors and fluorometers.",
    }
]

getProperties(filters: dict | None = None)[source]

Return a list of properties.

The API endpoint is /properties.

Return all properties defined in Oceans 3.0 that meet a filter criteria. Properties are observable phenomena (aka, variables) and are the common names given to sensor types (i.e., oxygen, pressure, temperature, etc).

The primary purpose of this service is to find the available properties of the data you want to access; the service provides the propertyCode that you can use to request a data product via the dataProductDelivery web service.

See https://data.oceannetworks.ca/OpenAPI#get-/properties for usage and available filters.

Parameters:

filters (dict, optional) –

Query string parameters in the API request. Return all properties available if None.

Supported parameters are:

propertyCode
propertyName
description
locationCode
deviceCategoryCode
deviceCode

Returns:

API response. Each property returned in the list is a dict with the following structure.

cvTerm: dict
- cvTerm.property: list of dict
  
  cvTerm.property[].uri: str
  
  cvTerm.property[].vocabulary: str
- cvTerm.uom: list of dict
  
  cvTerm.uom[].uri: str
  
  cvTerm.uom[].vocabulary: str
description: str
hasDeviceData: bool
hasPropertyData: bool
propertyCode: str
propertyName: str
uom: str

Check https://wiki.oceannetworks.ca/display/O2A/Glossary+of+Terms for more information.

Return type:

list of dict

Examples

>>> params = {
...     "propertyCode": "conductivity",
...     "locationCode": "BACAX",
...     "deviceCategoryCode": "CTD",
... }  
>>> onc.getProperties(params)  
[
    {
        "cvTerm": {
            "property": [],
            "uom": [
                {
                    "uri": "http://vocab.nerc.ac.uk/collection/P06/current/UECA/",
                    "vocabulary": "BODC data storage units",
                }
            ],
        },
        "description": "Conductivity: siemens per metre",
        "hasDeviceData": True,
        "hasPropertyData": True,
        "propertyCode": "conductivity",
        "propertyName": "Conductivity",
        "uom": "S/m",
    }
]

getDataProducts(filters: dict | None = None)[source]

Return a list of data products.

The API endpoint is /dataProducts.

Return all data products defined in Oceans 3.0 that meet a filter criteria. Data Products are downloadable representations of ONC observational data, provided in formats that can be easily ingested by analytical or visualization software.

The primary purpose of this service is to identify which data products and formats (file extensions) are available for the locations, devices, device categories or properties of interest. Use the dataProductCode and extension when requesting a data product via the dataProductDelivery web service.

See https://data.oceannetworks.ca/OpenAPI#get-/dataProducts for usage and available filters.

Parameters:

filters (dict, optional) –

Query string parameters in the API request. Return all data products available if None.

Supported parameters are:

dataProductCode
extension
dataProductName
propertyCode
locationCode
deviceCategoryCode
deviceCode

Returns:

API response. Each data product returned in the list is a dict with the following structure.

dataProductCode: str
dataProductName: str
dataProductOptions: list of dict
- dataProductOptions[].allowableRange: list of dict | None
  
  dataProductOptions[].allowableRange.lowerBound: str
  
  dataProductOptions[].allowableRange.onlyIntegers: bool
  
  dataProductOptions[].allowableRange.unitOfMeasure: str | None
  
  dataProductOptions[].allowableRange.upperBound: str
- dataProductOptions[].allowableValues: list of str
- dataProductOptions[].defaultValues: str
- dataProductOptions[].documentation: list of str
- dataProductOptions[].option: str
- dataProductOptions[].suboptions: list of dict | None
extension: str
hasDeviceData: bool
hasPropertyData: bool
helpDocument: str

Check https://wiki.oceannetworks.ca/display/O2A/Glossary+of+Terms for more information.

Return type:

list of dict

Examples

>>> params = {
...     "dataProductCode": "SHV",
... }  
>>> onc.getDataProducts(params)  
[
    {
        "dataProductCode": "SHV",
        "dataProductName": "Spectrogram For Hydrophone Viewer",
        "dataProductOptions": [
            {
                "allowableRange": {
                    "lowerBound": "-160.0",
                    "onlyIntegers": False,
                    "unitOfMeasure": None,
                    "upperBound": "140.0",
                },
                "allowableValues": ["-1000"],
                "defaultValue": "-1000",
                "documentation": [
                    "https://wiki.oceannetworks.ca/display/DP/Spectrogram+Plot+Options"
                ],
                "option": "dpo_lowerColourLimit",
                "suboptions": None,
            },
            {
                "allowableRange": None,
                "allowableValues": ["0", "1", "2", "3", "4", "5"],
                "defaultValue": "0",
                "documentation": [
                    "https://wiki.oceannetworks.ca/display/DP/Spectrogram+Plot+Options"
                ],
                "option": "dpo_spectrogramColourPalette",
                "suboptions": None,
            },
            {
                "allowableRange": {
                    "lowerBound": "-160.0",
                    "onlyIntegers": False,
                    "unitOfMeasure": None,
                    "upperBound": "140.0",
                },
                "allowableValues": ["-1000"],
                "defaultValue": "-1000",
                "documentation": [
                    "https://wiki.oceannetworks.ca/display/DP/Spectrogram+Plot+Options"
                ],
                "option": "dpo_upperColourLimit",
                "suboptions": None,
            },
        ],
        "extension": "png",
        "hasDeviceData": True,
        "hasPropertyData": False,
        "helpDocument": "https://wiki.oceannetworks.ca/display/DP/146",
    }
]

orderDataProduct(filters: dict, maxRetries: int = 0, downloadResultsOnly: bool = False, includeMetadataFile: bool = True, overwrite: bool = False)[source]

requestDataProduct(filters: dict)[source]

checkDataProduct(dpRequestId: int)[source]

Check status of a requested data product.

The API endpoint is /dataProductDelivery/status.

See https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/status for usage.

Parameters:: dpRequestId (int) – A dpRequestId returned from calling requestDataProduct.
Returns:: API response.
Return type:: dict

runDataProduct(dpRequestId: int, waitComplete: bool = True)[source]

cancelDataProduct(dpRequestId: int)[source]

Cancel a running data product.

The API endpoint is /dataProductDelivery/cancel.

See https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/cancel for usage.

Parameters:

dpRequestId (int) – A dpRequestId returned from calling requestDataProduct.

Returns:

API response. Each status returned in the list is a dict with the following structure.

dpRunId: int
status: str

Return type:

list of dict

restartDataProduct(dpRequestId: int, waitComplete: bool = True)[source]

Restart a cancelled data product.

The API endpoint is /dataProductDelivery/restart.

Restart searches cancelled by calling the cancelDataProduct method.

See https://data.oceannetworks.ca/OpenAPI#get-/dataProductDelivery/restart for usage.

Parameters:

dpRequestId (int) – A dpRequestId returned from calling requestDataProduct.

Returns:

API response. Each status returned in the list is a dict with the following structure.

dpRunId: int
status: str

Return type:

list of dict

downloadDataProduct(runId: int, maxRetries: int = 0, downloadResultsOnly: bool = False, includeMetadataFile: bool = True, overwrite: bool = False)[source]

getScalardataByLocation(filters: dict = None, allPages: bool = False)[source]

Return scalar data in JSON format by given location code and device category code.

The API endpoint is /scalardata/location.

See https://data.oceannetworks.ca/OpenAPI#get-/scalardata/location for usage.

The function getDirectByLocation is an alias for this function.

Parameters:

filters (dict, optional) –
Query string parameters in the API request.

Supported parameters are:
- locationCode (required)
- deviceCategoryCode (required)
- propertyCode
- sensorCategoryCodes
- dateFrom
- dateTo
- metadata
- rowLimit
- outputFormat
- returnOptions
- getLatest
- qualityControl
- resampleType
- resamplePeriod
- fillGaps
- sensorsToInclude
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

API response.

Return type:

dict

getScalardataByDevice(filters: dict = None, allPages: bool = False)[source]

Return scalar data in JSON format by given device code.

The API endpoint is /scalardata/device.

See https://data.oceannetworks.ca/OpenAPI#get-/scalardata/device for usage.

The function getDirectByDevice is an alias for this function.

Parameters:

filters (dict, optional) –
Query string parameters in the API request.

Supported parameters are:
- deviceCode (required)
- sensorCategoryCodes
- dateFrom
- dateTo
- rowLimit
- outputFormat
- returnOptions
- getLatest
- qualityControl
- resampleType
- resamplePeriod
- fillGaps
- sensorsToInclude
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

API response.

Return type:

dict

getScalardata(filters: dict = None, allPages: bool = False)[source]

Return scalar data in JSON format by given query parameters.

A helper method for getting scalar data. Whether it is by device or by location is inferred from the keys in the given query parameters.

ByDevice requires deviceCode.
ByLocation requires locationCode and deviceCategoryCode.
Raise ValueError if they both exist.

Parameters:

filters (dict, optional) – Query string parameters in the API request. See getScalardataByLocation and getScalardataByDevice for more information.
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

API response.

Return type:

dict

getRawdataByLocation(filters: dict = None, allPages: bool = False)[source]

Return the raw data at a given location for the given device category.

A date range is optional. When not specified, data from all time will be returned within (possibly default) row and size limits.

The API endpoint is /rawdata/location.

See https://data.oceannetworks.ca/OpenAPI#get-/rawdata/location for usage.

The function getDirectRawByLocation is an alias for this function.

Parameters:

filters (dict, optional) –
Query string parameters in the API request.

Supported parameters are:
- locationCode (required)
- deviceCategoryCode (required)
- dateFrom
- dateTo
- rowLimit
- sizeLimit
- convertHexToDecimal
- outputFormat
- getLatest
- skipErrors
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

API response.

Return type:

dict

getRawdataByDevice(filters: dict = None, allPages: bool = False)[source]

Return the raw data for a given device.

A date range is optional. When not specified, data from all time will be returned within (possibly default) row and size limits.

The API endpoint is /rawdata/device.

See https://data.oceannetworks.ca/OpenAPI#get-/rawdata/device for usage.

The function getDirectRawByDevice is an alias for this function.

Parameters:

filters (dict, optional) –
Query string parameters in the API request.

Supported parameters are:
- deviceCode (required)
- dateFrom
- dateTo
- rowLimit
- sizeLimit
- convertHexToDecimal
- outputFormat
- getLatest
- skipErrors
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

API response.

Return type:

dict

getRawdata(filters: dict = None, allPages: bool = False)[source]

Return the raw data by given query parameters.

A helper method for getting the raw data. Whether it is by device or by location is inferred from the keys in the given query parameters.

ByDevice requires deviceCode.
ByLocation requires locationCode and deviceCategoryCode.
Raise ValueError if they both exist.

Parameters:

filters (dict, optional) – Query string parameters in the API request. See getRawdataByLocation and getRawdataByDevice for more information.
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

API response.

Return type:

dict

getSensorCategoryCodes(filters: dict)[source]

Return a list of sensor category codes.

A helper method for narrowing down the sensorCategoryCodes that are of interest prior to the use of the scalardata service.

Parameters:

filters (dict) – Query string parameters in the API request. Use the same filters for calling getScalardata.

Returns:

API response. Each sensor category code returned in the list is a dict with the following structure.

outputFormat: str
propertyCode: str
sensorCategoryCode: str
sensorCode: str
sensorName: str
unitOfMeasure: str

Return type:

list of dict

Examples

>>> params = {
...     "locationCode": "NCBC",
...     "deviceCategoryCode": "BPR",
...     "propertyCode": "seawatertemperature,totalpressure",
... }  
>>> onc.getSensorCategoryCodes(params)  
[
    {
        "outputFormat": "array",
        "propertyCode": "totalpressure",
        "sensorCategoryCode": "pressure",
        "sensorCode": "Pressure",
        "sensorName": "Seafloor Pressure",
        "unitOfMeasure": "decibar",
    },
    {
        "outputFormat": "array",
        "propertyCode": "seawatertemperature",
        "sensorCategoryCode": "temperature",
        "sensorCode": "Temperature",
        "sensorName": "Housing Temperature",
        "unitOfMeasure": "C",
    },
    {
        "outputFormat": "array",
        "propertyCode": "seawatertemperature",
        "sensorCategoryCode": "temperature1",
        "sensorCode": "temperature1",
        "sensorName": "Temperature",
        "unitOfMeasure": "C",
    },
    {
        "outputFormat": "array",
        "propertyCode": "seawatertemperature",
        "sensorCategoryCode": "temperature2",
        "sensorCode": "temperature2",
        "sensorName": "P-Sensor Temperature",
        "unitOfMeasure": "C",
    },
]

getArchivefileByLocation(filters: dict = None, allPages: bool = False)[source]

Return a list of files available in Oceans 3.0 Archiving System for a given location code and device category code.

The API endpoint is /archivefile/location.

See https://data.oceannetworks.ca/OpenAPI#get-/archivefile/location for usage.

The function getListByLocation is an alias for this function.

Parameters:

filters (dict, optional) –
Query string parameters in the API request.

Supported parameters are:
- locationCode (required)
- deviceCategoryCode (required)
- dateFrom
- dateTo
- dateArchivedFrom
- dateArchivedTo
- fileExtension
- dataProductCode
- returnOptions
- rowLimit
- page
- getLatest
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

API response.

Return type:

dict

getArchivefileByDevice(filters: dict = None, allPages: bool = False)[source]

Return a list of files available in Oceans 3.0 Archiving System for a given device code.

The API endpoint is /archivefile/device.

See https://data.oceannetworks.ca/OpenAPI#get-/archivefile/device for usage.

The function getListByDevice is an alias for this function.

Parameters:

filters (dict, optional) –
Query string parameters in the API request.

Supported parameters are:
- deviceCode (required)
- dateFrom
- dateTo
- dateArchivedFrom
- dateArchivedTo
- fileExtension
- dataProductCode
- returnOptions
- rowLimit
- page
- getLatest
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

API response.

Return type:

dict

getArchivefile(filters: dict = None, allPages: bool = False)[source]

Return a list of files available in Oceans 3.0 Archiving System by given query parameters.

A helper method for getting a list of archive files. Whether it is by device or by location is inferred from the keys in the given query parameters.

ByDevice requires deviceCode.
ByLocation requires locationCode and deviceCategoryCode.
Raise ValueError if they both exist.

Parameters:

filters (dict, optional) – Query string parameters in the API request. See getArchivefileByLocation and getArchivefileByDevice for more information.
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

API response.

Return type:

dict

downloadArchivefile(filename: str = '', overwrite: bool = False)[source]

Download a file from Oceans 3.0 Archiving System by specifying the file name.

The file will be downloaded without any compression. Many files in the archive are compressed for storage, uncompressing these files takes time on the server and increases data volume to transfer.

The API endpoint is /archivefile/download.

See https://data.oceannetworks.ca/OpenAPI#get-/archivefile/download for usage.

The function getFile is an alias for this function.

Parameters:

filename (str, default "") – A valid name of a file in DMAS Archiving System.
overwrite (bool, default False) – Whether to overwrite the file if it exists.

Returns:

dict showing the error message if the filename is invalid. None if the download is successful.

Return type:

dict | None

downloadDirectArchivefile(filters: dict = None, overwrite: bool = False, allPages: bool = False)[source]

Download files from Oceans 3.0 Archiving System by given query parameters.

A helper method to combine getArchivefile and downloadArchivefile. Internally it calls getArchivefile to get a list of archive files, and downloadArchivefile to download all files.

The function getDirectFiles is an alias for this function.

Parameters:

filters (dict, optional) – Query string parameters in the API request. See getArchivefileByLocation and getArchivefileByDevice for more information.
overwrite (bool, default False) – Whether to overwrite the file if it exists.
allPages (bool, default False) – Whether the response concatenates data on all pages if there are more than one page due to rowLimit.

Returns:

A dict showing download results.

Return type:

dict