--- title: Marine Weather API - Ocean & Coastal Weather Data version: 1.0.0 description: Retrieve marine and ocean weather data for coastal and offshore locations by GPS coordinates, city name/address, or IP address. Returns wave height, wave direction, wave period, wind-wave and swell statistics, sea surface temperature, sea level height, and ocean current speed/direction. Omit `startDate`/`endDate` to get current conditions, or pass both to get a forecast up to 16 days ahead at `daily`, `hourly`, or `minutely` precision via the `precision` parameter. For locations with no nearby ocean data (inland cities, landlocked coordinates), the endpoint still returns a `200` response with every marine field set to `null` instead of an error. openapi: 3.1.1 servers: - https://api.apifreaks.com/v1.0/weather paths: 1 operations: 1 schemas: 12 --- ## Table of Contents - [Marine Weather API - Ocean & Coastal Weather Data v1.0.0](#marine-weather-api-ocean-coastal-weather-data-v100) - [Authentication](#authentication) - [Weather APIs](#weather-apis) - [getMarineWeather](#getmarineweather) - [Parameters](#parameters) - [Responses](#responses) - [Schemas](#schemas) - [MarineResponse](#marineresponse) - [LocationByCoordinates](#locationbycoordinates) - [LocationByIP](#locationbyip) - [LocationByAddress](#locationbyaddress) - [CurrentMarine](#currentmarine) - [MarineDaily](#marinedaily) - [MarineHourly](#marinehourly) - [MarineMinutely](#marineminutely) - [ErrorResponse](#errorresponse) - [WeatherLocation](#weatherlocation) - [MarineForecastData](#marineforecastdata) - [MarineForecastDay](#marineforecastday) # Marine Weather API - Ocean & Coastal Weather Data v1.0.0 Retrieve marine and ocean weather data for coastal and offshore locations by GPS coordinates, city name/address, or IP address. Returns wave height, wave direction, wave period, wind-wave and swell statistics, sea surface temperature, sea level height, and ocean current speed/direction. Omit `startDate`/`endDate` to get current conditions, or pass both to get a forecast up to 16 days ahead at `daily`, `hourly`, or `minutely` precision via the `precision` parameter. For locations with no nearby ocean data (inland cities, landlocked coordinates), the endpoint still returns a `200` response with every marine field set to `null` instead of an error. Base URLs: * [https://api.apifreaks.com/v1.0/weather](https://api.apifreaks.com/v1.0/weather) ## Authentication * API Key (ApiKeyAuthHeader) - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header. * API Key (ApiKeyAuthQuery) - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter. ## Weather APIs ### getMarineWeather `GET /marine` *Dive into detailed marine weather forecasts for coastal and offshore locations* Provides current or forecast marine conditions including wave height, wave direction, wave period, swell info, sea surface temperature, sea level height, and ocean currents. Accepts a location by GPS coordinates, city name/address, or IP address, and returns forecast data at daily, hourly, or minutely precision for up to 16 days ahead. #### Parameters |Name|In|Type|Required|Description| |---|---|---|---|---| |format|query|string|false|Format of the response. Possible values: json.| |startDate|query|string(date)|false|Starting date for marine forecast data in YYYY-MM-DD format. Must be today or a future date, and must be supplied together with endDate — providing only one of the two returns a 400 error. The difference between endDate and startDate must not exceed 16 days.| |endDate|query|string(date)|false|End date for marine forecast data in YYYY-MM-DD format. Must be today or a future date, and must be supplied together with startDate — providing only one of the two returns a 400 error. The difference between endDate and startDate must not exceed 16 days.| |location|query|string|false|City name, place name, or full address.| |lat|query|number|false|Latitude of the location.| |long|query|number|false|Longitude of the location.| |ip|query|string|false|IPv4, IPv6, or hostname for location inference. Defaults to the caller's IP address when location, lat/long, and ip are all omitted.| |precision|query|string|false|Precision of the marine forecast data. Only one of daily, hourly, or minutely is returned per request, matching this value. Default is daily.| |timezone|query|string|false|IANA timezone identifier used to localize the results (e.g. America/New_York). Returns a 400 error if not a recognized timezone.| ##### Enumerated Values |Parameter|Value| |---|---| |format|json| |precision|daily| |precision|hourly| |precision|minutely| > Example responses > Successful response — current marine conditions or a date-keyed forecast ```json { "location": { "latitude": "51.50000", "longitude": "2.00000", "country_name": "United Kingdom", "state_prov": "", "city": "", "locality": "", "elevation": "", "timezone": "Etc/GMT", "timezone_abbreviation": "GMT" }, "current": { "timestamp": "2026-07-24T11:30", "wave_height": 0.52, "wave_direction": 12, "wave_period": 5.75, "wind_wave_peak_period": 0.95, "wind_wave_height": 0, "wind_wave_direction": 220, "wind_wave_period": 0, "swell_wave_height": 0.52, "swell_wave_direction": 13, "swell_wave_period": 5.05, "swell_wave_peak_period": 6.3, "sea_level_height_msl": -1.04, "sea_surface_temperature": 20.5, "ocean_current_velocity": 0.4, "ocean_current_direction": 117 } } ``` ```json { "location": { "location_string": "Denver, Colorado", "country_name": "United States", "state_prov": "Colorado", "city": "Denver", "locality": "", "latitude": "39.73924", "longitude": "-104.98486", "elevation": "1609", "timezone": "America/Denver", "timezone_abbreviation": "GMT-6" }, "current": { "timestamp": "2026-07-24T05:30", "wave_height": null, "wave_direction": null, "wave_period": null, "wind_wave_peak_period": null, "wind_wave_height": null, "wind_wave_direction": null, "wind_wave_period": null, "swell_wave_height": null, "swell_wave_direction": null, "swell_wave_period": null, "sea_level_height_msl": null, "sea_surface_temperature": null, "ocean_current_velocity": null, "ocean_current_direction": null } } ``` ```json { "location": { "latitude": "51.50000", "longitude": "2.00000", "country_name": "United Kingdom", "state_prov": "", "city": "", "locality": "", "elevation": "", "timezone": "Etc/GMT", "timezone_abbreviation": "GMT" }, "forecast": { "2026-07-25": { "daily": { "timestamp": "2026-07-25", "wave_height_max": 0.84, "wave_direction_dominant": 278, "wave_period_max": 4.05, "wind_wave_height_max": 0.78, "wind_wave_direction_dominant": 231, "wind_wave_period_max": 3.3, "wind_wave_peak_period_max": 4.3, "swell_wave_height_max": 0.56, "swell_wave_direction_dominant": 4, "swell_wave_period_max": 4.85, "swell_wave_peak_period_max": 6.3 } }, "2026-07-26": { "daily": { "timestamp": "2026-07-26", "wave_height_max": 1.02, "wave_direction_dominant": 238, "wave_period_max": 4.65, "wind_wave_height_max": 0.8, "wind_wave_direction_dominant": 269, "wind_wave_period_max": 3.3, "wind_wave_peak_period_max": 5.2, "swell_wave_height_max": 0.86, "swell_wave_direction_dominant": 218, "swell_wave_period_max": 4.7, "swell_wave_peak_period_max": 6.3 } } } } ``` > Bad Request — invalid or incomplete parameters ```json { "timestamp": "2026-07-24T11:35:05.439Z", "status": 400, "message": "Invalid latitude or longitude values. Latitude must be between -90 and 90, and longitude must be between -180 and 180", "error": "invalid-params", "path": "/v1.0/weather/marine" } ``` ```json { "timestamp": "2026-07-24T11:35:18.421Z", "status": 400, "message": "Invalid IP address", "error": "invalid-params", "path": "/v1.0/weather/marine" } ``` ```json { "timestamp": "2026-07-24T11:35:19.621Z", "status": 400, "message": "Invalid precision", "error": "invalid-params", "path": "/v1.0/weather/marine" } ``` ```json { "timestamp": "2026-07-24T11:35:20.399Z", "status": 400, "message": "Invalid timezone", "error": "error", "path": "/v1.0/weather/marine" } ``` ```json { "timestamp": "2026-07-24T11:35:05.950Z", "status": 400, "message": "Forecast date range must be within 2026-07-24 to 2026-08-08", "error": "params-exception-error", "path": "/v1.0/weather/marine" } ``` ```json { "error": "Invalid Param Exception", "message": "please pass correct parameters", "path": "/v1.0/weather/marine", "status": 400, "timestamp": "2026-07-24T11:35:30.525Z" } ``` > Not Found — location could not be resolved ```json { "timestamp": "2026-07-24T11:35:17.921Z", "status": 404, "message": "Location not found", "error": "error", "path": "/v1.0/weather/marine" } ``` #### Responses |Status|Meaning|Description|Schema| |---|---|---|---| |200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response — current marine conditions or a date-keyed forecast|[MarineResponse](#marineresponse)| |400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — invalid or incomplete parameters|[ErrorResponse](#errorresponse)| |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — location could not be resolved|[ErrorResponse](#errorresponse)| #### Response Headers |Status|Header|Type|Format|Description| |---|---|---|---|---| |200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| |400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| |404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.| To perform this operation, you must be authenticated by means of one of the following methods: ApiKeyAuthHeader, ApiKeyAuthQuery ## Schemas ### MarineResponse Marine weather response. current and forecast are mutually exclusive: current is returned when startDate/endDate are omitted, forecast is returned when both are supplied. location is always present. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |location|[WeatherLocation](#weatherlocation)|true|none|Location information. Shape depends on how the location was resolved (coordinates, IP, or address/city name).| |current|[CurrentMarine](#currentmarine)|false|none|Current marine conditions. Present only when startDate/endDate are not supplied.| |forecast|[MarineForecastData](#marineforecastdata)|false|none|Date-keyed forecast data. Present only when startDate and endDate are both supplied.| ### LocationByCoordinates Location data when the target is specified by GPS coordinates (lat/long). #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |latitude|string|true|none|Geographic latitude coordinate in decimal degrees, ranging from -90 (South Pole) to +90 (North Pole). Returned as a string, not a number.| |longitude|string|true|none|Geographic longitude coordinate in decimal degrees, ranging from -180 (West) to +180 (East). Returned as a string, not a number.| |country_name|string|true|none|Full name of the country corresponding to the provided coordinates.| |state_prov|string|true|none|State, province, or primary administrative division name for the location. Can be an empty string.| |city|string|true|none|City or municipal area name associated with the coordinate location. Can be an empty string.| |locality|string|false|none|Specific locality, neighborhood, district, or village name within the broader area. Can be an empty string.| |elevation|string|false|none|Height above mean sea level in meters for the specified coordinates. Returned as a string, not a number, and can be an empty string when unavailable.| |timezone|string|true|none|IANA timezone database identifier for the location (e.g., America/New_York, Europe/London).| |timezone_abbreviation|string|true|none|Abbreviated timezone representation based on current offset (e.g., EST, GMT, PST).| ### LocationByIP Location data when the target is inferred from an IP address. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |continent_code|string|true|none|Two-letter continent code (e.g., NA for North America, EU for Europe, AS for Asia).| |continent_name|string|true|none|Full name of the continent where the IP address is registered.| |country_code2|string|true|none|ISO 3166-1 alpha-2 two-letter country code (e.g., US, GB, FR).| |country_code3|string|true|none|ISO 3166-1 alpha-3 three-letter country code (e.g., USA, GBR, FRA).| |country_name|string|true|none|Common name of the country associated with the IP address.| |country_name_official|string|true|none|Official long-form country name as recognized internationally (e.g., United States of America).| |is_eu|boolean|false|none|Boolean flag indicating whether the country is a member state of the European Union.| |state_prov|string|true|none|State, province, or primary administrative division associated with the IP location.| |state_code|string|false|none|ISO 3166-2 subdivision code for the state or province (e.g., CA for California).| |district|string|false|none|District, county, or secondary administrative division within the region. Can be an empty string.| |city|string|true|none|City or urban area name where the IP address is geographically registered.| |zipcode|string|false|none|Postal code or ZIP code for the approximate location of the IP address. Can be an empty string.| |latitude|string|true|none|Geographic latitude in decimal degrees for the IP geolocation, ranging from -90 to +90. Returned as a string, not a number.| |longitude|string|true|none|Geographic longitude in decimal degrees for the IP geolocation, ranging from -180 to +180. Returned as a string, not a number.| |locality|string|false|none|Specific locality, neighborhood, or small area designation within the city. Can be an empty string.| |elevation|string|false|none|Elevation above mean sea level in meters for the IP geolocation. Returned as a string, not a number, and can be an empty string when unavailable.| |timezone|string|true|none|IANA timezone database identifier for the IP location (e.g., America/Chicago, Asia/Tokyo).| |timezone_abbreviation|string|true|none|Current timezone abbreviation based on local offset (e.g., CST, JST, UTC).| ### LocationByAddress Location data when the target is specified by a city name or address string. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |location_string|string|true|none|Original location query string as submitted, including full address or place name.| |country_name|string|true|none|Resolved country name derived from the geocoded location query.| |state_prov|string|true|none|State, province, or primary administrative division identified from the location.| |city|string|true|none|City or municipal area name extracted from the geocoded location.| |locality|string|false|none|Specific locality, neighborhood, suburb, or village within the geocoded area. Can be an empty string.| |latitude|string|true|none|Geocoded latitude coordinate in decimal degrees, ranging from -90 to +90. Returned as a string, not a number.| |longitude|string|true|none|Geocoded longitude coordinate in decimal degrees, ranging from -180 to +180. Returned as a string, not a number.| |elevation|string|false|none|Elevation above mean sea level in meters at the geocoded coordinates. Returned as a string, not a number.| |timezone|string|true|none|IANA timezone database identifier for the geocoded location (e.g., America/Los_Angeles).| |timezone_abbreviation|string|true|none|Current timezone abbreviation for the location based on local offset (e.g., PDT, CET).| ### CurrentMarine Current marine weather conditions including wave, swell, sea level, and current data. For locations with no nearby ocean data (inland/landlocked), every field below timestamp is returned as null instead of an error. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |timestamp|string|true|none|Local timestamp of the current observation, in `YYYY-MM-DDTHH:mm` format — not full ISO 8601 (no seconds, no timezone offset/`Z`).| |wave_height|number|true|none|Significant height of combined sea waves in meters. Null where no ocean data is available for this location.| |wave_direction|number|true|none|Direction from which the combined waves are coming, in degrees. Null where no ocean data is available for this location.| |wave_period|number|true|none|Average period of combined sea waves in seconds. Null where no ocean data is available for this location.| |wind_wave_height|number|true|none|Height of locally generated wind waves in meters. Null where no ocean data is available for this location.| |wind_wave_direction|number|true|none|Direction from which the wind waves are coming, in degrees. Null where no ocean data is available for this location.| |wind_wave_period|number|true|none|Average period of locally generated wind waves in seconds. Null where no ocean data is available for this location.| |wind_wave_peak_period|number|true|none|Peak period of locally generated wind waves in seconds. Frequently null even at locations with other wave data present.| |swell_wave_height|number|true|none|Height of swell waves in meters. Null where no ocean data is available for this location.| |swell_wave_direction|number|true|none|Direction from which the swell waves are coming, in degrees. Null where no ocean data is available for this location.| |swell_wave_period|number|true|none|Average period of swell waves in seconds. Null where no ocean data is available for this location.| |swell_wave_peak_period|number|true|none|Peak period of swell waves in seconds. Frequently null even at locations with other wave data present.| |sea_level_height_msl|number|true|none|Sea level height relative to mean sea level in meters. Null where no ocean data is available for this location.| |sea_surface_temperature|number|true|none|Temperature of the ocean surface in degrees Celsius. Null where no ocean data is available for this location.| |ocean_current_velocity|number|true|none|Speed of the ocean current in km/h. Null where no ocean data is available for this location.| |ocean_current_direction|number|true|none|Direction of the ocean current, in degrees. Null where no ocean data is available for this location.| ### MarineDaily Daily marine forecast summary with wave, wind-wave, and swell statistics for one day. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |timestamp|string(date)|true|none|Date of this forecast entry in YYYY-MM-DD format.| |wave_height_max|number|true|none|Maximum significant wave height for the day, in meters.| |wave_direction_dominant|integer|true|none|Dominant direction of waves for the day, in degrees.| |wave_period_max|number|true|none|Maximum wave period for the day, in seconds.| |wind_wave_height_max|number|true|none|Maximum wind-driven wave height for the day, in meters.| |wind_wave_direction_dominant|integer|true|none|Dominant wind-wave direction for the day, in degrees.| |wind_wave_period_max|number|true|none|Maximum wind-wave period for the day, in seconds.| |wind_wave_peak_period_max|number|true|none|Maximum peak period of wind-driven waves for the day, in seconds. Frequently null.| |swell_wave_height_max|number|true|none|Maximum swell wave height for the day, in meters.| |swell_wave_direction_dominant|integer|true|none|Dominant swell wave direction for the day, in degrees.| |swell_wave_period_max|number|true|none|Maximum swell wave period for the day, in seconds.| |swell_wave_peak_period_max|number|true|none|Maximum peak period of swell waves for the day, in seconds. Frequently null.| ### MarineHourly Hourly marine weather reading with wave, swell, and sea surface data for a single hour. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |timestamp|string|true|none|Local timestamp of this hourly entry, in `YYYY-MM-DDTHH:mm` format — not full ISO 8601 (no seconds, no timezone offset/`Z`).| |wave_height|number|true|none|Significant wave height at the given hour, in meters.| |wave_direction|integer|true|none|Wave direction at the given hour, in degrees.| |wave_period|number|true|none|Wave period at the given hour, in seconds.| |wind_wave_height|number|true|none|Wind-driven wave height at the given hour, in meters.| |wind_wave_peak_period|number|true|none|Peak period of wind-driven waves at the given hour, in seconds.| |wind_wave_direction|integer|true|none|Wind-wave direction at the given hour, in degrees.| |wind_wave_period|number|true|none|Wind-wave period at the given hour, in seconds.| |swell_wave_height|number|true|none|Swell wave height at the given hour, in meters.| |swell_wave_direction|integer|true|none|Swell wave direction at the given hour, in degrees.| |swell_wave_period|number|true|none|Swell wave period at the given hour, in seconds.| |swell_wave_peak_period|number|true|none|Peak period of swell waves at the given hour, in seconds.| |sea_surface_temperature|number|true|none|Sea surface temperature at the given hour, in degrees Celsius.| |sea_level_height_msl|number|true|none|Sea level height relative to mean sea level at the given hour, in meters.| |ocean_current_velocity|number|true|none|Speed of ocean current at the given hour, in km/h.| |ocean_current_direction|integer|true|none|Direction of ocean current at the given hour, in degrees.| ### MarineMinutely Minute-by-minute marine data point for ocean current and sea level measurements. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |timestamp|string|true|none|Local timestamp of this minute-level entry, in `YYYY-MM-DDTHH:mm` format — not full ISO 8601 (no seconds, no timezone offset/`Z`).| |ocean_current_velocity|number|true|none|Speed of ocean current at this minute, in km/h.| |ocean_current_direction|integer|true|none|Direction of ocean current at this minute, in degrees.| |sea_level_height_msl|number|true|none|Sea level height relative to mean sea level at this minute, in meters.| ### ErrorResponse Standard error envelope returned by the API on failed requests. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |error|string|false|none|Short error category or exception type.| |message|string|true|none|Human-readable error message describing the failure.| |path|string|false|none|API endpoint path that produced the error.| |status|integer|false|none|HTTP status code returned with the error.| |timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).| ### WeatherLocation Location information. Shape depends on how the location was resolved (coordinates, IP, or address/city name). #### Properties oneOf |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |*anonymous*|[LocationByCoordinates](#locationbycoordinates)|false|none|Location data when the target is specified by GPS coordinates (lat/long).| xor |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |*anonymous*|[LocationByIP](#locationbyip)|false|none|Location data when the target is inferred from an IP address.| xor |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |*anonymous*|[LocationByAddress](#locationbyaddress)|false|none|Location data when the target is specified by a city name or address string.| ### MarineForecastData Forecast data keyed by date (YYYY-MM-DD). Each key is a forecast date and its value is a MarineForecastDay. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |**additionalProperties**|[MarineForecastDay](#marineforecastday)|false|none|Marine forecast for a single day. Exactly one of daily, hourly, or minutely is present, matching whichever precision value was requested (default daily) — the other two are omitted, not just empty.| ### MarineForecastDay Marine forecast for a single day. Exactly one of daily, hourly, or minutely is present, matching whichever precision value was requested (default daily) — the other two are omitted, not just empty. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |daily|[MarineDaily](#marinedaily)|false|none|Daily marine forecast summary. Present when precision=daily (the default).| |hourly|[[MarineHourly](#marinehourly)]|false|none|Array of hourly marine readings for the day. Present when precision=hourly.| |minutely|[[MarineMinutely](#marineminutely)]|false|none|Array of minute-by-minute marine data points for the day. Present when precision=minutely.|