locations Discovery Service

Description

The locations discovery web service returns all locations defined in Oceans 2.0 which meet the 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 2.0 Tree Node, from which you can get data. In the Oceans 2.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 2.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

http://data.oceannetworks.ca/api/locations

method=getTree

 get

The get method retrieves a list of location names and location codes.

Parameters

Response

Example for request: http://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": "http://data.oceannetworks.ca/DataSearch?location=BACAX"
   }
]

"locationName":"Axis (POD 1)"

"locationCode":"BACAX"

"description":"Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biodiversity, sediment dynamics."

"hasDeviceData":"true

"hasPropertyData":"true"

"dataSearchURL":"http://dmas.uvic.ca/DataSearch?location=BACAX"

Bad Request (HTTP 400)

 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

Response

Response for request http://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]&locationCode=BACCC

Success (HTTP 200)

"locationName":"Axis (POD 1)"

"locationCode":"BACAX"

"children":[{...},{...},...]

"description":"Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biodiversity, sediment dynamics."

"hasDeviceData":"true

"hasPropertyData":"true"

"dataSearchURL":"http://dmas.uvic.ca/DataSearch?location=BACAX"

Bad Request (HTTP 400)

 URL Examples

• Return a list of All Locations (no filters)

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

• Return the Location with a Location Code of 'BACAX' ('Barkely Canyon Axis (POD1)')

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

• Return a list of all Locations at or below the Location Code of 'NEP' ('Northeast Pacific') in the Tree View 

http://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&locationCode=NEP&includeChildren=true

• This example returns the NEP location and all of its child locations, in a flat format. In the results obtained from making the request, look for "hasDeviceData" and "hasPropertyData" properties. These indicate whether property data and device data are available from that location. If both values are false, the location is a hierarchical tree node.

• Return a list of all Locations that have a Location Name containing the string 'underwater'

http://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&locationName=underwater

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

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

• Return a list of all Locations with a Property Code of 'differentialtemperature'

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

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

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

• Return a list of all Locations where a device with a Device Code of 'NORTEKAQDPRO8398' has been deployed

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

• Return a list of all Locations that have instruments that support the Data Product Code of 'IBPP' ('Ice Buoy Profile Plots')

http://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 2010 and 30 June 2012

http://dmas.uvic.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&deploymentBegin=2010-07-01T00:00:00.000Z&deploymentEnd=2012-06-30T23:59:59.999Z

• Return a list of all of the Locations which has instruments Deployed Between 1 July 2010 and 30 June 2011 with a sensor Property Code of 'seawatertemperature'

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

• Return the complete Oceans 2.0 Search Tree hierarchy

http://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]

or

http://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]&locationCode=ONC

• Return the Oceans 2.0 Search Tree hierarchy at or below the 'Mobile Platforms' node

http://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]&locationCode=MOBP

API Proxy

The http://data.oceannetworks.ca/apiproxy/deviceCategories 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 http://data.oceannetworks.ca/api/deviceCateogies url along with a valid token. 

Code Examples