The API devices returns 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.
https://data.oceannetworks.ca/api/devices
Method | Description | Example |
---|---|---|
get | Retrieve a list of all devices |
|
The get method retrieves a list of devices with deviceId, deviceCode, and deviceName.
Parameter | Type | Description | Example |
---|---|---|---|
Required | |||
token | string | All Web Services require a token. This can be generated at https://data.oceannetworks.ca/Profile. Click on the "Web Services" tab and click "Generate Token". | token=YOUR_TOKEN_HERE |
Optional | |||
deviceCode | string | Return a single Device matching a specific Device Code.
| deviceCode=FSINXIC1622 |
deviceId | integer | Return a single Device matching a specific Device ID.
| deviceId=10301 |
deviceCategoryCode | string | Return all Devices belonging to a specific Device Category Code.
| deviceCategoryCode=CTD |
propertyCode | string | Return all Devices that have a sensor for a specific Property Code.
| propertyCode=pressure |
deviceName | string | Return all of the Devices where the Device Name contains a keyword.
| deviceName=meter |
locationCode | string | Return all Devices that are deployed at a specific Location.
| locationCode=BACAX |
includeChildren | boolean | Return all Devices that are deployed at a specific Location and sub-tree Locations.
| includeChildren=true |
dataProductCode | string | Return all Devices that have the ability to return a specific Data Product Code.
| dataProductCode=jpgfile |
dateFrom | datetime | Return all of the Devices that have a Deployment Beginning on or after a specific date/time. Accepted DateTime formats:
If not specified, the default value is the beginning of time.
| dateFrom=2010-07-27T00:00:00.000Z dateFrom=2010-07-27 dateFrom=-P1DT1H
|
dateTo | datetime | Return all of the Devices that have a Deployment Ending before a specific date/time. Accepted DateTime formats:
If not specified, the default value is the end of time.
| dateTo=2016-08-01T00:00:00.000Z dateTo=2016-08-01 dateTo=PT12H30M
|
Example for request: https://data.oceannetworks.ca/api/devices?method=get&token=YOUR_TOKEN_HERE&locationCode=BACAX&dateFrom=2010-07-01T00:00:00.000Z&dateTo=2011-06-30T23:59:59.999Z
Returns a list of devices with values for Device Code, Device Id, Device Name and Device Link URL, ordered by Device Code
|
Property | Type | Description | Example |
---|---|---|---|
deviceCode | string | Returns the device code | "deviceCode":"BC_POD1_AD2M" |
deviceId | integer | Returns the device id | "deviceId":11302 |
deviceCategoryCode | string | Returns the device category code | "deviceCategoryCode:"HYDROPHONE" |
deviceName | string | Returns the device name | "deviceName":"Nortek Aquadopp HR-Profiler 2965" |
deviceLink | url | Returns the a URL link to Device Listing page for the specific device | "deviceLink":"https://data.oceannetworks.ca/DeviceListing?DeviceId=11302" |
dataRating | list | Returns a list of data ratings and date from for each device–this list may be empty Each data rating is made up of:
| "dataRating": [ |
cvTerm | object | The list of controlled vocabulary terms associated with the device and any device groups the device belongs to. Each vocabulary term is made up of:
| "cvTerm": { |
hasDeviceData | boolean | hasDeviceData flag for devices with searchable device and siteDevice | "hasDeviceData":true |
errorCode | errorMessage | Description |
---|---|---|
23 | Invalid Time Range, Start Time is greater that End Time or start time is not provided | Occurs when the dateTo is before the dateFrom date/time.
|
25 | Invalid Time Range, Start Time is in the future. | Occurs when the dateFrom is in the future.
|
127 | Invalid parameter value | Occurs when an invalid code is used in the filter. Most filters require an exact match, otherwise this error will occur.
|
128 | Missing parameter | Occurs when multiple parameters are needed, but not all are present. Occurs when dateFrom is used without dateTo or vice versa
|
129 | Invalid parameter name | Occurs when a filter parameter is in the query but is not supported.
|
https://data.oceannetworks.ca/api/devices?method=get&token=YOUR_TOKEN_HERE
https://data.oceannetworks.ca/api/devices?method=get&token=YOUR_TOKEN_HERE&deviceCode=NORTEKADCP9917
https://data.oceannetworks.ca/api/devices?method=get&token=YOUR_TOKEN_HERE&deviceName=JASCO
https://data.oceannetworks.ca/api/devices?method=get&token=YOUR_TOKEN_HERE&locationCode=BACAX
https://data.oceannetworks.ca/api/devices?method=get&token=YOUR_TOKEN_HERE&propertyCode=oxygen
https://data.oceannetworks.ca/api/devices?method=get&token=YOUR_TOKEN_HERE&dataProductCode=IBPP
The https://data.oceannetworks.ca/apiproxy/devicesURL 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 behavior. In order to use the deployments endpoint from code, you must use the https://data.oceannetworks.ca/api/devices url along with a valid token.
Please report all issues with the web services, documentation, samples and client libraries to the Oceans 3.0 Help Centre |