WorldTides™ API Documentation
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.
|
||||||||||||||||||||
| 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:
|
||||||||||||
| heights | Array of tidal heights (referenced to the responseDatum):
|
||||||||||||
| extremes | Array of low and high tides (referenced to the responseDatum):
|
||||||||||||
| datums | Array of the tidal datums:
|
||||||||||||
| 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-11-17&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-11-17&lat=33.768321&lon=-118.195617&key=<apiKey>
Get the tidal extremes:
https://www.worldtides.info/api/v3?extremes&date=2024-11-17&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-11-17&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.
- Node.js Library - https://www.npmjs.com/package/worldtides
- Wordpress - WorldTides Wordpress Widget
