You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

Description

The locations discovery web service returns all the locations defined in DMAS which meet the filter criteria.

A location is the parent of a DMAS Tree Node that you can get data from. 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 DMAS perspective, a location is a Search Tree Nodes 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.

The primary purpose for 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.

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

Description

Example

get

Retrieve a flat list locations metadata

method=get

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   
tokenstringAll Web Services require a token. This can be generated at http://dmas.uvic.ca/Profile. Click on the "Web Services" tab and click "Generate Token"token=5ba514e8-1203-428c-8835-879c8173e387
Optional   
locationCodestring

Return a single Location matching a specific Location Code

  • Location Code must be valid and match exactly, including case
  • Specific Location Codes can be found by simply running the service without this parameter to get a list of all locations
locationCode=BACAX
locationNamestring

Return all of the Locations where the Location Name contains a keyword

  • Not case sensitive
  • Contains
locationName=mill
deviceCategoryCodestring

Return all Locations 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 deviceCateogries service
deviceCategoryCode=CTD
deviceCode string

Return all of the Locations where a specific Device has been deployed.

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

Return all Locations 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
dataProductCodestring

Return all of the 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
dataProductCode=CPID
deploymentBegindatetime

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

  • Requires deploymentEnd

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

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

deploymentEnddatetime

Return all of the Locations that have a Deployment Ending on or before a specific date/time

  • Requires deploymentBegin

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

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

includeChildrenbool

Include all of the children of a location in the results

  • Requires a valid locationCode
  • Valid values are either true or false
includeChildren=true

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

 

[
   {"locationName":"Axis (POD 1)",
    "description":"Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform Description: Canyon axis: benthic processes, biodiversity, sediment dynamics.",
    "hasDeviceData":"true",
    "locationCode":"BACAX",
    "hasPropertyData":"true",
    "dataSearchURL":"http://dmas.uvic.ca/DataSearch?location=BACAX"
   }
]
Property
Type
Description
Example
locationNamestringThe name of the location
"locationName":"Axis (POD 1)"
locationCodestringThe locationCode for that location.
"locationCode":"BACAX"
descriptionstringThe 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

stringIndicates that data products can be requested using a device category code for the location
"hasDeviceData":"true
hasPropertyDatastringIndicates that data products can be requested using a property code for the location
"hasPropertyData":"true"
dataSearchURLstringThe location specific Data Search web page URL
"dataSearchURL":"http://dmas.uvic.ca/DataSearch?location=BACAX"

Bad Request (HTTP 400)

errorCode
errorMessage
Description
23Invalid Time Range, Start Time is greater that End Time or start time is not provided

Occurs when the deploymentEnd is before the deploymentBegin date/time.

  • The name of both of the datetime filters will be 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 will be 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 will be included in the "parameter" property separated by /
129Invalid 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 the instruments or properties they are interested in. 

Parameters

Parameter
Type
Description
Example
Required   
tokenstringAll Web Services require a token. This can be generated at http://dmas.uvic.ca/Profile. Click on the "Web Services" tab and click "Generate Token"token=5ba514e8-1203-428c-8835-879c8173e387
Optional   
locationCodestring

A valid locationCode is needed. One can be found by simply running the service without this parameter to get a list of all locations

  • Code must match exactly, including case
locationCode=BACAX

 

Response

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

Success (HTTP 200)

 

[
   {"locationName":"Coral Cliff",
    "children":[{"locationName":"ADCP 2 MHz West",
                    "children":null,
                    "description":"Depth: 807 m Latitude: 48.3104 Longitude: -126.0623 Type: Autonomous platform Description: Boundary layer flow near steep bathymetry, interaction of currents and deep-sea corals.",
                    "hasDeviceData":"true",
                    "locationCode":"BACCC.A2",
                    "hasPropertyData":"false"},
                {"locationName":"ADCP 2 MHz East",
                    "children":null,
                    "description":"Depth: 824 m Latitude: 48.3098 Longitude: -126.0621 Type: Autonomous platform Description: Boundary layer flow near steep bathymetry, interaction of currents and deep-sea corals.",
                    "hasDeviceData":"true",
                    "locationCode":"BACCC.A1",
                    "hasPropertyData":"false"}],
    "description":"Depth: 816 m Latitude:48.3101 Longitude: -126.0622 Type: Autonomous platform Description: Boundary layer flow near steep bathymetry, interaction of currents and deep-sea corals.",
    "hasDeviceData":"false",
    "locationCode":"BACCC",
    "hasPropertyData":"true"
   }
]
Property
Type
Description
Example
locationNamestringThe name of the location
"locationName":"Axis (POD 1)"
locationCodestringThe locationCode for that location.
"locationCode":"BACAX"
childrenlistA list of all child nodes for the location. Each child node contains all of the available parameters
"children":[{...},{...},...]
descriptionstringThe 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

stringIndicates that data products can be requested using a device category code for the location
"hasDeviceData":"true
hasPropertyDatastringIndicates that data products can be requested using a property code for the location
"hasPropertyData":"true"
dataSearchURLstringThe location specific Data Search web page URL
"dataSearchURL":"http://dmas.uvic.ca/DataSearch?location=BACAX"

Bad Request (HTTP 400)

errorCode
errorMessage
Description
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 will be included in the "parameter" property
129Invalid parameter name

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

 

 URL Examples

  • Return a list of All of the 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 of the Locations including and below a location in the Tree View, with a Location Code of 'NEP' ('Northeast Pacific')

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 it's child locations, in a flat format. The "hasDeviceData" and "hasPropertyData" properties 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 a Location Name which contains 'underwater'

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

  

  • Return a list of all of the 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 of the 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 of the 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 of the 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 of the 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 July 1st 2010 and June 30th 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 July 1st 2010 and June 30th 2011 with a sensor for 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 DMAS 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 DMAS Search Tree hierarchy from the 'Mobile Platforms' node and below

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

 

*NOTE: The http://data.oceannetworks.ca/apiproxy/locations url used in the above examples can be used in a browser for sharing and testing purposes; however, it can not be used from code, as it redirects to a login screen to capture your user id. In order to use the locations endpoint from code, you must use the http://data.oceannetworks.ca/api/locations 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

TitleCreatorModified
Ouranos Use CaseAllan Rempel26-Feb-22
Bird Studies Canada Use CaseAllan Rempel26-Feb-22
Internal Use CaseRyan Ross26-Feb-22

  • No labels