WorldTides API Documentation
Use a single HTTPS endpoint to request tide heights, extremes, datums, station lists, tide plots, and timezone-aware local dates for locations worldwide.
Request tide data by latitude and longitude
The API accepts GET or POST requests over HTTPS. Most integrations start with a location, an API key, and one or more requested data types such as heights, extremes, datums, or stations.
https://www.worldtides.info/api/v3?heights&extremes&date=2026-07-18&days=3&lat=33.768321&lon=-118.195617&key=<apiKey>
Authentication
Every request requires an API key. You can create one by registering, and signed-in users can reset their key from the settings page if it is ever exposed.
Endpoint
https://www.worldtides.info/api/v3
Transport
Use HTTPS for production requests. HTTP is still documented for legacy clients, but HTTPS is preferred.
Credits per API request
API requests for one data type with default parameters typically cost 1 credit. A single request can return multiple data types or longer time intervals, which may increase the credit cost.
| Name | Description |
|---|---|
| heights | 1 credit for every 7 days of data at 30 minute intervals. |
| extremes | 1 credit for every 7 days of data. |
| datums | 1 credit when all datums are returned. |
| plot | 1 additional credit. |
| stations | 1 credit for stationDistance up to 500 km, 2 credits up to 5000 km, and 3 credits above 5000 km. |
Use the Credit Calculator for detailed estimates. Each API request may only be used for a single user except where the license explicitly allows otherwise.
Parameters
All requests should target v3. Parameters without values, such as heights or extremes, can be included as query flags.
| Name | Description |
|---|---|
| key | Your WorldTides API key. This is required for all API calls. |
| lat | Latitude in decimal degrees for the requested location. |
| lon | Longitude in decimal degrees for the requested location. |
| date v2+ | Start date in YYYY-MM-DD format. You may also pass today to use the current date at the requested location. |
| days v2+ | Number of calendar days to retrieve for heights, extremes, or a plot. Plot requests must use 1 to 7 days. |
| heights | Return tide heights. By default, heights cover 6 hours ago through 42 hours ahead at 30 minute intervals. Use date, days, start, length, and step to customize this. |
| extremes | Return low and high tide events. By default, extremes cover 6 hours ago through 42 hours ahead. |
| datum | Return heights and extremes relative to the requested datum. The default is MSL, but CD is recommended for many charting and navigation use cases. See the datums page. |
| datums | Return available vertical reference datums for the requested location. |
| localtime v2+ | Return dates in ISO 8601 format with the local timezone offset. This also returns the timezone field. |
| timezone v2+ | Return the location timezone, for example America/Los_Angeles. v3 improves global timezone polygon mapping and Etc/GMT signs. |
| plot v2+ | Use with heights to return a base64 encoded PNG plot. Optional plot parameters include units, timemode, width, height, font, grid, color, background, and points. |
| points v2+ | Use with plot to return cursor-friendly plot points containing x, y, dt, and height values. |
| start* | Unix timestamp for the start of the interval. Prefer date for calendar-day requests because date starts at local midnight and handles daylight saving transitions. |
| length* | Interval length in seconds. Prefer days for full local calendar days, especially across daylight saving changes. |
| step | Step size in seconds for heights. Defaults to 1800 seconds. Must be at least 60 seconds. |
| stationDistance | Maximum station search distance in kilometers. Set to 0 to use only global background data. The account default can be changed in settings. |
| stations | Return nearby tide stations within stationDistance kilometers. Requires lat and lon. This specific API call may be shared to multiple users under the license terms. |
JSON response fields
Responses are UTF-8 encoded JSON objects. Returned fields depend on the request, and additional fields may be added in the future.
| Name | Description |
|---|---|
| status | HTTP-style status code. 200 indicates success. |
| error | Stable error string returned when status is not 200. Treat these strings as error identifiers. |
| requestDatum | Datum requested by the client. |
| responseDatum | Datum actually used for returned values. This may differ when the requested datum is invalid or unavailable at the location. |
| requestLat / requestLon | Latitude and longitude from the request. |
| responseLat / responseLon | Latitude and longitude of the actual prediction point or station used. |
| callCount | Number of credits used by this request. |
| atlas | Dataset used for the tide calculation. |
| station | Station name when the response is based on a tide gauge. |
| copyright | Required copyright attribution for the returned tidal information. Per the terms of service, this must be reproduced in any app or website using the data. |
| timezone v2+ | Timezone name returned when timezone or localtime is requested. |
| plot v2+ | Base64 encoded PNG data, for example data:image/png;base64,iVBORw0KGg.... |
| points v2+ | Array of plot point values useful for interactive cursor behavior. |
| stations | Array of stations. Each station includes id, name, lat, lon, and timezone. |
| heights | Array of tide heights referenced to responseDatum. Each value includes dt, date, and height in meters. |
| extremes | Array of low and high tide events referenced to responseDatum. Each value includes dt, date, height in meters, and type. |
| datums | Array of tidal datums. Each value includes name and height relative to responseDatum. |
Common requests
Nearby stations
Get stations within 50 km of Long Beach, California.
https://www.worldtides.info/api/v3?stations&lat=33.768321&lon=-118.195617&stationDistance=50&key=<apiKey>
Current tide heights
Get tide heights for the current local date.
https://www.worldtides.info/api/v3?heights&date=2026-07-18&lat=33.768321&lon=-118.195617&key=<apiKey>
Tide plot
Get a one-day PNG tide plot.
https://www.worldtides.info/api/v3?heights&plot&date=2026-07-18&days=1&lat=33.768321&lon=-118.195617&key=<apiKey>
Tide extremes
Get low and high tide events.
https://www.worldtides.info/api/v3?extremes&date=2026-07-18&lat=33.768321&lon=-118.195617&key=<apiKey>
Seven-day forecast
Get heights and extremes for seven days.
https://www.worldtides.info/api/v3?heights&extremes&date=2026-07-18&lat=33.768321&lon=-118.195617&days=7&key=<apiKey>
Chart Datum
Get extremes referenced to Chart Datum.
https://www.worldtides.info/api/v3?datum=CD&extremes&lat=33.768321&lon=-118.195617&key=<apiKey>
LAT with datums
Get extremes referenced to Lowest Astronomical Tide and return datum offsets.
https://www.worldtides.info/api/v3?datum=LAT&datums&extremes&lat=33.768321&lon=-118.195617&key=<apiKey>
Change log
| Version | Changes |
|---|---|
| v1 | Initial API release. |
| v2 | Added date, days, localtime, plot, and timezone request parameters plus plot, points, and timezone response fields. |
| v3 | Released December 26, 2021. Improved timezone responses and corrected the sign of Etc/GMT timezone responses. |
Code examples
See WorldTides API examples for short client implementations and platform examples in Swift, Kotlin, cURL, Python, PHP, Node.js, JavaScript, WordPress, Home Assistant, C#, R, and Go.
