1. Help Center
  2. Documentation
  3. AerisWeather API
  4. Reference
  5. Endpoints

AerisWeather API

Endpoint: maritime

The Maritime Forecasts API endpoint delivers essential global marine weather data, including wave and swell heights, directions, and periods, tidal and surge information, surface ocean currents, sea surface temperature, and significant wave height. This comprehensive data set is available hourly by default, with options for 3-hour, 6-hour, or other defined intervals, making it suitable for a variety of maritime applications, such as oceanic navigation, offshore operations, coastal monitoring, and recreational activities.

Base URL Path https://api.aerisapi.com/maritime/
Data Coverage Global
Included With Flex,  API

This endpoint is currently in beta, which means there may be occasional errors and/or the supported features and response output may change before its production version.

The Maritime endpoint provides access to a wide array of information, including the following:

  • Sea surface temperature (SST): Sea surface temperature refers to the temperature of the top layer of the ocean, typically measured up to a depth of a few meters. SST data is crucial in maritime shipping because it affects the local weather and ocean currents and can influence fog formation, hurricanes, and other weather phenomena. This data helps in route planning and scheduling, ensuring that ships avoid areas with extreme weather conditions that might compromise the safety of the vessel and the crew.
  • Sea current direction and speed: Ocean currents are the continuous, directed movement of seawater generated by various forces, including wind, temperature differences, and salinity. Knowledge of sea current direction and speed is essential in maritime shipping for efficient route planning and fuel consumption management. By taking advantage of favorable currents, ships can save fuel, time and reduce their environmental impact.
  • Significant wave height: The significant wave height takes into account wind wave and swell wave information and is defined as the average height of the highest one-third of waves in a given area, is critical in maritime shipping as it impacts a vessel's stability, maneuverability, and safety. According to the National Oceanic and Atmospheric Administration (NOAA), approximately 15% of waves will equal or exceed the significant wave height, with the highest 10% of waves reaching 25-30% higher than this value. Additionally, about once per hour, a wave nearly twice the significant wave height can be expected. These higher waves can cause increased rolling and pitching, making ship navigation challenging and potentially leading to cargo damage or loss. 
  • Primary wave direction and period: The primary wave direction refers to the direction from which the most considerable wave energy is coming, while the period is the time between successive waves. This information is useful for shipping because it enables mariners to understand how waves affect the ship's movement and stability. Knowing the primary wave direction and period helps in route planning and allows for better anticipation of adverse conditions.
  • Wind wave height, direction, and period: Wind waves are generated by the wind blowing over the ocean's surface. The wind wave height, direction, and period are essential for maritime shipping because they can significantly impact the vessel's stability, maneuverability, and safety. This information helps mariners adjust their course and speed to minimize the effects of wind waves on the ship and avoid potential hazards.
  • Primary swell wave height, direction, and period: Swell waves are long-wavelength waves originating from distant weather systems. The primary swell wave height, direction, and period are crucial in maritime shipping because they can cause significant rolling and pitching, making navigation challenging and potentially causing cargo damage. Understanding these factors can help mariners avoid areas with unfavorable swell conditions and plan safer routes.
  • Secondary swell wave height, direction, and period: Secondary swell waves are similar to primary swell waves but originate from a different weather system. Knowledge of secondary swell waves is essential because the interaction of multiple swell systems can create complex wave patterns that can significantly impact the ship's motion and stability. This information helps mariners in route planning and making necessary adjustments to ensure the ship's and its crew's safety.
  • Tertiary swell wave height, direction, and period: Tertiary swell waves are the third most significant swell system affecting an area. Although these waves may be less prominent than primary and secondary swell waves, they can still contribute to the overall wave conditions and impact a vessel's motion and stability. Understanding tertiary swell waves can help mariners take a comprehensive approach to route planning and decision-making, ensuring they account for all possible wave interactions that could impact the ship's journey.

Supported Actions

The following actions are supported with the maritime endpoint:

:id Requesting data by using the :id action is used for returning data for a particular item that has an ID associated with it. This is the primary method for requesting general weather information for a single location (observations, forecasts, advisories, etc.) as the location's name or a zip code serves as the id. Other endpoints may expect a certain value for the ID, such as storm cells whose ID value is a combination of the radar site identifier and unique identifier assigned to every storm cell. Refer to an endpoint's detailed documentation for specific information regarding how to use the :id action.
route The route action returns data for points along a given route. This can be useful to obtain weather information along a transportation route, trails and more. The route is a series of locations, usually latitude/longitudes provided via the p query parameter or for longer routes via GeoJSON within a POST request. The route will return an array of GeoJSON points with the requested data for each point.

Supported Parameters

The following parameters are optional unless otherwise noted:

p p=:place Defines the location to query data for. Refer to the list of supported place value formats.
for for=:string Returns the results starting for the time frame specified. The for parameter is an alias of the from, but useful to indicate a specific time versus a time range

Supports a UNIX timestamp or a specific date string. Alternatively, common date formats supported by the PHP strtotime() function will be accepted; however, commas are not accepted.

Examples:
for=tomorrow
for=friday
for=1302883980
for=MM/DD/YYYY
for=YYYY/MM/DD
for=+2hours
for=2017-02-27 5:00 PM
from from=:string Returns the results starting from the value specified. For best practices we recommend using the to parameter as well to define a specific time frame.

Supports a UNIX timestamp or a specific date string. Alternatively, common date formats supported by the PHP strtotime() function will be accepted; however, commas are not accepted.

Examples:
from=tomorrow
from=friday
from=1302883980
from=MM/DD/YYYY
from=YYYY/MM/DD
from=+2hours
from=2017-02-27 5:00 PM
to to=:string Returns the results between now and the value specified. For best practices we recommend using the from parameter as well to define a specific time frame. When used in conjunction with the from parameter, the value of to will be relative to the value of from, not relative to the current time.

Supports a UNIX timestamp or a specific date string. Alternatively, common date formats supported by the PHP strtotime() function will be accepted; however, commas are not accepted.

Examples:
to=+6hours
to=+5days
to=1302883980
to=MM/DD/YYYY
to=YYYY/MM/DD
to=2017-02-27 5:00 PM
plimit plimit=:total Applied only on the periods property, the total number of periods to return as an integer. The maximum plimit for this endpoint is 250.
pskip pskip=:number Applied only on the periods property, used to skip over a specific number of periods in the data set.
psort psort=:string Applied only on the periods property, used to sort results based on certain fields contained within the periods.
filter filter=:string Predefined filters for limiting the results. The filter value can be a single, comma-delimited or a semicolon delimited string of filter names.

Supported Filters

The following filters can be passed to the filter parameter to reduce the results that are returned:

#hr Returns the conditions in # hour intervals for up to a 24 hour period. # must be an integer from 1 to 24.
For example:
filter=1hr : 1 hour intervals (Default)
filter=3hr : 3 hour intervals
filter=6hr : 6 hour intervals.

This filter is often be used in combination with the from and to parameters. If no from and to the endpoint returns data for the next 24 hours.

Sortable Fields

Default Sort: dt:1 (Date time ascending)

You can use the following fields to sort data. Review the sorting docs page for more information on the sort functionality.

dt Sort based on the forecast date/time

Examples

The /[:endpoint]/[:action]? portion within the query template below can be exchanged with any of the examples. Also, please note you will need to input your client credentials in the [ID] and [SECRET] fields which can be found under the Apps section of the members area.

https://api.aerisapi.com/[:endpoint]/[:action]?client_id=[ID]&client_secret=[SECRET]

Returns the maritime forecast in hourly intervals for the next 24 hours for latitude/longitude 0,0
/maritime/0,0

Returns the estimated maritime conditions for the current hour at latitude/longitude 0,0
/maritime/0,0?for=now&to=now

Returns the maritime forecast in hourly intervals for the next 48 hours for latitude/longitude 0,0
/maritime/0,0?for=now&to=+48hours

Returns the maritime forecast in 6 hour intervals for the next 7 days for latitude/longitude 0,0
/maritime/0,0?for=now&to=+1week&filter=6hours

Response

The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.

Default
GeoJSON

{
  "loc": {
    "long": 0,
    "lat": 0
  },
  "interval": "1hr",
  "periods": [
    {
      "timestamp": 1682204400,
      "dateTimeISO": "2023-04-22T23:00:00+00:00",
      "seaSurfaceTemperatureC": 28.7,
      "seaSurfaceTemperatureF": 83.66,
      "seaCurrentSpeedKTS": 0.4347,
      "seaCurrentSpeedKPH": 0.805,
      "seaCurrentSpeedMPS": 0.2236,
      "seaCurrentSpeedMPH": 0.5002,
      "seaCurrentDir": "NNW",
      "seaCurrentDirDEG": 333,
      "significantWaveHeightM": 1.36,
      "significantWaveHeightFT": 4.4619,
      "significantWaveDir": null,
      "significantWaveDirDEG": null,
      "significantWavePeriod": null,
      "primaryWaveDir": "SSW",
      "primaryWaveDirDEG": 211,
      "primaryWavePeriod": 12,
      "primarySwellHeightM": 0.7,
      "primarySwellHeightFT": 2.2966,
      "primarySwellDir": "SSW",
      "primarySwellDirDEG": 212,
      "primarySwellPeriod": 12,
      "secondarySwellHeightM": 0.2,
      "secondarySwellHeightFT": 0.6562,
      "secondarySwellDir": "S",
      "secondarySwellDirDEG": 170,
      "secondarySwellPeriod": 13,
      "tertiarySwellHeightM": 0.11,
      "tertiarySwellHeightFT": 0.3609,
      "tertiarySwellDir": "SSW",
      "tertiarySwellDirDEG": 205,
      "tertiarySwellPeriod": null,
      "tidesM": -0.56,
      "tidesFT": -1.8373,
      "surgeM": 0.02,
      "surgeFT": 0.0656,
      "windWaveDirDEG": 192,
      "windWaveDir": "S",
      "windWavePeriod": 8
    }
  ],
  "profile": {
    "tz": "Africa/Accra",
    "elevFT": 0,
    "elevM": 0
  }
}
								

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          0,
          0
        ]
      },
      "properties": {
        "loc": {
          "long": 0,
          "lat": 0
        },
        "interval": "1hr",
        "periods": [
          {
            "timestamp": 1682204400,
            "dateTimeISO": "2023-04-22T23:00:00+00:00",
            "seaSurfaceTemperatureC": 28.7,
            "seaSurfaceTemperatureF": 83.66,
            "seaCurrentSpeedKTS": 0.4347,
            "seaCurrentSpeedKPH": 0.805,
            "seaCurrentSpeedMPS": 0.2236,
            "seaCurrentSpeedMPH": 0.5002,
            "seaCurrentDir": "NNW",
            "seaCurrentDirDEG": 333,
            "significantWaveHeightM": 1.36,
            "significantWaveHeightFT": 4.4619,
            "significantWaveDir": null,
            "significantWaveDirDEG": null,
            "significantWavePeriod": null,
            "primaryWaveDir": "SSW",
            "primaryWaveDirDEG": 211,
            "primaryWavePeriod": 12,
            "primarySwellHeightM": 0.7,
            "primarySwellHeightFT": 2.2966,
            "primarySwellDir": "SSW",
            "primarySwellDirDEG": 212,
            "primarySwellPeriod": 12,
            "secondarySwellHeightM": 0.2,
            "secondarySwellHeightFT": 0.6562,
            "secondarySwellDir": "S",
            "secondarySwellDirDEG": 170,
            "secondarySwellPeriod": 13,
            "tertiarySwellHeightM": 0.11,
            "tertiarySwellHeightFT": 0.3609,
            "tertiarySwellDir": "SSW",
            "tertiarySwellDirDEG": 205,
            "tertiarySwellPeriod": null,
            "tidesM": -0.56,
            "tidesFT": -1.8373,
            "surgeM": 0.02,
            "surgeFT": 0.0656,
            "windWaveDirDEG": 192,
            "windWaveDir": "S",
            "windWavePeriod": 8
          }
        ],
        "profile": {
          "tz": "Africa/Accra",
          "elevFT": 0,
          "elevM": 0
        }
      }
    }
  ]
}

Response Properties

The following properties will be provided in every response object:

periods (array) Array for forecasts, Empty if data unavailable or requesting data inland
periods.#.timestamp (number) The UNIX timestamp of the valid time of the forecast period
periods.#.dateTimeISO (string) The ISO 8601 date/time of the forecast period valid time
periods.#.seaSurfaceTemperatureC (number) The sea surface temperature in Celsius. Available out 7 days. Null if unavailable.
periods.#.seaSurfaceTemperatureF (number) The sea surface temperature in Fahrenheit. Available out 7 days. Null if unavailable.
periods.#.seaCurrentSpeedKTS (number) The sea currents speed in knots. Null if no current or unavailable.
periods.#.seaCurrentSpeedKPH (number) The sea currents speed in kilometers/hour. Null if no current or unavailable.
periods.#.seaCurrentSpeedMPS (number) The sea currents speed in meters per second. Null if no current or unavailable.
periods.#.seaCurrentSpeedMPH (number) The sea currents speed in miles per hour. Null if no current or unavailable.
periods.#.seaCurrentDir (string) The sea current direction as a cardinal direction. Null if no current or unavailable.

Possible values:
- N - North
- NNE - North northeast
- NE - Northeast
- ENE - East northeast
- E - East
- ESE - East southeast
- SE - Southeast
- SSE - South southeast
- S - South
- SSW - South southwest
- SW - Southwest
- WSW - West southwest
- W - West
- WNW - West northwest
- NW - Northwest
- NNW - North northwest
periods.#.seaCurrentDirDEG (number) The sea current direction in degrees.
0 - 359, with 0 = North, Null if no current or unavailable.
periods.#.significantWaveHeightM (number) The significant wave height in meters. Null if unavailable.
periods.#.significantWaveHeightFT (number) The significant wave height in feet. Null if unavailable.
periods.#.primaryWaveDir (string) The primary wave direction as a cardinal direction. Null if no current or unavailable.
periods.#.primaryWaveDirDEG (number) The primary wave direction in degrees.
0 - 359, with 0 = North, Null if no current or unavailable.
periods.#.primaryWavePeriod (number) The primary wave period in seconds. Null if no swell or unavailable.
periods.#.windWaveDir (string) The wind wave direction as a cardinal direction. Null if no swell or unavailable.
periods.#.windWaveDirDEG (number) The wind wave direction in degrees.
0 - 359, with 0 = North, Null if no swell or unavailable.
periods.#.windWavePeriod (number) The wind wave period in seconds.
periods.#.primarySwellHeightM (number) The primary swell height in meters. Null if no swell or unavailable.
periods.#.primarySwellHeightFT (number) The primary swell height in feet. Null if no swell or unavailable.
periods.#.primarySwellDir (string) The primary swell direction as a cardinal direction. Null if no swell or unavailable.
periods.#.primarySwellDirDEG (number) The primary swell direction in degrees.
0 - 359, with 0 = North, Null if no swell or unavailable.
periods.#.primarySwellPeriod (number) The primary swell period in seconds. Null if no swell or unavailable.
periods.#.secondarySwellHeightM (number) The secondary swell height in meters. Null if no swell or unavailable.
periods.#.secondarySwellHeightFT (number) The secondary swell height in feet. Null if no swell or unavailable.
periods.#.secondarySwellDir (string) The secondary swell direction as a cardinal direction. Null if no swell or unavailable.
periods.#.secondarySwellDirDEG (number) The secondary swell direction in degrees.
0 - 359, with 0 = North, Null if no swell or unavailable.
periods.#.secondarySwellPeriod (number) The secondary swell period in seconds. Null if no swell or unavailable.
periods.#.tertiarySwellHeightM (number) The tertiary swell height in meters. Null if no swell or unavailable.
periods.#.tertiarySwellHeightFT (number) The tertiary swell height in feet. Null if no swell or unavailable.
periods.#.tertiarySwellDir (string) The tertiary swell direction as a cardinal direction. Null if no swell or unavailable.
periods.#.tertiarySwellDirDEG (number) The tertiary swell direction in degrees.
0 - 359, with 0 = North, Null if no swell or unavailable.
periods.#.tertiarySwellPeriod (number) The tertiary swell period in seconds. Null if no swell or unavailable.
periods.#.tidesM (number) The tide level in meters. Can be negative for low tide. Useful near shore. Null if unavailable.
periods.#.tidesFT (number) The tide level in feet. It can be negative for low tide. Useful near shore. Null if unavailable.
periods.#.surgeM (number) The surge level in meters. Useful near shore. Null if unavailable.
periods.#.surgeFT (number) The surge level in feet. Useful near shore. Null if unavailable.
loc.long (number) The longitude coordinate of the record.
loc.lat (number) The latitude coordinate of the record.
profile.tz (string) Timezone name of the location.
profile.tzname (string) The timezone abbreviation for the location.
profile.tzoffset (number) The timezone offset for the location in seconds.
profile.isDST (boolean) True if the location is currently observing Daylight Savings Time (DST), otherwise false.

Last modified: May 12, 2023