The API devices returns all devices defined in Oceans 2.0 which meet a filter criteria.
Devices are instruments with one or more sensors that observe 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 service is to find devices that have the data you want to access; the service provides the deviceCode that can be used to request a data product via the dataProductDelivery web service.
For a list of available device codes, along with names, ids and device links, see the Available Devices page.
See External Web Services for method and token usage and error messages.
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. 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=5ba514e8-1203-428c-8835-879c8173e387 |
Optional | |||
deviceCode | string | Return a single Device matching a specific Device Code
| deviceCode=FSINXIC1622 |
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 |
deviceCategoryCode | string | Return all Devices belonging to a specific Device Category
| deviceCategoryCode=CTD |
propertyCode | string | Return all Devices that have a sensor for a specific Property
| propertyCode=pressure |
dataProductCode | string | Return all Devices that have the ability to return a specific Data Product
| dataProductCode=jpgfile |
deploymentBegin | datetime | Return all of the Devices that have a Deployment Beginning on or after a specific date/time
Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
| deploymentBegin=2010-07-27T00:00:00.000Z |
deploymentEnd | datetime | Return all of the Devices that have a Deployment Ending on or before a specific date/time
Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
| deploymentEnd=2016-08-01T00:00:00.000Z |
Example for request: https://data.oceannetworks.ca/api/devices?method=get&token=[YOUR_TOKEN_HERE]&deviceCategoryCode=ADCP2MHZ
Returns a list of devices with values for Device Code, Device Id, Device Name and Device Link URL, ordered by Device Code
[{ "deviceCode" : "BC_POD1_AD2M" , "deviceId" :11302, "deviceLink" : "https://data.oceannetworks.ca/DeviceListing?DeviceId=11302" , "deviceName" : "Nortek Aquadopp HR-Profiler 2965" , "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" : "https://data.oceannetworks.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" : "https://data.oceannetworks.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" : "https://data.oceannetworks.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" : "https://data.oceannetworks.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" : "https://data.oceannetworks.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" }], "cvTerm" : [{ "device" : [{ "vocabulary" : "SeaVoX Device Catalogue" , "uri" : "http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/" }] }] }, { "deviceCode" : "NORTEKAQDPRO8398" , "deviceId" :520, "deviceLink" : "https://data.oceannetworks.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/" }] }] }, { "deviceCode" : "NORTEKAQDPRO8455" , "deviceId" :23117, "deviceLink" : "https://data.oceannetworks.ca/DeviceListing?DeviceId=23117" , "deviceName" : "Nortek Aquadopp Profiler AQD 8455" , "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/" }] }] }, { "deviceCode" : "NTAquadoppHRCP2973" , "deviceId" :11203, "deviceLink" : "https://data.oceannetworks.ca/DeviceListing?DeviceId=11203" , "deviceName" : "Nortek Aquadopp HR-Profiler 2973" , "dataRating" : [{ "samplePeriod" :120.0, "dateFrom" , "2008-11-01 00:00:00" },{ "samplePeriod" :1.0, "dateFrom" , "2010-05-13 23:17:54" },{ "samplePeriod" :10.0, "dateFrom" , "2010-05-27 19:22:39" }], "cvTerm" : [{ "device" : [{ "vocabulary" : "SeaVoX Device Catalogue" , "uri" : "http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/" }] }] }, { "deviceCode" : "NTAquadoppHRCP2978" , "deviceId" :12003, "deviceLink" : "https://data.oceannetworks.ca/DeviceListing?DeviceId=12003" , "deviceName" : "Nortek Aquadopp HR-Profiler 2978" , "dataRating" : [{ "samplePeriod" :1.0, "dateFrom" , "2008-11-01 00:00:00" },{ "samplePeriod" :120.0, "dateFrom" , "2008-03-01 00:00:00" },{ "samplePeriod" :1.0, "dateFrom" , "2010-05-13 23:18:34" },{ "samplePeriod" :10.0, "dateFrom" , "2010-05-27 19:32:41" }], "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 |
deviceName | string | Returns the device name | "deviceName":"Nortek Aquadopp HR-Profiler 2965" |
deviceLink | url | Returns a URL link to the 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 Each data rating is made up of:
| "dataRating" : [ { "samplePeriod" : 1.0 , "dateFrom" : "2013-08-01 00:00:00" } ] |
cvTerm | list | 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" : [ { "device" : [ { "vocabulary" : "SeaVoX Device Catalogue" , } ] } ] |
errorCode | errorMessage | Description |
---|---|---|
23 | Invalid Time Range, Start Time is greater than End Time or start time is not provided | Occurs when the deploymentEnd is before the deploymentBegin date/time
|
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 deploymentBegin is used without deploymentEnd
|
129 | Invalid parameter name | Occurs when a filter parameter is used, 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]&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/devices 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/devices url along with a valid token.