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.

On this page

Web service providing access to prediction, observations, forecasts and various information at water level stations (IWLS API)

Description

The Integrated Water Level System (IWLS) web service has been produced by the Canadian Hydrographic Service (CHS) and is available free of charge under license. This web service provides predictions, observations and forecasts at water level stations across Canada. Various information is disseminated such as data holdings, benchmark information, vertical datum conversions, water level reference heights. Based on the availability, other time series such as dynamic vertical clearance forecast at some bridges, water current speed, water current direction, water temperature and water salinity might be available. Pictures, tide tables and statistics can also be obtained using this web service.

Technical Specifications

IWLS web service is accessible via a REST-API using the JavaScript JSON format. This web service can be accessed at the following address: https://api.iwls-sine.azure.cloud-nuage.dfo-mpo.gc.ca/swagger-ui/index.html.

The IWLS API consists of nine endpoints which are the following:

  • station statistics
  • height types
  • tide tables
  • station metadata
  • data
  • stations
  • time series definitions
  • benchmarks
  • phenomena

Each endpoint has from one to six different GET commands associated.

Users should pay attention to the quality control flag code (qcFlagCode) associated to each data point. 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)

To familiarize yourself with the IWLS API, documentation is available directly on the web service page.

More information

The IWLS 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

By using the IWLS API, you agree to abide by the licence agreement.

Web service providing access to St. Lawrence River interpolated water level forecast data (SPINE API)

Description

The SPINE forecasts of water levels in the St. Lawrence River are calculated with the results from 1) the ECCC OHPS-SFLE hydrodynamic model for the first 2 days in the future and 2) the non-stationary water level predictions calculated with ECCC's NS_Tide algorithm for the following 28 days. The OHPS-SLFE model uses flow forecasts of the St. Lawrence River and from its most important tributaries upstream and also from tributaries located on its lateral boundaries. It uses downstream water levels from the astronomical tide prediction to which is added the storm surge forecast for the first 2 days in the future. The combined OHPS-SLFE+NS_TIDE forecasts are adjusted according to the latest observations recorded at the nearest tide gauges.

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 SPINE 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 center 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 value.

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.

The user can also request multiple interpolated forecast values from the model via a single query, by sequentially adding all the latitudes, longitudes and times (date and time UTC in ISO 8601 format) desired; the model will then return a number of responses equivalent to the number of latitude/longitude/time trios entered.

GET (/rest/v1/waterLevel)

Single query example:

Multiple query example:

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

The SPINE 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

By using the SPINE API, you agree to abide by the licence agreement.

Date modified: