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.
http://data.oceannetworks.ca/api/locations |
Method | Description | Example |
---|---|---|
get | Retrieve a flat list locations metadata. |
|
getTree | Retrieve a Search Tree Node hierarchy of locations. | method=getTree |
The get method retrieves a list of location names and location codes.
Parameter | Type | Description | Example |
---|---|---|---|
Required | |||
token | string | All Web Services require a token. Once logged in at http://data.oceannetworks.ca/login, your token can be retrieved or generated at http://data.oceannetworks.ca/Profile. Click on the "Web Services" tab, then click "Generate Token". | token=5ba514e8-1203-428c-8835-879c8173e387 |
Optional | |||
locationCode | string | Return a single Location matching a specific Location Code
| locationCode=BACAX |
locationName | string | Return all of the Locations where the Location Name contains a keyword.
| locationName=mill |
deviceCategoryCode | string | Return all Locations that have devices belonging to a specific Device Category
| deviceCategoryCode=CTD |
deviceCode | string | Return all of the Locations where a specific Device has been deployed.
| deviceCode=AandOpt0581 |
propertyCode | string | Return all Locations that have devices with a sensor for a specific Property.
| propertyCode=differentialtemperature |
dataProductCode | string | Return all of the Locations that support a specific Data Product.
| dataProductCode=CPID |
deploymentBegin | datetime | Return all of the Locations 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 Locations 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 |
includeChildren | bool | Include all of the children of a location in the results.
| includeChildren=true |
Example for request: http://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&locationCode=BACAX
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" } ] |
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":"http://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 } |
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. |
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.
Parameter | Type | Description | Example |
---|---|---|---|
Required | |||
token | string | All Web Services require a token. Once logged in at http://data.oceannetworks.ca/login, your token can be retrieved or generated at http://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 |
Response for request http://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]&locationCode=BACCC
[ { "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 |
---|---|---|---|
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" |
dataSearchURL | string | The location specific Data Search web page URL | "dataSearchURL":"http://dmas.uvic.ca/DataSearch?location=BACAX" |
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 used, but is not supported. |
http://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]
http://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&locationCode=BACAX
http://data.oceannetworks.ca/api/locations?method=get&token=[YOUR_TOKEN_HERE]&dataProductCode=IBPP
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
http://data.oceannetworks.ca/api/locations?method=getTree&token=[YOUR_TOKEN_HERE]&locationCode=MOBP
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.