The CHS is transforming the way it delivers data!

Interested in trying our new water level tools? Visit our new website now under development.

Water level chart

Web services and Rest-API

Please note:

As of 12:00 pm EDT on Monday, May 3rd, 2021, the old Canadian Hydrographic Service WDS services (observations and predictions) are being decommissioned. Please refer to the text below for information on using the new REST-API for direct access to official water level data and other available services.

Web service providing access to water level SPINE forecasts

Technical specifications for accessing this service

This document describes the technical specifications for accessing the Web-based water level forecasting and interpolation service between Montreal and Saint-Joseph-de-la-Rive commonly known as SPINE.

Description

The SPINE web-based forecasting service was developed by the Canadian Hydrographic Service (CHS) and is available free of charge under licence. This system allows to obtain water levels at a time and position specified by the user, up to 30 days in the future, for the navigation channel of the St. Lawrence River between the Port of Montreal and Saint-Joseph-de-la-Rive.

This system is based, in part, on water level forecasts derived from a hydrodynamic model that takes various weather conditions into account and, in part, on real-time observations made by the network of permanent water level recorders. To increase their accuracy, digital model forecasts are adjusted according to water level observations for the entire area. A precision matrix is also provided for forecast data.

To access this Web service, simply follow the steps described in these technical specifications.

Access and restrictions

Please take a moment to read through the licence.

Data

The Web service use SOAP and XML as their communication protocol and the English language for method calling and data exchange. The service has an XML description readable in WSDL (i.e. https://ws-shc.qc.dfo-mpo.gc.ca/spine?wsdl). This description is useful for automatically generating code (with tools such as WSDL2Java from Apache Axis) to communicate with the services.

Rest-API Documentation

CHS is currently undergoing a transformation process in all its product and service delivery activities. Two of the key elements that CHS is working on are the modernization of the water level database (observations, forecasts, predictions) and the development of new services for the dissemination of these data including this REST-API programming interface.

To receive information and notices of updates regarding this interface, please send your name and email to: chsinfo@dfo-mpo.gc.ca.

To familiarize yourself with this new public API, users can consult the documentation available in English only on the following website: https://api-iwls.dfo-mpo.gc.ca/swagger-ui.html.

Example:
  1. To find the IDs of your stations of interest: https://api-iwls.dfo-mpo.gc.ca/api/v1/stations.
  2. Use the following query to obtain the official water levels (wlo) for Vieux-Québec station (ID code: 5cebf1e23d0f4a073c4bc0f6) from October 1 to 2, 2020: https://api-iwls.dfo-mpo.gc.ca/api/v1/stations/5cebf1e23d0f4a073c4bc0f6/data?time-series-code=wlo&from=2020-10-01T00:00:00Z&to=2020-10-01T00:30:00Z

    [{"eventDate":"2020-10-01T00:00:00Z","qcFlagCode":"1","value":3.903,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:03:00Z","qcFlagCode":"1","value":3.865,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:06:00Z","qcFlagCode":"1","value":3.825,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:09:00Z","qcFlagCode":"1","value":3.784,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:12:00Z","qcFlagCode":"1","value":3.743,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:15:00Z","qcFlagCode":"1","value":3.7,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:18:00Z","qcFlagCode":"1","value":3.661,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:21:00Z","qcFlagCode":"1","value":3.62,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:24:00Z","qcFlagCode":"1","value":3.578,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:27:00Z","qcFlagCode":"1","value":3.538,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true},{"eventDate":"2020-10-01T00:30:00Z","qcFlagCode":"1","value":3.495,"timeSeriesId":"5cebf1e23d0f4a073c4bc0e1","reviewed":true}]
                   
  3. Replace the station ID "5cebf1e23d0f4a073c4bc0f6" with your station of interest.
  4. Change the value of the "Time-series-code" parameter to use either:
    • wlo – Water level observations
    • wlf or wlf-spine – Forecasts at operational stations only
    • wlp – Predictions (15 minutes)
    • wlp-hilo – Highs and Lows predictions
  5. Adjust the time period "From" and "To" using the ISO 8061 UTC format.
Quality control - qcFlagCode

The indicators used at all quality control levels are based on UNESCO Ocean Data Standards

Value Flag short name Definition
1 Good Passed documented required QC tests
2 Not evaluated, not available or unknown Used for data when no QC test performed or the information on quality is not available
3 Questionable/suspect Failed non-critical documented metric or subjective test(s)
4 Bad Failed critical documented QC test(s) or as assigned by the data provider
9 Missing data Used as place holder when data are missing