API Documentation
The API endpoint /v1/marine accepts a geographical coordinate, a list of marine variablesand responds with a JSON hourly marine weather forecast for 7 days. Time always starts at 0:00 today.All URL parameters are listed below:
| Parameter | Format | Required | Default | Description |
|---|---|---|---|---|
| latitude, longitude | Floating point | Yes | Geographical WGS84 coordinates of the location. Multiple coordinates can be commaseparated. E.g. &latitude=52.52,48.85&longitude=13.41,2.35. To return datafor multiple locations the JSON output changes to a list of structures. CSV and XLSXformats add a column location_id. | |
| hourly | String array | No | A list of weather variables which should be returned. Values can be comma separated, ormultiple&hourly= parameter in the URL can be used. | |
| daily | String array | No | A list of daily weather variable aggregations which should be returned. Values can becomma separated, or multiple &daily= parameter in the URL can be used. Ifdaily weather variables are specified, parameter timezone is required. | |
| current | String array | No | A list of variables to get current conditions. | |
| timeformat | String | No | iso8601 | If format unixtime is selected, all time values are returned in UNIX epochtime in seconds. Please note that all timestamp are in GMT+0! For daily values with unixtimestamps, please applyutc_offset_seconds again to get the correct date. |
| timezone | String | No | GMT | If timezone is set, all timestamps are returned as local-time and data isreturned starting at 00:00 local-time. Any time zone name from thetime zone databaseis supported. If auto is set as a time zone, the coordinates will be automaticallyresolved to the local time zone. For multiple coordinates, a comma separated list of timezonescan be specified. |
| past_days | Integer (0-92) | No | 0 | If past_days is set, yesterday or the day before yesterday data are also returned. |
| forecast_days | Integer (0-8) | No | 5 | Per default, 7 days are returned. Up to 8 days of forecast are possible. |
| forecast_hours past_hours | Integer (>0) | No | Similar to forecast_days, the number of timesteps of hourly data can controlled. Instead of using the current day as a reference, the current hour is used. | |
| start_date end_date | String (yyyy-mm-dd) | No | The time interval to get weather data. A day must be specified as an ISO8601 date (e.g.2022-06-30). | |
| start_hour end_hour | String (yyyy-mm-ddThh:mm) | No | The time interval to get weather data for hourly data. Time must be specified as an ISO8601 date (e.g.2022-06-30T12:00). | |
| length_unit | String | No | metric | Options metric and imperial |
| cell_selection | String | No | sea | Set a preference how grid-cells are selected. The default land finds asuitable grid-cell on land withsimilar elevation to the requested coordinates using a 90-meter digital elevationmodel.sea prefers grid-cells on sea. nearest selects the nearest possiblegrid-cell. |
| apikey | String | No | Only required to commercial use to access reserved API resources for customers. Theserver URL requires the prefix customer-. Seepricing for more information. |
Additional optional URL parameters will be added. For API stability, no required parameters willbe added in the future!
See Also
OpenWeatherMap API guide - OpenWeatherMapWeather API - OpenWeatherHow to start to work with Openweather APIHow to start to work with Openweather APIHourly Parameter Definition
The parameter &hourly= accepts the following values. Most weather variables are givenas an instantaneous value for the indicated hour. Some variables like precipitation are calculatedfrom the preceding hour as an average or sum.
| Variable | Valid time | Unit | Description |
|---|---|---|---|
| wave_height wind_wave_height swell_wave_height | Instant | Meter | Wave height of significant mean, wind and swell waves. Wave directions are always reported as the direction the waves come from. 0° = From north towards south; 90° = From east |
| wave_direction wind_wave_direction swell_wave_direction | Instant | ° | Mean direction of mean, wind and swell waves |
| wave_period wind_wave_period swell_wave_period | Instant | Seconds | Period between mean, wind and swell waves. |
| wind_wave_peak_period swell_wave_peak_period | Instant | Seconds | Peak period between wind and swell waves. |
| ocean_current_velocity | Instant | km/h (mph, m/s, knots) | Velocity of ocean current considering Eulerian, Waves and Tides. |
| ocean_current_direction | Instant | ° | Direction following the flow of the current. E.g. where the current is heading towards. 0° = Going north; 90° = Towards east. |
Daily Parameter Definition
Aggregations are a simple 24 hour aggregation from hourly values. The parameter &daily= accepts the following values:
| Variable | Unit | Description |
|---|---|---|
| wave_height_max wind_wave_height_max swell_wave_height_max | Meter | Maximum wave height on a given day for mean, wind and swell waves |
| wave_direction_dominant wind_wave_direction_dominant swell_wave_direction_dominant | ° | Dominant wave direction of mean, wind and swell waves |
| wave_period_max wind_wave_period_max swell_wave_period_max | Seconds | Maximum wave period of mean, wind and swell |
| wind_wave_peak_period_max swell_wave_peak_period_max | Seconds | Maximum peak period between wind and swell waves. |
JSON Return Object
On success a JSON object will be returned.
"latitude": 52.52, "longitude": 13.419, "elevation": 44.812, "generationtime_ms": 2.2119, "utc_offset_seconds": 0, "timezone": "Europe/Berlin", "timezone_abbreviation": "CEST", "hourly": { "time": ["2022-07-01T00:00", "2022-07-01T01:00", "2022-07-01T02:00", ...], "wave_height": [1, 1.7, 1.7, 1.5, 1.5, 1.8, 2.0, 1.9, 1.3, ...] }, "hourly_units": { "wave_height": "m" }, | Parameter | Format | Description |
|---|---|---|
| latitude, longitude | Floating point | WGS84 of the center of the weather grid-cell which was used to generate this forecast.This coordinate might be a few kilometers away from the requested coordinate. |
| generationtime_ms | Floating point | Generation time of the weather forecast in milliseconds. This is mainly used forperformance monitoring and improvements. |
| utc_offset_seconds | Integer | Applied timezone offset from the &timezone= parameter. |
| timezone timezone_abbreviation | String | Timezone identifier (e.g. Europe/Berlin) and abbreviation (e.g.CEST) |
| hourly | Object | For each selected weather variable, data will be returned as a floating point array.Additionally atime array will be returned with ISO8601 timestamps. |
| hourly_units | Object | For each selected weather variable, the unit will be listed here. |
| daily | Object | For each selected daily weather variable, data will be returned as a floating pointarray. Additionally a time array will be returned with ISO8601 timestamps. |
| daily_units | Object | For each selected daily weather variable, the unit will be listed here. |
Errors
In case an error occurs, for example a URL parameter is not correctly specified, a JSON errorobject is returned with a HTTP 400 status code.
"error": true, "reason": "Cannot initialize WeatherVariable from invalid String value tempeture_2m for key hourly" All users of Open-Meteo data must provide a clear attribution to DWD as well as a reference toOpen-Meteo.
