Standard US Tidal Predictions
Overview
- Domain Portfolio: Lifestyle
- Domain: Marine
- Usage classification: Standard
- Geography: U.S. only
- Attribution Required: NO
- Attribution Requirements: N/A
The U.S. Tides API returns marine tide predictions for coastal locations in the United States and its territories. The tidal predictions are generated from harmonic or subordinate tide station/locations. Harmonic locations (also known as reference sites) are generated by regular water level reading sites. Subordinate location predictions derived by applying corrections to a reference tide station. Data is available for the date range of 12 months prior to present date and up to 12 months into the future. Data will not be returned for locations over 60 miles from the coastline.
HTTP Headers and Data Lifetime - Caching and Expiration
For details on appropriate header values as well as caching and expiration definitions, please see The Weather Company® Data | API Common Usage Guide.
| Atomic Endpoints | Aggregate Product Names |
|---|---|
| v3/wx/forecast/tides/daily/3day | v3-wx-forecast-tides-daily-3day |
| v3/wx/forecast/tides/daily/5day | v3-wx-forecast-tides-daily-5day |
| v3/wx/forecast/tides/daily/10day | v3-wx-forecast-tides-daily-10day |
| v3/wx/forecast/tides/daily/15day | v3-wx-forecast-tides-daily-15day |
| v3/wx/forecast/tides/monthly | v3-wx-forecast-tides-monthly |
URL Construction
| Request by Tidal Station ID: Required Parameters: tide(s), units, format, startDay (not used with ‘monthly’ endpoint), startMonth, startYear, apiKey |
|---|
| Request by Geocode: Required Parameters: geocode(s), units, format, startDay (not used with ‘monthly’ endpoint), startMonth, startYear, apiKey |
| https://api.weather.com/v3/wx/forecast/tides/daily/3day?geocode=30.39,-86.49&units=e&format=json&startDay=01&startMonth=10&startYear=2018&apiKey=yourApiKey |
| Request by IATA Code: Required Parameters: iataCode, units, format, startDay (not used with ‘monthly’ endpoint), startMonth, startYear, apiKey |
| https://api.weather.com/v3/wx/forecast/tides/daily/3day?iataCode=SFO&units=e&format=json&startDay=01&startMonth=10&startYear=2018&apiKey=yourApiKey |
| Request by ICAO Code: Required Parameters: icaoCode, units, format, startDay (not used with ‘monthly’ endpoint), startMonth, startYear, apiKey |
| https://api.weather.com/v3/wx/forecast/tides/daily/3day?icaoCode=KLGA&units=e&format=json&startDay=01&startMonth=10&startYear=2018&apiKey=yourApiKey |
| Request by Place ID: Required Parameters: placeid, units, format, startDay (not used with ‘monthly’ endpoint), startMonth, startYear, apiKey |
| https://api.weather.com/v3/wx/forecast/tides/daily/3day?placeid=dab51f120ae4ee6a0359298f849c29a710c09e4c6b28a45975c5557a21ed1153&units=e&format=json&startDay=01&startMonth=10&startYear=2018&apiKey=yourApiKey |
| Request by Postal Key: Required Parameters: postalKey, units, format, startDay (not used with ‘monthly’ endpoint), startMonth, startYear, apiKey |
| https://api.weather.com/v3/wx/forecast/tides/daily/3day?postalKey=94016:US&units=e&format=json&startDay=01&startMonth=10&startYear=2018&apiKey=yourApiKey |
| https://api.weather.com/v3/wx/forecast/tides/daily/3day?tide=8670870&units=e&format=json&startDay=01&startMonth=10&startYear=2018&apiKey=yourApiKey |
Valid Parameter Definitions
| Parameter Name | Valid Parameter Value | Description |
|---|---|---|
| tide | 8670870, TEC2847 | This field contains the unique tidal station ID. Appears as an integer or alphanumeric string. |
| startDay | any valid day of the monthly, range 01-31 | any valid day of the month, range 01-31 |
| startMonth | any valid month of the year, range 01-12 | any valid month of the year, range 01-12 |
| startYear | any valid year | any valid year |
Data Elements & Definitions
Note: Field names are sorted alphabetically in the table below for presentation purposes. The table below does not represent the sort order of the API response.
| Field Name | Description | Type | Range | Sample | Nulls Allowed |
|---|---|---|---|---|---|
| tideLowAnnualMin | Min height of Low Tide predicted for the annual period: in feet or meters | decimal | Feet or meters based on units parameter | 1.6 | Y |
| "tidalForecast" | Array | ||||
| tideHeight | The Height of the Tide at a particular time in the appropriate unit of measure (UOM) : feet or meters. Datum is derived from MLLW (Mean Lower Low Water) | [decimal] | Feet or meters based on units parameter | 6 | N |
| tideId | Tide ID reference number. | [integer] | 413 | Y | |
| tideType | The type of the tide. | [string] | H=High, L=Low | H | N |
| validTimeLocal | Time of the Tide in the local time adjusted for Daylight Savings Time (DST) | [ISO] | YYYY-MM-DDTHH:MM:SS-NNNN; NNNN=GMT offset | 2014-08-20T10:47:59-0500 | N |
| validTimeUtc | Date/time of tide in Unix seconds [number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds]. | [epoch] | 1369306800 | N | |
| "tidalForecast" | Object | ||||
| adminDistrict | The internationalized identifier for ‘state’, ‘province’, or similar geopolitical area - level 1 administrative division. | string | Any valid US state code or International region identifier | Colorado | Y |
| adminDistrictCode | State, Region, District or Province code - identifier code for ‘state’, 'province' or similar geopolitical area - level 1 administrative division. | string | Any valid US state code or International region identifier | GA | N |
| countryCode | ISO country code of the location | string | Any valid ISO country code | US | N |
| latitude | Latitude of tidal station location. | decimal | Any valid latitude value. -90 to 90 | -59.53 | N |
| longitude | Longitude of tidal station location. | decimal | Any valid longitude value. -180 to 180 | -113.13 | N |
| stationId | This field contains the unique tidal station ID. | string | Any valid tide station ID, which can contain numbers and letters | 8670870, TEC2847 | N |
| tidalStationName | This field contains the presentation name of a tidal station. | string | Crown Point, Mission Bay, California | Y | |
| tideHighAnnualMax | Max height of High Tide predicted for the annual period: in feet or meters | decimal | Feet or meters based on units parameter | 7.6 | Y |
JSON Sample
// Response Collapsed for Presentation Purposes
{
"adminDistrict": "Florida",
"adminDistrictCode": "FL",
"countryCode": "US",
"latitude": 30.4,
"longitude": -86.51,
"stationId": "8729511",
"tidalStationName": "Destin / East Pass",
"tideHighAnnualMax": 0,
"tideLowAnnualMin": 0,
"tidalForecast": {
"predictionType": [
"Harmonic",
"Harmonic",
"Harmonic",
"Harmonic",
"Harmonic",
"Harmonic",
"Harmonic",
"Harmonic"
],
"tideHeight": [
0.7,
-0.1,
0.7,
-0.1,
0.7,
-0.1,
0.6,
-0.1
],
"tideId": [
1,
2,
3,
4,
5,
6,
7,
8
],
"tideType": [
"H",
"L",
"H",
"L",
"H",
"L",
"H",
"L"
],
"validTimeLocal": [
"2016-11-30T22:01:00-0600",
"2016-12-01T09:00:00-0600",
"2016-12-01T22:36:00-0600",
"2016-12-02T09:43:00-0600",
"2016-12-02T23:12:00-0600",
"2016-12-03T10:23:00-0600",
"2016-12-03T23:48:00-0600",
"2016-12-04T10:58:00-0600"
],
"validTimeUtc": [
1480564860,
1480604400,
1480653360,
1480693380,
1480741920,
1480782180,
1480830480,
1480870680
]
}
}