...
The API devices returns all the devices defined in Oceans 23.0 which that meet a set of filter criteria.
Devices are instruments with 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 this the devices service is to find devices that have the data you want to access; the service provides the deviceCode that can be used to request are interested in and use the deviceCode when requesting a data product via using the dataProductDelivery web service.
For a list of available device codes, along with names, ids and device links, see the Available Devices page.
See the External Web Services for method and token usage and error messages.
URL
...
URL
https://data.oceannetworks.ca/api/devices
Method | Description | Example |
---|---|---|
get | Retrieve a list of all devices |
|
get
The get method retrieves a list of devices with deviceId, deviceCode, and deviceName.
Parameters
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 |
- Not case sensitive
- Contains
Return all Devices that are deployed at a specific Location
- Location Code must be valid and match exactly, including case
- Specific Location Codes can be obtained using the locations service
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 |
- When the depolymentBegin filter is included, the deploymentEnd filter must also be included
Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
DateTime is represented in Coordinated Universal Time (UTC)
deploymentBegin=2010-07-27T00:00:00.000Z
Return all of the Devices that have a Deployment Ending on or before a specific date/time
- When the deploymentEnd filter is included, the deploymentBegin filter must also be included
Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
DateTime is represented in Coordinated Universal Time (UTC)
deploymentEnd=2016-08-01T00:00:00.000Z
Response
Example for request: http://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&deviceCategoryCode=ADCP2MHZ
Success (HTTP 200)
Returns a list of devices with values for Device Code, Device Id, Device Name and Device Link URL, ordered by Device Code
...
"dataRating"
: [{
"samplePeriod"
:1.0,
"dateFrom"
,
"2008-11-01 00:00:00"
},{
"samplePeriod"
:10.0,
"dateFrom"
,
"2010-05-27 19:27:04"
}],
"cvTerm"
: [{
"device"
: [{
"vocabulary"
:
"SeaVoX Device Catalogue"
,
"uri"
:
"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
}] }]
},
{
"deviceCode"
:
"NortekADCP1504"
,
"deviceId"
:22666,
"deviceLink"
:
"http://qaweb2.neptune.uvic.ca/DeviceListing?DeviceId=22666"
,
"deviceName"
:
"Nortek Aquadopp Profiler AQD 1504 on Crawler"
,
"dataRating"
: [{
"samplePeriod"
:60.0,
"dateFrom"
,
"2010-08-01 00:00:00"
}],
"cvTerm"
: [{
"device"
: [{
"vocabulary"
:
"SeaVoX Device Catalogue"
,
"uri"
:
"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
}] }]
},
{
"deviceCode"
:
"NORTEKADCP9917"
,
"deviceId"
:23081,
"deviceLink"
:
"http://qaweb2.neptune.uvic.ca/DeviceListing?DeviceId=23081"
,
"deviceName"
:
"Nortek Aquadopp Profiler AQD 9917"
,
"dataRating"
: [{
"samplePeriod"
:60.0,
"dateFrom"
,
"2012-05-23 18:28:16"
},{
"samplePeriod"
:60.0,
"dateFrom"
,
"2012-05-01 00:00:00"
}],
"cvTerm"
: [{
"device"
: [{
"vocabulary"
:
"SeaVoX Device Catalogue"
,
"uri"
:
"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
}] }]
},
{
"deviceCode"
:
"NORTEKAQDPRO2751"
,
"deviceId"
:23164,
"deviceLink"
:
"http://qaweb2.neptune.uvic.ca/DeviceListing?DeviceId=23164"
,
"deviceName"
:
"Nortek Aquadopp Profiler AQD 2751"
,
"dataRating"
: [{
"samplePeriod"
:300.0,
"dateFrom"
,
"2013-05-14 00:00:00"
}],
"cvTerm"
: [{
"device"
: [{
"vocabulary"
:
"SeaVoX Device Catalogue"
,
"uri"
:
"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
}] }]
},
{
"deviceCode"
:
"NORTEKAQDPRO2786"
,
"deviceId"
:23163,
"deviceLink"
:
"http://qaweb2.neptune.uvic.ca/DeviceListing?DeviceId=23163"
,
"deviceName"
:
"Nortek Aquadopp Profiler AQD 2786"
,
"dataRating"
: [{
"samplePeriod"
:300.0,
"dateFrom"
,
"2013-05-14 00:00:00"
}],
"cvTerm"
: [{
"device"
: [{
"vocabulary"
:
"SeaVoX Device Catalogue"
,
"uri"
:
"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
}] }]
},
{
"deviceCode"
:
"NORTEKAQDPRO2958"
,
"deviceId"
:20002,
"deviceLink"
:
"http://qaweb2.neptune.uvic.ca/DeviceListing?DeviceId=20002"
,
"deviceName"
:
"Nortek Aquadopp Profiler AQD 2958"
,
"dataRating"
: [{
"samplePeriod"
:1.0,
"dateFrom"
,
"2008-03-01 00:00:00"
},{
"samplePeriod"
:1.0,
"dateFrom"
,
"2008-11-01 00:00:00"
},{
"samplePeriod"
:10.0,
"dateFrom"
,
"2010-10-28 23:21:06"
},{
"samplePeriod"
:60.0,
"dateFrom"
,
"2011-02-21 23:48:02"
}],
...
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
|
Response
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
Success (HTTP 200)
Returns a list of devices with values for Device Code, Device Id, Device Name and Device Link URL, ordered by Device Code
|
...
},
{
"deviceCode"
:
"NORTEKAQDPRO8398"
,
"deviceId"
:520,
"deviceLink"
:
"http://qaweb2.neptune.uvic.ca/DeviceListing?DeviceId=520"
,
"deviceName"
:
"Nortek Aquadopp Profiler AQD 8398"
,
"dataRating"
: [{
"samplePeriod"
:1200.0,
"dateFrom"
,
"2013-02-06 00:00:00"
},{
"samplePeriod"
:600.0,
"dateFrom"
,
"2014-04-17 17:00:00"
}],
"cvTerm"
: [{
"device"
: [{
"vocabulary"
:
"SeaVoX Device Catalogue"
,
"uri"
:
"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
}] }]
},
...
|
|
...
...
...
|
...
"dataRating"
: [{
"samplePeriod"
:900.0,
"dateFrom"
,
"2013-04-18 00:00:00"
},{
"samplePeriod"
:600.0,
"dateFrom"
,
"2014-05-13 00:00:00"
}],
"cvTerm"
: [{
"device"
: [{
"vocabulary"
:
"SeaVoX Device Catalogue"
,
"uri"
:
"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
}] }]
},
...
|
...
|
...
...
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
...
...
},
...
|
...
|
...
|
...
...
...
...
|
...
|
...
|
...
|
...
|
"cvTerm"
: [{
"device"
: [{
"vocabulary"
:
"SeaVoX Device Catalogue"
,
"uri"
:
"http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/"
}] }]
}]
...
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": |
"dataRating"
: [
{
"samplePeriod"
:
1.0
,
"dateFrom"
:
"2013-08-01 00:00:00"
[ |
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": { |
:" |
"cvTerm"
: [
{
"device"
: [
{
http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/", |
"SeaVoX Device |
,
}
]
}
Bad Request (HTTP 400)
Catalogue" | |||
hasDeviceData | boolean | hasDeviceData flag for devices with searchable device and siteDevice | "hasDeviceData":true |
Bad Request (HTTP 400)
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 |
...
.
|
Examples
- Return a list of All Devices (no filters) of the Devices (no filters)
https://data.oceannetworks.ca/api/devices?method=get&token=YOUR_TOKEN_HERE
- Return the Device with a Device Code of 'NORTEKADCP9917'
httpshttp://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]
- Return the Device with a Device Code of 'NORTEKADCP9917'
- Return a list of all of the Devices that have a Device Name which contains 'JASCO'
httpshttp://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&deviceCodedeviceName=NORTEKADCP9917 JASCO
- Return a list of all Devices of the devices that have a Device Name which contains 'JASCO'been deployed at a location with a Location Code of 'BACAX' ('Barkely Canyon Axis (POD1)')
httpshttp://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&deviceNamelocationCode=JASCO BACAX
- Return a list of all
...
- of the Devices with a Device Category of 'ADCP2MHZ'
https://data.oceannetworks.ca/api/devices?method=get&token=
...
...
...
...
- Return a list of all of the Devices with a Device CategoryProperty Code of 'ADCP2MHZoxygen'
httphttps://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&deviceCategoryCodepropertyCode=ADCP2MHZ oxygen
- Return a list of all of the Devices with a Device Category of 'CTD' and Property Code of 'oxygenpressure'
httphttps://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&deviceCategoryCode=CTD&propertyCode=oxygen pressure
- Return a list of all Devices with a Device Category of 'CTD' and Property Code of 'pressure'of the Devices that support the Data Product Code of 'IBPP' ('Ice Buoy Profile Plots')
httpshttp://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&deviceCategoryCode=CTD&propertyCode=pressure
- Return a list of all Devices that support the Data Product Code of 'IBPP' ('Ice Buoy Profile Plots')of the Devices that were Deployed Between July 1st 2010 and June 30th 2012
httpshttp://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&dataProductCode=IBPP
YOUR_TOKEN_HERE&dateFrom=2010-07-01T00:00:00.000Z&dateTo=2012-06-30T23:59:59.999Z
- Return a list of all of the Devices that were Devices Deployed Between 1 July July 1st 2010 and 30 June 2012June 30th 2011, at a location with a Location Code of 'BACAX' ('Barkely Canyon Axis (POD1)')
httpshttp://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&deploymentBegin&locationCode=BACAX&dateFrom=2010-07-01T00:00:00.000Z&deploymentEnddateTo=20122011-06-30T23:59:59.999Z
- Return a list of all of the Devices Deployed Between 1 July 2010 and 30 June 2011, at Devices which have a Property Code of 'seawatertemperature', at a location with a Location Code of 'BACAX' ('Barkely Canyon Axis (POD1)'), Deployed Between July 1st 2010 and June 30th 2011
httpshttp://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&locationCode=BACAX&deploymentBegindateFrom=2010-07-01T00:00:00.000Z&deploymentEnddateTo=2011-06-30T23:59:59.999Z &propertyCode=seawatertemperature
- Return a list of all of the Devices which have a Property Code of 'seawatertemperature', at devices that have been deployed at a location with a Location Code of 'BACAXBACCC' ('Barkely Canyon Axis (POD1)Coral Cliff') , Deployed Between 1 July 2010 and 30 June 2011and children locations
httpshttp://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&locationCode=BACAX&deploymentBegin=2010-07-01T00:00:00.000Z&deploymentEnd=2011-06-30T23:59:59.999Z&propertyCode=seawatertemperature =BACCC&includeChildren=true
API Proxy
The httphttps://data.oceannetworks.ca/apiproxy/devices url used devicesURL link in the above examples can be used in a browser for sharing or testing purposes; however, it can not be used accessed from code, as it redirects . Calls to the apiproxy server are redirected to a login screen to capture your user id. In 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 devices deployments endpoint from code, you must use the httphttps://data.oceannetworks.ca/api/devices url devices url along with a valid token. Attempting to use the apiproxy url from code will result html returned in the payload which may cause errors or unexpected behavior.
Code Examples
Content Report Table | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Warning |
---|
Please report all issues with the web services, documentation, samples and client libraries to the Oceans 3.0 Help Centre |