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
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
Canadian Hydrographic Service
Page 2 of 14
Watel level web services
version 2.0.3
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
Canadian Hydrographic Service
Page 3 of 14
Watel level web services
version 2.0.3
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.
Canadian Hydrographic Service
Page 4 of 14
Watel level web services
version 2.0.3
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
contact
language
name
abstract
reference_date
max_results
Value
Gives information about the person to contact in case of trouble.
Gives the language of messages exchanged between the server and the
client.
Gives the name of the web service.
Gives the description of the web service.
Gives a textual representation of temporal limits. A more standard way is
to call getBoundaryDate.
Gives the maximum number of elements returned by a query to
interpolate.
Observations has eleven (11) metadata:
Name of the metadata
Value
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]….
Canadian Hydrographic Service
Page 5 of 14
Watel level web services
version 2.0.3
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.
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:
Name of the metadata
Value
contact
Gives information about the person to contact in case of trouble.
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
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.
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 :
Canadian Hydrographic Service
Page 6 of 14
Watel level web services
version 2.0.3
[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).
Canadian Hydrographic Service
Page 7 of 14
Watel level web services
version 2.0.3
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 datalevel 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.
Canadian Hydrographic Service
Page 8 of 14
Watel level web services
version 2.0.3
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.
Canadian Hydrographic Service
Page 9 of 14
Watel level web services
version 2.0.3
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
http://weds.sourceforge.net/cookbook/en/index.html
WSDL :


http://www.w3.org/TR/wsdl
http://en.wikipedia.org/wiki/Web_Services_Description_Language
Canadian Hydrographic Service
Page 10 of 14
Watel level web services
version 2.0.3
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.
Canadian Hydrographic Service
Page 11 of 14
Watel level web services
version 2.0.3
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.
Canadian Hydrographic Service
Page 12 of 14
Watel level web services
version 2.0.3
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
Canadian Hydrographic Service
Page 13 of 14
Watel level web services
version 2.0.3
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
The forecast web service
unavailable. Please, try later.
Ce que cela signifie :
is
currently
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.
Canadian Hydrographic Service
The coordinates are inside the spatial limits but too far
from the center of St. Lawrence River channel.
Page 14 of 14