Crate rjw_uktides

rjw-uktides is a small library to help fetch and parse tide predictions data from the UK Hydrographic Office EasyTide service.

Tide predictions can be obtained for about 700 locations around Great Britain, Ireland, the Channel Islands, and the Isle of Man. The data includes the predicted times of high and low tides, so it’s perfect for planning your next trip to the beach (please don’t use it for navigation).

EasyTide is a publicly available web application that uses two unauthenticated JSON endpoints to look up tide stations and tide predictions for those stations. No API key is needed.

This library does not perform network IO itself, instead there are two pairs of functions that construct the appropriate URLs for you to query with your preferred HTTP client, and parse the returned JSON data:

• stations_list_url() returns the URL that gives a list of tidal stations, which can then be parsed with stations_from_reader().
• tide_predictions_url() constructs a station-specific URL that gives tide prediction data, which can then be parsed with tides_from_reader().

Example usage

Here’s a full usage example using ureq to perform the GET request.

// Fetch the list of all stations.
let url = rjw_uktides::stations_list_url();
let body = ureq::get(url.as_str()).call()?.into_body().into_reader();
let stations: Vec<Station> = rjw_uktides::stations_from_reader(body)?;

// Fetch tide predictions for the first station
let url = rjw_uktides::tide_predictions_url(&stations[0].id);
let body = ureq::get(url.as_str()).call()?.into_body().into_reader();
let predictions: TidePredictions = rjw_uktides::tides_from_reader(body)?;

// Print the times of the high and low tides
for event in predictions.tidal_event_list {
    println!("{}    {}", event.date_time, event.event_type);
}

Typically you’ll already know the station you want predictions for. Look up its ID, either from the list of stations or from the value of the PortID query parameter on the EasyTide website. For instance, Sandown on the Isle of Wight has an ID of “0053” (note that these are not numeric IDs). We can look it up directly by creating a StationId from that string:

let sandown: StationId = "0053".into();
let url = tide_predictions_url(&sandown);
let body = ureq::get(url.as_str()).call()?.into_body().into_reader();
let sandown_predictions = tides_from_reader(body)?;

Main types

The main structs of interest are:

• TidePredictions, which includes all of the prediction data, notably the times of high and low tides over the next few days;
• StationId, which you need to use to obtain those predictions; and
• Station, which contains more details about a particular tidal station.

Feature flags

If you only need to use this as a library, you can disable the CLI binary and its dependencies by disabling default features.

Structs

Coordinates

Latitude and longitude of a tidal station.

DecimalDegrees

Geographic coordinate represented as decimal degrees.

LunarPhase

Prediction of a particular lunar phase.

Metres

Predicted tide height in metres.

Station

Details of a specific tidal station.

StationId

Unique identifier for a tidal station used to look up tide predictions.

TidalEvent

An instance of low or high tide.

TidalHeightOccurence

Half-hourly prediction of tide height.

TidePredictions

Tide prediction and related data for a particular station.

Enums

Country

Country in which a tidal station is located.

Error

LunarPhaseType

Represents a particular phase of the moon.

TidalEventType

Represents either low or high tide.

Functions

stations_from_reader

Parse a tide stations list from the reader.

stations_list_url

Get the URL for information on all available stations.

tide_predictions_url

Construct a tide-prediction URL for the given station.

tides_from_reader

Parse tide predictions for a specific station from the reader.