General

The World Tides API lets you retrieve tidal information for any location in the world. You can call it via a GET or POST request via http or https. Depending on the query it returns:

  • the coordinates of the closest point for which tidal information is available (i.e. this will be the nearest coastal location in case the requested location was on land).
  • the calculated heights at a certain time
  • the times and heights of low tide and high tide
  • various vertical datums (height reference levels)
  • tidal constituents that enable you to calculate heights and low/high tide offline

Access

Access to the API is protected by an API key and a list of allowed origins. You can obtain an API key by registering.

The origin is verified by checking the "Origin" header against the list of allowed sites/apps.
If the origin header is not present it is set to the literal text "no-origin".

Billing

Retrieval of heights, extremes, datum, datums and corrected constituents can be done in one API call, but it will be calculated as separate calls for billing purposes. (Including both datum and datums will only be counted as one API call.)

Normally the amount of data returned for heights or extremes is limited to 7 days (with the default step size). However if maxcalls is specified more data can be requested, but will be charged for 1 call per 7 day period for extremes or 1 call per 336 steps for heights (which is equivalent to 7 days with the default step size).
E.g. if constituents + heights + extremes for 14 days are requested, maxcalls needs to be >= 2 and 5 calls will be charged: 1 for the constituents, and 2 each for the heights and extremes.

Request

The request must be made to:

http://www.worldtides.info/api

or

https://www.worldtides.info/api

The following parameters can be used:

Parameter Description
stations If this parameter is present a list of tidal stations will be returned.
heights If this parameter is present the tidal heights will be calculated and returned.
By default the heights will be returned from 6 hours ago to 42 hours in the future in 30 minutes intervals.
You can specify the start, length and/or step parameters to customize this.
extremes If this parameter is present the low and high tides will be returned.
By default the heights will be returned from 6 hours ago to 42 hours in the future.
You can specify the start and length parameters to customize this.
datum If this parameter is present heights and extremes will be returned referring to this datum (vertical reference level). The possible datums are listed here.
datums If this parameter is present the datums (vertical reference levels) will be returned. The possible datums are listed here.
correctedConstituents If this parameter is present the tidal constituents corrected for nodal variations will be returned.
With these constituents tidal heights and extremes can be calculated offline. The results will be accurate in a period roughly one month from the start date.
lat Latitude (in decimal degrees) of the location for which to return the tidal data.
lon Longitude (in decimal degrees) of the location for which to return the tidal data.
stationDistance The maximum distance (in kilometers) for which to return tidal data from a tidal station instead of from the global background data.
When this parameter is set to 0 no results from stations will be returned only from the global background data.
The default for this parameter can be changed in the settings. It is set to 10km by default.
key The World Tides API key.
start Start date/time (in seconds since the unix epoch) to retrieve the tidal heights or extremes for.
By default the current time - 6 hours.
length Length (in seconds) of the interval to retrieve the tidal heights or extremes for.
By default the length is 2 days.
For extremes the maximum is 7 days (604800 seconds) unless maxcalls is specified.
For heights the maximum number of datapoints is 336 (7 days * 48 points) unless maxcalls is specified (so length/step must be <= 336).
step Step size (in seconds) to retrieve the tidal heights for.
By default the step is 1/2 hour (1800 seconds).
For heights the maximum number of datapoints is 336 (7 days * 48 points) unless maxcalls is specified (so length/step must be <= 336).
maxcalls Maximum amount of API calls that may be charged for heights or extremes.
If more then 7 days of extremes data and/or more then 336 datapoints for heights are requested, this parameter must be specified. It specifies the maximum amount of calls to be charged for heights or extremes.
E.g. if constituents + heights + extremes for 14 days are requested, maxcalls needs to be >= 2 and 5 calls will be charged: 1 for the constituents, and 2 each for the heights and extremes.
By default maxcalls is 1.

Response

The response is a JSON object. The response is encoded in the UTF-8 character encoding. The JSON object can contain the properties as documented below. Which properties will be returned depends on the request. Additional properties may be present or added in future.

Key Value
status HTTP status code of response. 200 is success, other codes indicated failure.
error If the status is other then 200, this returns a description of the error.
requestDatum The datum that was requested. The possible datums are listed here.
responseDatum Datum of the actual results. The possible datums are listed here.
This can be different from the requestDatum if the datum is invalid or is not available for teh current location.
requestLat Latitude (in decimal degrees) of the request.
requestLon Longitude (in decimal degrees) of the request.
responseLat Latitude (in decimal degrees) of the actual results.
responseLon Longitude (in decimal degrees) of the actual results.
callCount The amount of API calls charged for this request.
atlas The name of the data set from which the tidal information is obtained.
station The name of the station from which the tidal information is obtained. (This is only present if the data is from a tidal gauge.)
copyright The copyright information regarding the retrieved tidal information. As per the terms of service you MUST reproduce this message in any site/app using this data.
stations Array of tidal stations:
Key Value
id Unique identifier of the tidal station.
name Name of the tidal station.
lat Latitude (in decimal degrees) of the tidal station.
lon Longitude (in decimal degrees) of the tidal station.
heights Array of tidal heights (referenced to the responseDatum):
Key Value
dt Date/Time of this prediction (in seconds since the unix epoch).
date Date/Time of this prediction (in ISO 8601 standard date and time format, e.g.: Sat Jun 24 08:33:22 UTC 2017 )
height Height (in meters) of the tide.
extremes Array of low and high tides (referenced to the responseDatum):
Key Value
dt Date/Time of this extreme (in seconds since the unix epoch).
date Date/Time of this extreme (in ISO 8601 standard date and time format, e.g.: Sat Jun 24 08:33:22 UTC 2017 ).
height Height (in meters) of the tide.
type Indicates if this is a "Low" or a "High" tide.
datums Array of the tidal datums:
Key Value
name Abbreviations of the datum.
height The height of the datum with respect to the responseDatum
correctedConstituents Array of the corrected tidal constituents:
Key Value
name Name of the tidal constituent.
speed The speed/frequency of the constituent (in degrees/hour)
amplitude The amplitude of the constituent (in meters)
phase The phase of the constituent (in degrees)
start_dt Date/Time of the start of the interval for which the correctConstituents are accurate (in seconds since the unix epoch).
start_date Date/Time of the start of the interval for which the correctConstituents are accurate (in ISO 8601 standard date and time format, e.g.: Sat Jun 24 08:33:22 UTC 2017).
end_dt Date/Time of the end of the interval for which the correctConstituents are accurate (in seconds since the unix epoch).
end_date Date/Time of the end of the interval for which the correctConstituents are accurate (in ISO 8601 standard date and time format, e.g.: Sat Jun 24 08:33:22 UTC 2017).

Examples

Below examples use GET requests and the links will only work if you have added the string "no-origin" to the list of allowed sites/apps.

Get the tidal heights for the current date/time:

https://www.worldtides.info/api?heights&lat=39.043757&lon=-77.487442&key=<insert API key>

Get the tidal heights for a specific date/time:

https://www.worldtides.info/api?heights&lat=39.043757&lon=-77.487442&start=1412272800000&length=43200000&step=1800000&key=<insert API key>

Get the tidal extremes:

https://www.worldtides.info/api?extremes&lat=39.043757&lon=-77.487442&key=<insert API key>

Get the tidal heights and extremes for a 14 day period:

https://www.worldtides.info/api?heights&extremes&lat=39.043757&lon=-77.487442&length=1209600&maxcalls=5&key=<insert API key>

Get the tidal extremes referenced to LAT (=Lowest Astronomical Tide):

https://www.worldtides.info/api?datum=LAT&extremes&lat=39.043757&lon=-77.487442&key=<insert API key>

Get the tidal extremes referenced to LAT (=Lowest Astronomical Tide) and the datums:

https://www.worldtides.info/api?datum=LAT&datums&extremes&lat=39.043757&lon=-77.487442&key=<insert API key>

Library

A java library to use the constituents to locally calculate the tidal information is available from github: WorldTidesLib (see also the javadoc). There is also a small demonstration application at github: TideDemo.