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

Description

The deployments discovery web service returns all deployments defined in Oceans 2.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.


URL

https://data.oceannetworks.ca/api/deployments

get

Retrieve a flat list deployments metadata.

method=get

Method

Description

Example

get

The get method retrieves a list of deployments including location code, device code, deployment begin and end dates and spatial information.

Parameters

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


locationCodestring

Return all Deployments at a specific Location Code.

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

Return all Deployments that have devices belonging to a specific Device Category.

  • Device Category Code must be valid and match exactly, including case.
  • Specific Device Category Codes can be obtained using the deviceCategories service.
deviceCategoryCode=CTD
deviceCode string

Return all Deployments of a specific Device.

  • Device Code must be valid and match exactly, including case.
  • Specific Device Codes can be obtained from the devices service.
 deviceCode=AandOpt0581
propertyCodestring

Return all Deployments that have devices with a sensor for a specific Property.

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

Return all of the Deployments that have a Deployment Beginning on or after a specific date/time.

Accepted DateTime formats:

  • yyyy-MM-dd'T'HH:mm:ss.SSS'Z' (ISO 8601 Extended)
  • yyyy-MM-dd (ISO 8601 Extended)
  • PnYnMnDTnHnMnS (ISO 8601 Duration)

If not specified, the default value is the beginning of time.

  • DateTime is represented in Coordinated Universal Time (UTC).

  • ISO 8601 Extended format without a time will be assumed to mean midnight (T00:00:000.000Z).
  • Queries with both dateFrom and dateTo in the ISO 8601 Duration format will not be accepted.

dateFrom=2010-07-27T00:00:00.000Z

dateFrom=2010-07-27

dateFrom=-P1DT1H

  • Previous 1 day and 1 hour, relative to the dateTo. Note the '-' before the P.
dateTodatetime

Return all of the Deployments that have a Deployment Ending before a specific date/time.

Accepted DateTime formats:

  • yyyy-MM-dd'T'HH:mm:ss.SSS'Z' (ISO 8601 Extended)
  • yyyy-MM-dd (ISO 8601 Extended)
  • PnYnMnDTnHnMnS (ISO 8601 Duration)

If not specified, the default value is the end of time.

  • DateTime is represented in Coordinated Universal Time (UTC).

  • ISO 8601 Extended format without a time will be assumed to mean midnight (T00:00:000.000Z).
  • Queries with both dateFrom and dateTo in the ISO 8601 Duration format will not be accepted.

dateTo=2016-08-01T00:00:00.000Z

dateTo=2016-08-01

dateTo=PT12H30M

  • Next 12 hours and 30 minutes, relative to the dateFrom.
Parameter
Type
Description
Example

Response

Example for request: https://data.oceannetworks.ca/api/deployments?method=get&token=[YOUR_TOKEN_HERE]&locationCode=BACAX&deviceCategoryCode=CTD

Success (HTTP 200)

Returns a list of locations with values for Location Code, Location Name, Description, Device Data indicator, Property Data indicator, and Data Search Link URL, ordered by Location Code


[
{
"begin": "2014-05-09T15:50:42.000Z",
"depth": 982,
"deviceCode": "SBECTD16p6002",
"end": "2015-09-17T12:59:52.000Z",
"hasDeviceData": true,
"heading": null,
"lat": 48.31658,
"locationCode": "BACAX",
"lon": -126.0508,
"pitch": null,
"roll": null
},
{
"begin": "2013-09-10T16:08:33.000Z",
"depth": 985,
"deviceCode": "SBECTD16p7031",
"end": "2014-05-05T18:08:36.000Z",
"hasDeviceData": true,
"heading": null,
"lat": 48.316517,
"locationCode": "BACAX",
"lon": -126.05022,
"pitch": null,
"roll": null
},
{
"begin": "2016-06-14T08:58:41.000Z",
"depth": 982,
"deviceCode": "SBECTD19p6813",
"end": null,
"hasDeviceData": true,
"heading": null,
"lat": 48.31658,
"locationCode": "BACAX",
"lon": -126.0508,
"pitch": null,
"roll": null
}
]

locationCodestringThe locationCode for the deployment location.
"locationCode":"BACAX"
deviceCodestringThe deviceCode for a deployed device.
"deviceCode":"SBECTD19p6813"
begindatetime

The beginning datetime of the deployment.

Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

"begin":2010-07-27T00:00:00.000Z
enddatetime

The ending datetime of the deployment.

  • If the deployment is current, the value is null.

Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

"end":2016-08-01T00:00:00.000Z

hasDeviceData

stringIndicates that data products can be requested using a device category code for the deployment.
"hasDeviceData":"true
depthdoubleThe depth of the device deployment."depth":982
latdouble

The latitude of the device deployment.

"lat":48.31658
londoubleThe longitude of the device deployment."lon":-126.0508
headingdoubleThe heading of the device deployment."heading":244
pitchdoubleThe pitch of the device deployment."pitch":null
rolldoubleThe pitch of the device deployment."roll":null
Property
Type
Description
Example

Bad Request (HTTP 400)

23Invalid Time Range, Start Time is greater than End Time or start time is not provided

Occurs when the end is before the begin date/time.

  • The name of both of the datetime filters are included in the parameter property.
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 is included in the parameter property.
128Missing parameter

Occurs when multiple parameters are needed, but not all are present. Occurs when deploymentBegin is used without deploymentEnd.

  • The names of the required filter parameters, separated by /, are included in the parameter property.
129Invalid parameter name

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

errorCode
errorMessage
Description


 URL Examples

  • Return a list of All Deployments (no filters)

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


  • Return a list of all Deployments with a Location Code of 'BACAX' ('Barkely Canyon Axis (POD1)')

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

  

  • Return a list of all Deployments that have devices with the Device Category 'ADCP2MHZ'

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


  • Return a list of all Deployments with the Property Code 'differentialtemperature'

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


  • Return a list of all Deployments with the Device Category 'CTD' and Property Code 'pressure'

https://data.oceannetworks.ca/api/deployments?method=get&token=[YOUR_TOKEN_HERE]&deviceCategoryCode=CTD&propertyCode=pressure


  • Return a list of all Deployments of a device with the Device Code 'NORTEKAQDPRO8398'

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


  • Return a list of all of the Deployments Between 1 July 2010 and 30 June 2012

https://data.oceannetworks.ca/api/deployments?method=get&token=[YOUR_TOKEN_HERE]&dateFrom=2010-07-01T00:00:00.000Z&dateTo=2012-06-30T23:59:59.999Z


  • Return a list of all Deployments Between 1 July 2010 and 30 June 2011 with the sensor Property Code 'seawatertemperature'

https://data.oceannetworks.ca/api/deployments?method=get&token=[YOUR_TOKEN_HERE]&dateFrom=2010-07-01T00:00:00.000Z&dateTo=2011-06-30T23:59:59.999Z&propertyCode=seawatertemperature


API Proxy

The https://data.oceannetworks.ca/apiproxy/deployments 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 deployments endpoint from code, you must use the https://data.oceannetworks.ca/api/deployments url along with a valid token. 

Code Examples

TitleCreatorModified
Python Client LibraryRyan Ross16-Aug-19
Research Use CaseRyan Ross23-May-18
Ouranos Use CaseAllan Rempel25-Apr-18
Bird Studies Canada Use CaseAllan Rempel24-Apr-18
Internal Use CaseRyan Ross24-Apr-18
Request Data ProductRyan Ross23-Apr-18
Discover Device CategoriesRyan Ross23-Apr-18
Discover DeploymentsRyan Ross23-Apr-18
Discover DevicesRyan Ross23-Apr-18
Discover LocationsRyan Ross23-Apr-18
Discover Data ProductsRyan Ross26-Sep-17
Discover PropertiesRyan Ross26-Sep-17



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

  • No labels