Table of Contents
Description
The locations discovery API locations discovery web service returns all the locations defined in Oceans 23.0 which that meet the a set of filter criteria.
The primary purpose for the locations service is to find locations that have the data you are interested in and use the locationCode when requesting a data product using the dataProductDelivery web service.
A location is the parent of an Oceans 23.0 Tree Node , from which you can get data. In the Oceans 23.0 Data Search GUI, a location is a Tree Node that contains device categories (Instruments by Location) or properties (Variables by Location) that can be selected to download data. From the Oceans 23.0 perspective, a location is a Search Tree Node that has one or more site devices and/or has one or more primary sensors. If there are multiple instruments of the same device category at a location, child - locations or pseudo-nodes will exist and can be pulled from any one of them. Device Categories can be either at the location or at the child-level, whereas Properties (variables) can only be at the location level, due to the '"Primary Sensor' " concept, which stitches together data from multiple sensors over time at a location.
For a list of available location codes, along with names and descriptions, see the Available Locations page.
See the External Web Services for method and token usage and error messages.
URL
...
The primary purpose for the locations service is to find locations that have the data you are interested in and use the locationCode when requesting a data product using the dataProductDelivery web service.
URL
https://data.oceannetworks.ca/api/locations
Method | Description | Example |
---|---|---|
get | Retrieve a flat list of locations metadata |
| |
getTree | Retrieve a Search Tree Node hierarchy of locations |
method=getTree |
get
The get method retrieves a list of location names and location codes.
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 |
---|
locationCode | string | Return a single Location matching a specific Location Code.
|
| locationCode=BACAX |
deviceCategoryCode | string | Return all |
- Filter is not case sensitive, treating mill, Mill and MILL as the same word.
- Filter will find partial words. The filter locationName=island returns "Digby Island Underwater Network", "Digby Island Shore Station", "Finlayson Islands", "Quadra Island" and more.
Locations that have devices with a specific Device Category Code.
| deviceCategoryCode=CTD |
propertyCode |
string | Return all Locations that have devices |
with a sensor with a specific |
Property Code.
|
|
|
propertyCode= |
differentialtemperature |
dataProductCode |
string | Return all of the Locations |
that support a specific |
Data Product Code. |
|
|
|
dataProductCode= |
CPID |
dateFrom |
datetime | Return all of the Locations that have |
- Property Code must be valid and match exactly, including case.
- Specific Property Codes can be obtained using the properties service.
Return all Locations that support a specific Data Product.
- Data Product Code must be valid and match exactly, including case.
- Specific Data Product Codes can be obtained from the dataProducts service.
Return all Locations that have a Deployment Beginning on or after a specific date/time.
- When the depolymentBegin filter is included, the deploymentEnd filter must also be included.
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 Locations that have a Deployment Ending before a specific date/time. Accepted DateTime formats: |
|
DateTime is represented in Coordinated Universal Time (UTC)
deploymentBegin=2010-07-27T00:00:00.000Z
Return all Locations 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
Include all children of a location in the results.
- Requires a valid locationCode.
- Valid values are either true or false and must match exactly.
Response
Example for request: https://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&locationCode=BACAX
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
[
{
"deployments": 50,
"locationName": "Axis ",
"depth": 984.3076,
"bbox": {
"maxDepth": 987,
"maxLat": 48.316837,
"maxLon": -126.050125,
"minDepth": 981,
"minLat": 48.316517,
"minLon": -126.05087
},
"description": "Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biodiversity, sediment dynamics.",
"hasDeviceData": "true",
"lon": -126.05033,
"locationCode": "BACAX",
"hasPropertyData": "true",
"lat": 48.31669,
"dataSearchURL": "https://data.oceannetworks.ca/DataSearch?location=BACAX"
}
] |
Property | Type | Description | Example |
---|---|---|---|
locationName | string | The name of the location | "locationName":"Axis (POD 1)" |
locationCode | string | The locationCode for the location. | "locationCode":"BACAX" |
description | string | The description of the location | "description":"Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biodiversity, sediment dynamics." |
hasDeviceData | string | Indicates that data products can be requested using a device category code for the location | "hasDeviceData":"true |
hasPropertyData | string | Indicates that data products can be requested using a property code for the location | "hasPropertyData":"true" |
dataSearchURL | string | The location specific Data Search web page URL | "dataSearchURL":"https://dmas.uvic.ca/DataSearch?location=BACAX" |
deployments | integer | number of deployments | "deployments" : 10 |
depth | double | average depth of deployments | "depth" : 75 |
lat | double | average latitude of deployments | "lat" : 48.47672 |
lon | double | average longitude of deployments | "lon" : - 123.294902 |
bbox | Object | bounding box of site devices at location for device that pass filters | "bbox" : { "maxDepth" : 100 , "maxLat" : 48.476740 , "maxLon" : - 123.294904 , "minDepth" : 50 , "minLat" : 48.47670 , "minLon" : - 123.294900 } |
Bad Request (HTTP 400)
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. |
getTree
The getTree method returns a hierarchical representation of the ONC Search Tree Nodes. The Search Tree is used in Oceans 2.0 to organize Instruments and Variables by Location so that users can easily drill down by place name or mobile platform name to find instruments or properties of interested.
Parameters
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 | |||
locationCode | string | A valid locationCode is needed. Run the service without this parameter to get a list of all locations.
| locationCode=BACAX |
...
If not specified, the default value is the end of time.
| dateTo=2016-08-01T00:00:00.000Z dateTo=2016-08-01 dateTo=PT12H30M
| ||
locationName | string | Return all of the Locations where the Location Name contains a keyword.
| locationName=mill |
deviceCode | string | Return all of the Locations where a specific device with that Device Code has been deployed.
| deviceCode=AandOpt0581 |
includeChildren | bool | Return all Devices that are deployed at a specific Location and sub-tree Locations.
| includeChildren=true |
Response
Example for request: https://data.oceannetworks.ca/api/locations?method=get&token=YOUR_TOKEN_HERE&locationCode=BACAX
Success (HTTP 200)
Returns a list of locations with values for Location Code, Location Name, Description, Device Data indicator, Property Data indicator, bounding box, and Data Search Link URL, ordered by Location Code
|
Property | Type | Description | Example |
---|---|---|---|
locationName | string | The name of the location | "locationName":"Axis (POD 1)" |
locationCode | string | The locationCode for that location. | "locationCode":"BACAX" |
description | string | The description of the location | "description":"Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biodiversity, sediment dynamics." |
hasDeviceData | string | Indicates that data products can be requested using a device category code for the location | "hasDeviceData":"true" |
hasPropertyData | string | Indicates that data products can be requested using a property code for the location | "hasPropertyData":"true" |
dataSearchURL | string | The location specific Data Search web page URL | "dataSearchURL":"https://data.oceannetworks.ca/DataSearch?location=BACAX" |
deployments | integer | Number of deployments | "deployments" : 10 |
depth | double | Average depth of deployments (in meters below the water surface) | "depth" 984.164314 |
lat | double | Average latitude of deployments (in degrees north of the equator) | "lat" : 48.47672 |
lon | double | Average longitude of deployments (in degrees east of the prime meridian) | "lon" : - 123.294902 |
bbox | object | Bounding box of site devices at location for device that pass filters |
|
| double | Maximum depth in meters below water surface (negative numbers denote above) | "maxDepth":987.0 |
| double | Maximum latitude in degrees north of the equator (negative numbers denote south) | "maxLat":48.316839 |
| double | Maximum longitude in degrees east of the prime meridian (negative numbers denote west) | "maxLon":-126.050123 |
| double | Minimum depth in meters below water surface (negative numbers denote above) | "minDepth":981.0 |
| double | Minimum latitude in degrees north of the equator (negative numbers denote south) | "minLat":48.316517 |
| double | Minimum longitude in degrees east of the prime meridian (negative numbers denote west) | "minLon":-126.050872 |
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.
|
getTree
The getTree method returns a hierarchical representation of the ONC Search Tree Nodes. The Search Tree is used in Oceans 3.0 to organize Instruments and Variables by Location so that users can easily drill down by place name or mobile platform name to find the instruments or properties they are interested in.
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 | |||
locationCode | string | Return a single Location matching a specific Location Code.
| locationCode=BACAX |
deviceCategoryCode | string | Return all Locations that have devices with a specific Device Category Code.
| deviceCategoryCode=CTD |
propertyCode | string | Return all Locations that have devices with a sensor with a specific Property Code.
| propertyCode=differentialtemperature |
dataProductCode | string | Return all of the Locations that support a specific Data Product Code.
| dataProductCode=CPID |
dateFrom | datetime | Return all of the Locations 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 Locations 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
|
locationName | string | Return all of the Locations where the Location Name contains a keyword.
| locationName=mill |
deviceCode | string | Return all of the Locations where a specific device with that Device Code has been deployed.
| deviceCode=AandOpt0581 |
Response
Response for request https://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]&locationCode=BACCC
Success (HTTP 200)
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
Property | Type | Description | Example |
---|---|---|---|
locationName | string | The name of the location | "locationName":"Axis (POD 1)" |
locationCode | string | The locationCode for that location. | "locationCode":"BACAX" |
children | list | A list of all child nodes for the location. Each child node contains all of the available parameters | "children":[{...},{...},...] |
description | string | The description of the location | "description":"Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biodiversity, sediment dynamics." |
hasDeviceData | string | Indicates that data products can be requested using a device category code for the location | "hasDeviceData":"true" |
hasPropertyData | string | Indicates that data products can be requested using a property code for the location | "hasPropertyData": |
"true" |
Bad Request (HTTP 400)
errorCode | errorMessage | Description |
---|---|---|
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.
|
129 | Invalid parameter name | Occurs when a filter parameter is |
in the query but is not supported. |
...
|
Examples
- Return a list of All Locations of the Locations (no filters)
https://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]
...
- Return the Location with the a Location Code of 'BACAX' ('Barkely Canyon Axis (POD1)')
https://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&locationCode=BACAX
- Return a list of all of the Locations at or below the Location Code including and below a location in the Tree View, with a Location Code of 'NEP' ('Northeast Pacific') in the Tree View )
- This example returns the NEP location and all of its
- it's child locations, in a flat format. In the results obtained from making the request, look for
- The "hasDeviceData" and "hasPropertyData" properties . These indicate whether property data and device data are available from
- in the results indicate if there is data at that location. If both values are false, the location is a hierarchical tree node.
...
- Return a list of all of the Locations that have the a Location Name containing the string which contains 'underwater'
- Return a list of all of the Locations that have devices with a Device Category Code of 'ADCP2MHZ'
- Return a list of all of the Locations with a Property Code of 'differentialtemperature'
- Return a list of all of the Locations with a Device Category Code of 'CTD' and Property Code of 'pressure'
- Return a list of all of the Locations where a device with with a Device Code of 'NORTEKAQDPRO8398' has been deployed
- Return a list of all of the Locations that have instruments that support the Data Product Code of 'IBPP' ('Ice Buoy Profile Plots')
https://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&dataProductCode=IBPP
- Return a list of all of the Locations that have instruments that were Deployed Between 1 July July 1st 2010 and 30 June 30th 2012
https://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&deploymentBegindateFrom=2010-07-01T00:00:00.000Z&deploymentEnddateTo=2012-06-30T23:59:59.999Z
- Return a list of all of the Locations that have which has instruments Deployed Between 1 July July 1st 2010 and 30 June 30th 2011 with the a sensor with the Property Code of 'seawatertemperature'
https://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&deploymentBegindateFrom=2010-07-01T00:00:00.000Z&deploymentEnddateTo=2011-06-30T23:59:59.999Z&propertyCode=seawatertemperature
- Return the complete Oceans 2.0 DMAS Search Tree hierarchy
https://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]
or
https://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]&locationCode=ONC
- Return the Oceans 2.0 DMAS Search Tree hierarchy at or below from the 'Mobile Platforms' node and below
https://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]&locationCode=MOBP
API Proxy
The https://data.oceannetworks.ca/apiproxy/locations 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 behaviourbehavior. In order to use the deviceCategories deployments endpoint from code, you must use the https://data.oceannetworks.ca/api/locations url along with a valid token.
...
Content Report Table | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Warning |
---|
Please report all issues with the web services, documentation, samples and client libraries to the Oceans 3.0 Help Centre |