JSON API to tide and surge predictions for multiple tide gauge locations
Switch branches/tags
Clone or download
pbrooks Merge pull request #402 from sealevelresearch/requires-io-master
[requires.io] dependency update on master branch
Latest commit 3b28c50 Apr 6, 2017


Documentation Status Build Status Codacy Badge Requirements Status

Sea Level API v1

** Warning: This is an alpha API and may change dramatically - don't develop against it without contacting us first! **

Type of Endpoint Data class Source URL base
point-in-time predictions tide level astro model /predictions/tide-levels/
surge level hydro model /predictions/surge-levels/
sea level derived /predictions/sea-levels/
weather /predictions/weather/
point-in-time observations sea level tide gauge /observations/sea-levels/
surge level derived /observations/surge-levels/
weather /observations/weather/
combined prediction/obs sea level derived /sea-levels/
time window predictions tide level derived /predictions/tide-windows/
sea level derived /predictions/sea-level-windows/

Datetime and "now"

  • All datetimes are expressed in UTC
  • Datetimes are always formatted as YYYY-MM-DDThh:mm:ssZ (a subset of ISO 8601)


  • start and end - date/times between which tide levels are returned.
  • interval - number of minutes between results (default=1)


  "tide_levels": [{
    "datetime": "2014-06-03T15:47:00Z",
    "tide_level": 10.37,



  • start and end - date/time bounds inside which to search for tidal windows.
  • tide_level - the minimum tide height in metres.

Returns time windows during which the tide level will be above a given height in metres.


  "tide_windows": [{
    "start": {
      "datetime": "2014-06-03T18:00:00Z",
      "tide_level": 10.71
    "end": {
      "datetime": "2014-06-03T19:21:00Z",
      "tide_level": 10.73
    "duration": {
      "total_seconds": 4860,


/predictions/sea-levels/ (draft)

  "sea_levels": [
    "datetime": "2014-08-01T16:14:00Z",
    "sea_level": 8.85,
    "tide_level": 8.45,
    "surge_level": 0.20,

/sea-levels/ (draft)

  "sea_levels": [
    "datetime": "2014-08-01T16:14:00Z",
    "predicted_tide_level": 8.45,
    "predicted_surge_level": 0.20,
    "predicted_sea_level": 8.65,
    "observed_sea_level": 8.70,
    "derived_surge_level": 0.25,

Design notes