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


Description

The API deviceCategories service returns all device categories defined in Oceans 2.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.


URL

https://data.oceannetworks.ca/api/deviceCategories
Method
Description
Example
getGet a list of files for a given station, and filtered by others optional parameters.method=get

 get

Get a list of device categories in Oceans 2.0. 

Parameters

ParameterTypeDescriptionExample
Required
tokenstringAll Web Services require a token. Once logged in at https://data.oceannetworks.ca/login, your token can be retrieved or generated at https://data.oceannetworks.ca/Profile . Click on the "Web Services" tab, then click "Generate Token".token=YOUR_TOKEN_HERE
Optional
deviceCategoryCodestring

Return a single Device Category matching a specific Device Category Code

  • Device Category Code must be valid and match exactly, including case.
  • Run the service without this parameter to get a list of all devices.
deviceCategoryCode=CTD
deviceCategoryNamestring

Return all of the Device Categories where the Device Category Name contains a keyword

  • Filter is not case sensitive, treating adcp and ADCP as the same word.
    • Filter will find partial words. The filter deviceCategoryName=adcp returns "ADCP 55 kHz, "ADCP 75 kHz", "ADCP 150 kHz", "ADCP 300 kHz", "ADCP 1 MHz", "ADCP 2 MHz" and more.
deviceCategoryName=adcp
descriptionstring

Return all of the Device Categories where the Description contains a keyword.

  • Filter is not case sensitive and will find partial words. (See above)
description=Camera
locationCodestring

Return all Device Categories that are represented at a specific Location.

  • Location Code must be valid and match exactly, including case.
  • Specific Location Codes can be obtained using the locations service.
locationCode=BACAX
propertyCodestring

Return all Device Categories associated specific Property.

  • Property Code must be valid and match exactly, including case.
  • Specific Property Codes can be obtained using the properties service.
propertyCode=differentialtemperature

Response

Example for request: https://data.oceannetworks.ca/api/deviceCategories?method=get&token=[YOUR_TOKEN_HERE]&propertyCode=salinity

Success (HTTP 200)

Returns a list of device categories with values for Device Category Code, Device Category Name, Description and Long Description, ordered by Device Category Code

 

[
 {
    "description":"Conductivity Temperature (and Depth Sensor)",
    "deviceCategoryCode":"CTD",
    "deviceCategoryName":"CTD",
    "longDescription":" Conductivity Temperature Depth (CTD) is an abbreviated name for an instrument package that contains sensors for measuring the conductivity, temperature, and pressure of seawater. Salinity, sound velocity, and density are variables derived from sensor measurements. CTDs can carry additional instruments and sensors such as oxygen sensors, turbidity sensors and fluorometers. ",
    "cvTerm": [{  "deviceCategory": [{  "vocabulary""SeaDataNet device categories""uri""http://vocab.nerc.ac.uk/collection/L05/current/130/"}]    }]
 },
 {
    "description":"Current Meter",
    "deviceCategoryCode":"CURRENTMETER",
    "deviceCategoryName":"Current Meter",
    "longDescription":" Acoustic Current Meters (ACM) use the Doppler Effect to measure current velocities in the ocean environment. The instrument transmits a short pulse of sound, and then listens to its echo to measure the change in pitch or frequency. The change in pitch can determine the velocity of the current.  Current metres are installed at many locations on Ocean Networks Canada observatories. Several current metres are installed on the Regional Circulation Moorings (RCM) at Endeavour. The instruments are spaced at various depths on the RCM moorings, and are used to study currents within the axial rift valley of Endeavour Ridge. Aquadopp current metres have a sensor head that contains 3 acoustic transducers, a tilt sensor, a temperature sensor and a pressure sensor.",
    "cvTerm": [{  "deviceCategory": [{  "vocabulary""SeaDataNet device categories""uri""http://vocab.nerc.ac.uk/collection/L05/current/114/"}]    }]
 },
 {
    "description":"Thermosalinograph",
    "deviceCategoryCode":"TSG",
    "deviceCategoryName":"Thermosalinograph",
    "longDescription":" Thermosalinographs collect data about the sea surface via flow-through systems that move over water on a vessel. Often, they are mounted near the front of the vessel in order to minimize contamination. Primary variables measured are temperature and conductivity, and other variables like salinity and density are derived.",
    "cvTerm": [{  "deviceCategory": [{  "vocabulary""SeaDataNet device categories""uri""http://vocab.nerc.ac.uk/collection/L05/current/123/"}]    }]
 },
 {
    "description":"Water Quality Monitor",
    "deviceCategoryCode":"WETLABS_WQM",
    "deviceCategoryName":"Water Quality Monitor",
    "longDescription":" Water Quality Monitors (WQM) have sensors to measure temperature, salinity, depth, dissolved oxygen, chlorophyll fluorescence, turbidity and backscattering data. The WQM incorporate technologies from two manufacturers, WET Labs and Sea-Bird. To reduce fouling and growth of marine organisms, WQM also have features such as a Bleach Injection System (BLIS), bio-wipers, and passive inhibitors that allow extended deployments up to one year. WQMs provide comprehensive data used to track subtle changes in coastal and inshore marine systems. WQM have been installed in local settings such as Mill Bay, as well as the frigid Arctic waters of Cambridge Bay.",
    "cvTerm": [{  "deviceCategory": [{  "vocabulary""SeaDataNet device categories""uri""http://vocab.nerc.ac.uk/collection/L05/current/123/"}]    }]
 }
]
Property
Type
Description
Examples
deviceCategoryCode
string
The unique code for the device category.
"deviceCategoryCode":"ICE_BUOY"
deviceCategoryName
string
The name of the device category.
"deviceCategoryName":"Ice Buoy"
description
string
The short description of the device category.
"description":"Ice Buoy"
hasDeviceDatastringWhether at least one device with this device category is NEPTUNE-searchable and has a NEPTUNE-searchable site."hasDeviceData":"true"
longDescription
string
The long description of the device category.
"longDescription":" Ice buoys are used in Arctic and Antarctic regions to track ice movement and collect environmental data. 
Ice buoys can be geographically located with the Argos system or other satellite navigation receivers (e.g. GPS)."
cvTermlist

The list of controlled vocabulary terms associated with the device category.

Each vocabulary term in the controlled vocabulary list contains two key-value pairs:

  1. Key : "vocabulary" Value : "title of the vocabulary the term belongs to"
  2. Key: "uri" Value: "the vocabulary term url"

 

"cvTerm": [
    {
      "deviceCategory": [
        {
          "vocabulary""NERC-L05",
          "uri""http://vocab..."
        }
      ]
    }
]

 

Bad Request (HTTP 400)

errorCode
errorMessage
Description
127Invalid parameter value

Occurs when an invalid code is used in the filter. Most filters require an exact match, otherwise this error will occur.

  • The name of the filter parameter are included in the parameter property
129Invalid parameter name

Occurs when a filter parameter is used, but is not supported.

 

 URL Examples

  • Return a list of All Device Categories (no filters)

https://data.oceannetworks.ca/api/deviceCategories?method=get&token=[YOUR_TOKEN_HERE]

 

  • Return the Device Category with Code 'ADCP1MHZ'

https://data.oceannetworks.ca/api/deviceCategories?method=get&token=[YOUR_TOKEN_HERE]&deviceCategoryCode=ADCP1MHZ

 

  • Return a list of all Device Categories that have a Name which contains 'adcp'

https://data.oceannetworks.ca/api/deviceCategories?method=get&token=[YOUR_TOKEN_HERE]&deviceCategoryName=adcp

 

  • Return a list of all Device Categories that have a Description which contains 'doppler'

https://data.oceannetworks.ca/api/deviceCategories?method=get&token=[YOUR_TOKEN_HERE]&description=doppler

 

  • Return a list of all Device Categories that are available at a location with a Location Code of 'BACAX' ('Barkely Canyon Axis (POD1)')

https://data.oceannetworks.ca/api/deviceCategories?method=get&token=[YOUR_TOKEN_HERE]&locationCode=BACAX

 

  • Return a list of all Device Categories which has devices with a specific Property Code of 'salinity'

https://data.oceannetworks.ca/api/deviceCategories?method=get&token=[YOUR_TOKEN_HERE]&propertyCode=salinity

API Proxy

The https://data.oceannetworks.ca/apiproxy/deviceCategories URL link in the above examples can be used in a browser for sharing or testing purposes; however, it can not be accessed from code. Calls to the apiproxy server are redirected to a login screen to capture your user id. Accessing the apiproxy URL from code will return html in the payload, which may cause errors or unexpected behaviour. In order to use the deviceCategories endpoint from code, you must use the https://data.oceannetworks.ca/api/deviceCateogies url along with a valid token. 

Code Examples

TitleCreatorModified
Python Client LibraryRyan Ross16-Aug-19
MATLAB Client LibraryRyan Ross26-Apr-19
Discover Device CategoriesRyan Ross23-Apr-18

 

 

Please report all issues with the web services, documentation, samples and client libraries to the Oceans 2.0 Help Centre 

  • No labels