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

README.md

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)

/predictions/tide-levels/

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

/predictions/tide-levels/liverpool-gladstone-dock/?start=2014-06-03T15:47:00Z&end=2014-06-03T15:48:00Z

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

/predictions/tide-levels/liverpool-gladstone-dock/now/

/predictions/tide-windows/

  • 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.

/predictions/tide-windows/liverpool-gladstone-dock?start=2014-06-01T18:00:00Z&end=2014-06-02T18:00:00Z&tide_level=10.7

{
  "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/tide-windows/liverpool-gladstone-dock/now/?tide_level=10.7

/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