Visual Crossing provides historical and forecast weather data for maritime locations, including oceans, seas and other large bodies of water. In addition to standard weather variables such as temperature, wind and precipitation, the Timeline Weather API can return marine-specific information including wave height, maximum wave height, wave period, wave direction, swell height, swell period and swell direction.
This makes it possible to retrieve the weather and sea state for a specific latitude and longitude using the same API used for land-based weather data.
Available marine weather data
Marine weather data is available globally over open oceans, seas and large bodies of water.
You can request standard weather information such as:
- Temperature
- Wind speed and direction
- Atmospheric pressure
- Cloud cover
- Precipitation
You can also request marine-specific wave and swell information:
| API element | Description |
|---|---|
waveheight | Significant wave height — the average height of the highest one-third of waves |
maxwaveheight | Maximum individual wave height |
waveperiod | Dominant wave period in seconds |
wavedir | Direction the waves are coming from, in degrees from north |
swellheight | Significant height of the swell component |
swellperiod | Swell period in seconds |
swelldir | Direction the swell is coming from, in degrees from north |
Marine elements are available at hourly resolution and can also be returned as daily values.
Marine data is available over water where the underlying marine data source has coverage. Locations on land, or locations extremely close to shore where the marine model does not resolve a water location, may return empty marine values.
Understanding significant and maximum wave height
The waveheight element represents significant wave height.
Significant wave height is the mean height of the highest one-third of waves during the period. It is one of the most commonly used measures of sea state and generally corresponds well to the wave height that an experienced observer would describe.
For example, a returned value of:
waveheight = 1.8 m
means that the significant wave height is approximately 1.8 meters.
The maxwaveheight element provides the maximum individual wave height for the period.
This can be particularly useful for applications such as vessel operations, offshore infrastructure and other situations where individual large waves may be important in addition to the overall sea state.
Understanding wave period
The waveperiod element reports the dominant wave period in seconds.
Wave period describes the time between successive wave crests. For example:
waveperiod = 8
indicates a dominant wave period of approximately eight seconds.
Wave period can provide important information about the character and energy of the sea state. Longer-period waves are often associated with swell generated by distant weather systems.
Understanding wave direction
The wavedir element reports the direction from which the waves are coming.
Directions are expressed in degrees clockwise from north:
- 0° — waves coming from the north
- 90° — waves coming from the east
- 180° — waves coming from the south
- 270° — waves coming from the west
This follows the same meteorological “from” convention used by the API’s winddir element.
For daily data, directional values are calculated using a vector average rather than a simple arithmetic average.
Wave data versus swell data
The API provides separate wave and swell elements.
The wave fields describe the overall wave conditions at the requested location.
The swell fields describe the longer-period swell component that has propagated into the location, often from weather systems some distance away.
The swell elements are:
swellheightswellperiodswelldir
Swell frequently has a longer period and more consistent direction than locally generated wind-driven waves.
Separating these values can be useful for applications including vessel routing, offshore operations, fishing, surfing and coastal recreation.
Requesting marine data using the Timeline Weather API
Marine data is available through the standard Visual Crossing Timeline Weather API.
For ocean and sea locations, using a latitude and longitude is usually the easiest and most precise way to specify the location.
For example, the following request retrieves hourly marine weather for the location 50.00835,-7.94565 for June 1 through June 30, 2016:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/50.00835,-7.94565/2016-06-01/2016-06-30?unitGroup=metric&include=hours&elements=datetime,temp,windspeed,winddir,waveheight,maxwaveheight,waveperiod,wavedir,swellheight,swellperiod,swelldir&key=YOUR_API_KEY&contentType=json
Replace YOUR_API_KEY with your Visual Crossing Weather API key.
The marine elements are optional premium elements and should be explicitly included using the elements parameter.
For example:
&elements=datetime,waveheight,maxwaveheight,waveperiod,wavedir,swellheight,swellperiod,swelldir
You can freely combine marine fields with the other weather elements available through the Timeline Weather API.
Retrieving historical wave data
To retrieve historical marine conditions, simply specify the historical dates in the Timeline API URL.
For example:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/50.00835,-7.94565/2025-01-01/2025-01-07?unitGroup=metric&include=hours&elements=datetime,waveheight,maxwaveheight,waveperiod,wavedir,swellheight,swellperiod,swelldir&key=YOUR_API_KEY
This returns the hourly wave and swell conditions for the requested location and date range.
Because the Timeline API uses the same request structure for historical and forecast data, an application can retrieve past and future marine conditions without changing APIs.
Retrieving a marine weather forecast
The Timeline Weather API can also retrieve forecast wave and swell conditions.
For example, to retrieve the forecast for an ocean location:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/50.00835,-7.94565?unitGroup=metric&include=hours&elements=datetime,temp,windspeed,winddir,waveheight,maxwaveheight,waveperiod,wavedir,swellheight,swellperiod,swelldir&key=YOUR_API_KEY
The response combines standard atmospheric weather information with marine conditions for the requested point.
Using US, metric and UK units
Marine height values follow the API’s unitGroup setting.
| Unit group | Wave and swell height |
|---|---|
us | feet |
metric | meters |
uk | meters |
Wave and swell periods are returned in seconds and directions are returned in degrees regardless of the unit group.
Daily versus hourly marine data
Marine data is fundamentally available at hourly resolution.
When daily data is requested, the API aggregates the hourly values using the appropriate statistic:
- Wave and swell heights — average
- Wave and swell periods — average
- Maximum wave height — maximum
- Wave and swell directions — vector average
For applications that need to understand changing sea conditions during the day, request the hourly records using:
&include=hours
Finding a maritime location
For land locations, the Timeline Weather API can resolve addresses and place names automatically.
For locations at sea, however, a latitude and longitude is normally the most useful way to specify the point of interest.
For example:
50.00835,-7.94565
can be passed directly as the location portion of the Timeline API URL.
This makes it straightforward to request marine weather for vessel positions, offshore facilities, fishing grounds, shipping routes or arbitrary points in the ocean.
Applications for historical marine weather data
Historical and forecast marine data can be useful for many applications, including:
- Vessel and shipping analysis
- Offshore wind operations
- Oil and gas operations
- Fisheries
- Marine insurance
- Port and harbor operations
- Coastal engineering
- Surf and recreational forecasting
- Investigating historical marine incidents
- Comparing sea conditions with operational or business data
Because wave and swell information can be retrieved alongside wind, temperature, pressure and precipitation, a single Timeline Weather API request can provide a more complete picture of the atmospheric and sea conditions at a location.
Getting started
You can create marine weather queries using the Visual Crossing Weather Query Builder or construct requests directly using the Timeline Weather API.
For a complete description of the available weather and marine elements, see the Weather Data Documentation and Timeline Weather API Documentation.
Marine wave and swell elements are premium weather elements. See the Visual Crossing pricing information for current plan availability.