General

The WorldTides API provides 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 will return:

  • the calculated heights at a certain time
  • the times and heights of low tide and high tide
  • a graph of the tide for 1 to 7 days (new in v2)
  • various vertical datums (height reference levels)
  • a list of stations in a specific area
  • the coordinates of the closest point for which tidal information is available. (Note: If there is no location within a degree of latitude and longitude, then an error is returned).

Access

Access to the API is protected by an API key which you can change at any time. You can obtain an API key by registering here.

Credits per API Request

Each API request can only be used for a single user (see License). API requests for one type of data with default parameters cost 1 credit. You are can also make an an API request that returns multiple types of data at once and for longer time intervals.

  • heights: 1 credit for every 7 days of data at 1/2 hour intervals.
  • extremes: 1 credit for every 7 days of data.
  • datums: 1 credit.
  • plots: 1 additional credit.
  • stations: 1 credit for a distance <= 500km, 2 credits <= 5000km, and 3 credits for more.

Try the free Credit Calculator pricing page for more details.

Change Log

v1 - Initial release.

v2 - Adds date, days, localtime, plot, and timezone Request parameters as well as plot, points, and timezone Response parameters.

v3 - 12/26/21: Improves timezone Response parameter and flips sign of Etc/GMT timezone response.

Request

All request should be made to v3 of the API using the following endpoint:

http://www.worldtides.info/api/v3

or

https://www.worldtides.info/api/v3

The following parameters can be used:

Parameter Description
date (new in v2) Start date (in YYYY-MM-DD format) to retrieve the tidal heights or extremes starting at midnight local time. You can also pass "today" to use the current date of the location.
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.

The default is MSL (Mean Sea Level), but we highly recommend setting this to CD.
days (new in v2) The number of days to retrieve the heights or extremes or a plot. If receive a plot, days must be 1 to 7.
datums If this parameter is present the datums (vertical reference levels) will be returned. The possible datums are listed here.
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, date, length, days, and step parameters to customize this.
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, date, length, days, and step parameters to customize this.
key The WorldTides API key (required for all calls)
lat Latitude (in decimal degrees) of the location for which to return the tidal data and stations list.
length* Length (in seconds) of the interval to retrieve the tidal heights or extremes. (defaults to 192800 seconds which is usually 2 days depending on daylight saving).

It is highly recommended to use "days" parameter instead. This ensures that you get one or more full calendar days worth of data even when there is a daylight saving transition which adds or removes an 3600 seconds to the time between the start and end. In other words, not all days have exactly 24 hours.
localtime (new in v2) If this parameter is present, the "date" parameters in the "heights" and "extremes" will be in ISO 8601 format with the local timezone (ex. 2021-02-12T15:19:21-08:00). This also returns the timezone in the response even if you do not set the timezone parameter.
lon Longitude (in decimal degrees) of the location for which to return the tidal data and stations list.
plot (new in v2) Used in conjunction wtih heights, setting this will return mime64 encoded png data. The following additional optional parameters allow you to customize the plot.
ParameterDescription
units feet or meters
timemode 12 or 24
width width of the image (defaults to 1400)
height height of the image (defaults to 600)
font font size to use on the image (defaults to 24)
grid type of grid to use (“none”, “course”, or “fine”) (defaults to “course”)
color comma separated red, green, blue color of the plot (defaults to 2,102,255)
backgroundcomma separated red, green, blue color for the background (defaults to white)
points returns "points" of the plot
Note: Make sure you set length or days otherwise you will get an empty plot. Also, you should set "heights" so there is data to plot. See the example below.
start* Start date/time (in seconds since the unix epoch) to retrieve the tidal heights or extremes. (defaults to the 6 hours before the current time)

It is highly recommended to use "date" parameter instead. The "date" parameter automatically starts at midnight local time for the location. This saves you the trouble of determining this on the client end.
step Step size (in seconds) to retrieve the tidal heights for. By default the step is 1/2 hour (1800 seconds). Step must be a positive number equal or greater than 60 (1 minute).
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. This is also used with the "stations" parameter to limit the number of stations that are returned. The default for this parameter can be changed in the settings. It is set to 10km by default.
stations If this parameter is present a list of tidal stations will be returned within "stationDistance" kilometers from the specified lat and lon. If stationDistance is not specified, then your default setting is used. Both lat and lon parameters are required when using this parameter.
The cost is 1 credit for a station distance of 500km or less, 2 credits for 5000km or less, and 3 credits for anything greater.
Note: This specific API call is allowed to be shared to multiple users (see License for more information).
timezone (new in v2) If this parameter is present, the location's timezone is returned (ex. America/Los_Angeles). Note: v3 improves timezones for global locations by using accurate polygon mapping. v3 also fixes the Etc/GMT timezones so they are positive for negative latitudes.

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. Developers are encouraged to use this string in their software as if they were error numbers. These strings will not change, however new ones may be added in the future.
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 the 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 number of credits used by this request (see Billing description above).
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.
plot (new in v2) Base64 encoded png file. Ex: "plot":"data:image\/png;base64,iVBORw0KGg..."
points (new in v2) If "points" parameter is passed, this gets set to an array of [x, y, dt, and height] values of the plot. This is useful for cursoring over a the plot and determining the hight of the tide at any specific point along the curve.
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.
timezone (new in v2) Full timezone name (ex. America/Los_Angeles).
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.: 2017-06-12T19:47+0000 )
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.: 2017-06-12T19:47+0000 ).
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
timezone (new in v2) Full timezone name (ex. America/Los_Angeles) returned if either timezone or localtime parameter is passed

Examples

Get a list of stations in a 50km radius:

https://www.worldtides.info/api/v3?stations&lat=33.768321&lon=-118.195617&stationDistance=50&key=<apiKey>

Get the tidal heights for the current date:

https://www.worldtides.info/api/v3?heights&date=2024-03-28&lat=33.768321&lon=-118.195617&key=<apiKey>

Get the tidal plot for the current date:

https://www.worldtides.info/api/v3?heights&plot&date=2024-03-28&lat=33.768321&lon=-118.195617&key=<apiKey>

Get the tidal extremes:

https://www.worldtides.info/api/v3?extremes&date=2024-03-28&lat=33.768321&lon=-118.195617&key=<apiKey>

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

https://www.worldtides.info/api/v3?heights&extremes&date=2024-03-28&lat=33.768321&lon=-118.195617&days=7&key=<apiKey>

Get the tidal extremes referenced to CD (Chart Datum):

https://www.worldtides.info/api/v3?datum=CD&extremes&lat=33.768321&lon=-118.195617&key=<apiKey>

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

https://www.worldtides.info/api/v3?datum=LAT&datums&extremes&lat=33.768321&lon=-118.195617&key=<apiKey>

Libraries

The following libraries were created by third party developers. They are listed here as examples to help you get started writing an app. For assistance, see the authors.