technical specifications for accessing water level web ... - spine... · watel level web services...

Technical specifications for accessing Water Level Web Services

Version 2.0.3

September 2014

Canadian Hydrographic Service

Fisheries and Oceans Canada

Watel level web services version 2.0.3

Canadian Hydrographic Service of 14

Contents

Introduction .................................................................................................................................................................... 3

Access and support ......................................................................................................................................................... 3

Addresses ........................................................................................................................................................................ 3

Technologies ................................................................................................................................................................... 3

Available Methods .......................................................................................................................................................... 4

getStatus ............................................................................................................................................................... 4

getName .................................................................................................................................................................... 4

getInfo .................................................................................................................................................................... 4

getVersion ............................................................................................................................................................. 4

getBoundaryDate ................................................................................................................................................. 4

getBoundaryDepth .............................................................................................................................................. 4

getBoundarySpatial ......................................................................................................................................... 4

getDataInfo .......................................................................................................................................................... 4

getMetadata .......................................................................................................................................................... 5

getMetadataInfo ................................................................................................................................................. 7

search ...................................................................................................................................................................... 7

Examples of calls to method search .................................................................................................................... 8

interpolate .......................................................................................................................................................... 9

References .................................................................................................................................................................... 10

Appendix A – Class Diagram of the WDS Standard ....................................................................................................... 11

ResultSet ............................................................................................................................................................. 11

Appendix B – Class Diagram of Method interpolate of web service SPINE .......................................................... 12

ResultSpine ........................................................................................................................................................ 12

DataSpine ............................................................................................................................................................. 13

Appendix C – Error Messages ....................................................................................................................................... 14



Introduction

This document describes three web services giving direct access to water levels measured and calculated by

the Canadian Hydrographic Service (CHS) of Fisheries and Oceans Canada.

The service web de prévisions et d’interpolation des niveaux d’eau (water level forecast and interpolation

web service - also called SPINE) is a system allowing one to obtain water levels at any time on the St.

Lawrence navigation channel between Saint-Joseph-de-la-Rive and the Port of Montréal.

The observations web service offers water level observations collected by a network of tide and water level

gauges deployed along the St. Lawrence River, its estuary and its gulf.

The predictions web service offers water level predictions for over 800 coastal locations all over Canada.

Access and support

Access to the web services is available to general public, free of charge. Further information can be obtained

by communicating with the Canadian Hydrographic Service at [email protected]. This address should

also be used to get support for using the CHS’s web services.

Notice that the CHS will not provide any additional information on auxiliary environmental data, such as

water temperature, salinity nor atmospheric pressure. Requests of information on water level data will

answered as soon as possible, within current CHS level of service.

Meteorological conditions can cause differences (time and height) between the predicted and the observed

tides. These differences are mainly the result of atmospheric pressure changes, strong prolonged winds or

variations of freshwater discharge.

Addresses

The web service entry points are :

SPINE web service: https://ws-shc.qc.dfo-mpo.gc.ca/spine

observations web service: https://ws-shc.qc.dfo-mpo.gc.ca/observations

predictions web service: https://ws-shc.qc.dfo-mpo.gc.ca/predictions

Technologies

All three web services use SOAP and XML and communicate in English. Each service has a WSDL

description (i.e. : https://ws-shc.qc.dfo-mpo.gc.ca/predictions?wsdl) to help generate code using tools such

WSDL2Java from Apache Axis.

Furthermore, each service faithfully respects the Web Data Service WDS standard established by the St.

Lawrence Global Observatory (SLGO). Details about the WDS standard can be found at:

http://weds.sourceforge.net/cookbook/en/index.html

mailto:[email protected]

https://ws-shc.qc.dfo-mpo.gc.ca/spine

https://ws-shc.qc.dfo-mpo.gc.ca/observations

https://ws-shc.qc.dfo-mpo.gc.ca/predictions

https://ws-shc.qc.dfo-mpo.gc.ca/predictions?wsdl




Available Methods

The WDS standard describes ten methods offering information about the service itself and one method to

search data. The detailed description of each method and its objects are available on the WDS standard

website.

Exceptionally, the SPINE web service adds one search method called interpolate that is described later

in this section.

getStatus

Gives the status of the web service. With the WDS up and running, the status should read « ok », and when

something is wrong the status gives « error ».

getName

Gives the name of the web service.

getInfo

Gives the description of the web service.

getVersion

Gives the version number of WDS standard used by the web service.

getBoundaryDate

Gives the time interval data is available for (all dates and times are in UTC).

It is important to note that a search with temporal limits outside this time interval will not result in an error but

an empty set.

getBoundaryDepth

Gives the depth interval data is available for. Water levels are always considered to be at the surface and

thus at a depth of zero (0.0). Values are in meters.

The observation web service is the only service for which depth values have a meaning. Temperature and

salinity are taken under the surface and require depth values when searching for them. However,

atmospheric pressure are taken above the surface and also have depths of zero (0.0).

It is important to note that a search with depth limits outside this depth interval will not result in an error but

an empty set.

getBoundarySpatial

Gives the latitudes and longitudes inside of which data is available. Latitude and longitude values are in

decimal degrees and follow the ISO 6709 standard (a positive latitude is North, a positive longitude is East).

It is important to note that a search with spatial limits outside this bounding box will not result in an error but

an empty set.

getDataInfo

Gives the list of data type and their description.



SPINE has a single value :

spine : water level forecast in meters

Observations has four values :

wl : water level in meters

sal : water salinity in parts per thousand (‰)

temp : water temperature in Celcius degree

atm_pres : atmospheric pressure in millibars

Note : environment data (sal, temp, den et atm_pres) are available only as is and no quality control has been

done. Additional information on those data will not be supplied.

Prédictions has two values :

hilo : water levels of high tides and low tides

wl15 : water levels each 15 minutes ( :00, :15, :30 et :45)

The predictions web service only offers water levels predictions. Consequently, Tidal bores (Moncton et

Truro) and slack waters (Reversing Falls) are not available through this service.

One of these values must be given as the first parameter of its respective web service method search.

getMetadata

Gives a list of metadata alongside their values.

SPINE has six (6) metadata :

Name of the metadata Value

contact Gives information about the person to contact in case of trouble.

language Gives the language of messages exchanged between the server and the client.

name Gives the name of the web service.

abstract Gives the description of the web service.

reference_date Gives a textual representation of temporal limits. A more standard way is

to call getBoundaryDate.

max_results Gives the maximum number of elements returned by a query to

interpolate.

Observations has eleven (11) metadata:


station_id_list Gives the list of tidal gauge ids, each id separated by a comma :

03057,03071,03100,…

station_id_position Gives the list of tidal gauge ids alongside their geographical coordinates.

These three values are separated by comma and decorated with square

brackets : [15520,45.5035,-73.5525][15540,45.5286667,73.5424444]….




language Gives the language of messages exchanged between the server and the

client.





station_id_name_list Gives the list of tidal gauge ids alongside their names. These two values

are separated by two semi-colon and decorated by square brackets :

[15520;;Montréal, Jetée no 1][15540;;Montréal, rue Frontenac]…

metadata_selection_accepted Gives the list of metadata fields allowed in method search, each

separated by a comma. For more information, please consult the WDS

standard and look for parameter metadataSelection in method search.

max_rows Gives the maximum number of elements returned by a call to method

search.

total_nbr_obs Gives the number of data points in the database.

Predictions has twelve (12) metadata:



date Gives the date the web service came online

language Gives the language of messages exchanged between the server and the

client.

topic Gives the topic of the web service





station_id_list Gives the list of tidal gauge ids, each id separated by a comma :

03057,03071,03100,…

station_id_position Gives the list of tidal gauge ids alongside their geographical coordinates.

These three values are separated by comma and decorated with square

brackets : [15520,45.5035,-73.5525][15540,45.5286667,73.5424444]….

station_id_name_list Gives the list of tidal gauge ids alongside their names. These two values

are separated by two semi-colon and decorated by square brackets :



[15520;;Montréal, Jetée no 1][15540;;Montréal, rue Frontenac]…

metadata_selection_accepted Gives the list of metadata fields allowed in method search, each

separated by a comma. For more information, please consult the WDS

standard and look for parameter metadataSelection in method search.

max_rows Gives the maximum number of elements returned by a call to method

search.

getMetadataInfo

Gives a list describing the each metadata.

It is important to note that there are three levels of metadata :

Service level metadata and given by method getMetadata.

Result level metadata, metadata about the set of data given by a search.

Data level metadata, metadata about a single value.

search

Makes a search and gives back data points and their metadata inside an object of type ResultSet (see

Appendix A).

This method requires many parameters: one data type, one spatial interval, one depth interval, one temporal

interval, the 1-based index for the start of the data, the number of data, the flag to include data-level

metadata, the metadata selection and the sort order (example are given later).

This method is available in SPINE but has been deprecated, use interpolate instead.

Data from observations and predictions have the following metadata to help identify them :

metadata : the metadata array :

station_id : the unique station id (i.e : 02985)

station_name : the name of the station (i.e. : Rimouski)

vl : validation level (observations only)

o 0 = invalid data, the data has not been subject to any validation test, it is the raw

data from the tidal gauge.

o 1 = valid data, the data has passed basic tests.

o 2 = certified data, the data has passed extensive tests.

These data-level metadata can be used as value to parameter metadataSelection (i.e. station_id=02985

or again station_name=Rimouski). Examples are given later.

Furthermore, it is possible to use metadata vl with operator + and – when using it as parameter

metadataSelection to select data at multiple levels (i.e vl=1+ would give data at level 1 and 2).



Examples of calls to method search

Prédiction EXAMPLE 1

search("hilo", 47.5, 47.7, -61.6, -61.4, 0.0, 0.0, "2012-02-01

00:00:00", "2012-02-01 23:59:59", 1, 100, true, "", "asc")

Searches all the high tides and all the low tides in the northwest of the Îles-de-la-Madeleine

on February 1st 2012, asks for the first 100 beginning with the first value and requests data-

level metadata with everything in ascending order.

EXEMPLE 2

search("wl15", 47.5, 47.7, -61.6, -61.4, 0.0, 0.0, "2012-02-03

23:43:54", "2012-02-04 00:17:27", 3, 5, true, "", "desc")

Searches all the water levels in the northwest of the Îles-de-la-Madeleines during the night of

February 3rd 2012 and asks, in decreasing order, the next five elements starting at 3

(données 3, 4, 5, 6 et 7) with data-level metadata and no metadata selection.

Observations EXAMPLE 1

search("sal", -90.0, 90.0, -180.0, 180.0, 5.0, 50.0, "2012-12-10

14:15:00", "2012-12-10 14:30:00", 1, 1000, true, "", "asc")

Searches for all salinity values taken between 5 meters and 50 meters on December 10th

2012 between 14 :15 et 14 :30 and gives the first 1000 in ascending order.

EXAMPLE 2

search("wl", -90.0, 90.0, -180.0, 180.0, 0.0, 0.0, "2012-12-10

13:16:00", "2012-12-10 14:16:00", 1, 1, true, "station_id=02985",

"desc")

Assuming being December 10th 2012 at 14 :16, gives the most recent water level at

Rimouski (02985) if it has been measured in the last hour.

EXAMPLE 3

search("wl", 48.4, 48.5, -68.6, -68.5, 0.0, 0.0, "2012-12-10

12:00:00", "2012-12-10 18:00:00", 1, 1000, true, "vl=1+","asc")

Searches for all the water levels in Rimouski during the afternoon of December 10th 2012

which have a validation level of 1 or 2. By replacing "vl=1+" with "vl=2", one can get only

the level 2 water levels.



interpolate

Makes a search of forecast water levels and gives back data points and metadata inside an object of type

ResultSpine (see Appendix B). This method only works in SPINE and is much more simple than search,

only needing three arrays :

One array of real numbers for latitudes

Another array of real numbers for longitudes

A last array of strings for dates.

Values at the same index in the arrays represent a set of coordinates and arrays must have the same length.



References

To learn more about technologies used by the web services :

SOAP :

http://www.w3.org/TR/soap/

http://en.wikipedia.org/wiki/SOAP

WDS Standard:

http://weds.sourceforge.net/cookbook/fr/index.html


WSDL :

http://www.w3.org/TR/wsdl

http://en.wikipedia.org/wiki/Web_Services_Description_Language

http://www.w3.org/TR/soap/

http://en.wikipedia.org/wiki/SOAP



http://www.w3.org/TR/wsdl

http://en.wikipedia.org/wiki/Web_Services_Description_Language



Appendix A – Class Diagram of the WDS Standard

Extrait du document « WDS Cookbook » (http://weds.sourceforge.net/cookbook/fr/index.html)

ResultSet

An instance of class ResultSet is given back as results to a search. This object, drawn at the center of the

diagram, contains an array of data in its property data of size size. Other properties are :

boundarySpatial : the spatial limits of the data inside the results,

boundayDepth : the depth limits of the data inside the results,

boundaryDate : the temporal limits of the data inside the results,

boundaryValue : the limits of the values themselves,

status : the status of the request

metatada : other metadata about the request

Values themselves are instances of class Data. Properties spatialCoordinates, boundaryDepth and

boundaryDate indicate the location of the sensor and property metadata gives more information (see the

section about method search). The value itself is in property value.




Appendix B – Class Diagram of Method interpolate of web service SPINE

ResultSpine

An instance of class ResultSpine is given as a result to a call to an interpolation. This object, drawn at the

center of the diagram contains an array as property data of size size. Other properties are :

status : the status of the request

metatada : other metadata about the request

Values themselves are instances of class DataSpine. Properties coordinates and date indicate the location

and time of the forecast, properties metadata and type give more information (see the section on interpolate).

The value itself is in property value.



DataSpine

An instance of class DataSpine contains values and metadata about a water level forecast:

value: the water level in meters w.r.t chart datum

coordinate: spatial coordinate moved to be at the closest St. Lawrence channel center-line

date: the date for which the forecast is for

type: the type of data: it can be forecast for a forecast or begin with error to indicate an error.

metadata: metadata about the forecast, including age_forecast indicating the age in minute of the

forecast (that is the interval between the moment the forecast was made and the moment the forecast was

requested) and precision_index indicating the margin of error in meters

Any other type or metadata available at the moment does not have any significant value and are

placeholders for future changes



Appendix C – Error Messages

If there are errors in a search request or if the service itself has errors, the property status in the

ResultSet will have one of these messages :

Valeur : Ce que cela signifie :

The web service is currently unavailable.

Please, try later.

Self explanatory.

Invalid date format The date has an incorrect format. The correct format is

yyyy-MM-dd HH:mm:ss in UTC.

Invalid order The order is incorrect, the correct orders are asc or desc.

Invalid datatype The type in parameter dataname is incorrect. See

getDataInfo for a list of correct values.

If there are errors in a call to interpolate from SPINE or if the service itself has errors, property status of

ResultSpine will have one of these messages :

Valeur Ce que cela signifie :

The forecast web service is currently

unavailable. Please, try later.

Self explanatory.

error, Out of Date Boundary Self explanatory.

error, Out of Spatial Boundary Self explanatory.

error, Wrong date format The date has an incorrect format. The correct format is

yyyy-MM-dd HH:mm:ss in UTC.

Data of class DataSpine from SPINE can also have the following message instead of a value:

error, The geographic coordinate must be

closer to the center of the St. Lawrence river.

The coordinates are inside the spatial limits but too far

from the center of St. Lawrence River channel.

technical specifications for accessing water level web ... - spine... · watel level web services...

Documents