Web services offered by the Canadian Hydrographic Service

Web services for accessing official data on navigating modelled surface currents and water levels.

Terms and Conditions for use of the Tides, currents and water levels public website

If you would like to use the web services offered by the Canadian Hydrographic Service and the Tides, currents and water levels public website, please read this licence agreement.

If you agree with the terms and conditions of the Canadian Hydrographic Service and the Tides, currents and water levels public website licence agreement, please click on the "I agree" button.

Access to the official web service for navigating modelled surface currents and Geographic coverage was decommissioned on June 16, 2022.

The data is still available.

Documentation is available from Environment and Climate Change Canada.

On this page

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 DFO.NCRCHSInfo-InfoSCHNCR.MPO@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

Web service providing access to SPINE water level forecast data

Description

The SPINE web-based forecasting service has been produced by the Canadian Hydrographic Service (CHS) and is available free of charge under license. This system provides interpolated water level forecasts by specifying a time and a geographical position. These forecasts are available up to 30 days into the future within the navigation channel of the St. Lawrence River between the Port of Montreal and Saint-Joseph-de-la-Rive.

SPINE forecasts of water levels in the St. Lawrence River are calculated using a one-dimensional hydrodynamic model (STLT1061). This model uses upstream flow forecasts from various tributaries. Downstream, it uses water levels from the astronomical tide prediction, plus the storm surge forecast for the first 10 days. Real-time observations are assimilated to anchor the model forecasts. Water level forecast uncertainty values are available from the SPINE web service

Technical specifications

The SPINE service is accessible as a REST-API using the JavaScript JSON format. This service can be accessed at the following address: https://api-spine.azure.cloud-nuage.dfo-mpo.gc.ca/swagger-ui/index.html

The API consists of three GET endpoints. Note that only the first endpoint requires the user to enter parameters.

Interpolated water-level forecast

The user must specify a geographical position and a specified time, and the model returns an interpolated water level forecast from a position related to the centre of the navigation channel. This interpolated water level forecast is expressed relative to chart datum and is always accompanied by the age of the calculation in minutes and an uncertainty.

To use the forecast, you'll need to enter a latitude and longitude pair in decimal degrees, as well as the UTC date and time in ISO 8601 format. It's important to note that only geographic coordinates within the model footprint (St. Lawrence River between Montreal and Saint-Joseph-de-la-Rive) will return a water level forecast value.

.GET (/rest/v1/waterLevel)

If the geographical coordinates are outside the geographical limits of the model, you will receive the following error message: "status": "DISTANCE_OUT_OF_RANGE".

If the requested date is outside the time limits of the model, you will receive the following error message: "status": "DATE_OUT_OF_RANGE".

Model geographical extents

The second endpoint allows you to get the geographical extent where water-level forecasts are available.

GET (/rest/v1/boundarySpatial)

Example:

Model temporal limits

The third endpoint provides the temporal limits (dates and times) for which water-level forecasts are available.

Get (/rest/v1/boundaryDate)

Example :

More information

API schematics are available at the following address: Swagger UI. You can also test the various endpoints at the same address.

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

Access and restrictions

Please take a moment to read through the licence agreement.

Date modified: