NAV Navbar
python javascript shell
  • Introduction
  • Authentication
  • Sources
  • Point Request
  • Area Request
  • Errors
  • Introduction

    The Storm Glass Marine Weather API allows you to fetch forecasts for any coordinate in a simple, programmatic way using conventional HTTP requests. When a request is successful, a response will be sent back in the form of a JSON object.

    Authentication

    Storm Glass uses API keys to allow access to the API. You can register for an API key at our developer portal.

    Storm Glass expects API key to be included in all API requests to the server in a header that looks like the following:

    Authorization: example-api-key

    Sources

    Storm Glass include data from several weather institutes around the world. Each source contains its' own set of attributes and is updated individually on different intervals.

    Below you can find two tables overviewing the available data sources and what attributes to expect from each source.

    Available sources

    Name abbr Resolution Update frequency Forecast span Area Description
    NOAA Wavewatch 3 noaa 0.25°x1.0° Every 6 hours 183 hours Global - Except for smaller seas such as
    the Baltic Sea and the Mediterranean Sea
    The National Oceanic and Atmospheric Administration wave model forecast
    NOAA GFS noaa 0.5°x0.5° Daily 240 hours Global The National Oceanic and Atmospheric Administration global forecast system
    Météo-France meteo 0.5°x1.0° Daily 120 hours Global French National Meteorological service, Météo-France
    Deutscher Wetterdienst dwd 0.25°x0.25° Every 12 hours 92 hours The Atlantic coast of Ireland, UK, France,
    Spain and Portugal. The North Sea,
    Mediterranean Sea and Baltic Sea.
    Germany's National Meteorological Service, the Deutscher Wetterdienst
    UK MetOffice meto 0.5°x1.0° Daily 240 hours Global currents and water temperature.
    Wave data for North Sea and North Atlantic
    United Kingdom's national weather service, The UK MetOffice
    FCOO fcoo 0.5°x0.5° Every 12 hours 48 hours Baltic Sea including Gulf of Botnia and Gulf of Finland. Danish Defence Centre for Operational Oceanography
    FMI fmi 0.25°x0.25° Every 4 hours 55 hours Baltic Sea including Gulf of Botnia and Gulf of Finland. The Finnish Meteorological Institution
    YR yr 0.05°x0.05° Every 4 hours 73 hours The Norwegian coast. Norwegian Meteorological Institute and NRK
    SMHI smhi 0.5°x0.5° Every 12 hours 240 hours Baltic Sea including Gulf of Botnia and Gulf of Finland. Swedish Meteorological and Hydrological Institute
    Storm Glass sg 0.25°x0.25° Every 4 hours 120 hours Global Swedish Meteorological and Hydrological Institute

    Attributes per source

    Attribute noaa meteo dwd meto fcoo fmi yr smhi
    airTemperature
    airPressure
    cloudCover
    currentDirection
    currentSpeed
    gust
    humidity
    iceCover
    precipitation
    seaLevel
    snowDepth
    swellDirection
    swellHeight
    swellPeriod
    visiblity
    waterTemperature
    waveDirection
    waveHeight
    wavePeriod
    windWaveDirection
    windWaveHeight
    windWavePeriod
    windDirection
    windSpeed

    Point Request

    import arrow
    import requests
    
    # Get first hour of today
    start = arrow.now().floor('day')
    
    # Get last hour of today
    end = arrow.now().ceil('day')
    
    response = requests.get(
      'https://api.stormglass.io/point',
      params={
        'lat': 58.7984,
        'lng': 17.8081,
        'params': ','.join(['waveHeight', 'airTemperature']),
        'start': start.to('UTC').timestamp,  # Convert to UTC timestamp
        'end': end.to('UTC').timestamp  # Convert to UTC timestamp
      },
      headers={
        'Authorization': 'example-api-key'
      }
    )
    
    # Do something with response data.
    json_data = response.json()
    
    curl "https://api.stormglass.io/point?lat=58.7984&lng=17.8081&params=waveHeight,airTemperature"
      -H "Authorization: example-api-key"
    
    const lat = 58.7984;
    const lng = 17.8081;
    const params = 'waveHeight,airTemperature';
    
    fetch(`https://api.stormglass.io/point?lat=${lat}&lng=${lng}&params=${params}`, {
      headers: {
        'Authorization': 'example-api-key'
      }
    }).then(function(response) {
      // Do something with response data.
      const jsonData = response.json();
    });
    

    The above requests returns JSON structured like this:

    {
      "hours": [
        {
          "time": "2018-01-19T17:00:00+00:00",
          "airTemperature": [
            {
              "source": "smhi", 
              "value": "-2.6"
            }
          ],
          "waveHeight": [
            {
              "source": "noaa",
              "value": 2.1
            },
            {
              "source": "meteo",
              "value": 2.3
            }
          ]
          ...
        }
      ], 
      "meta": {
        "dailyQuota": 5, 
        "lat": 58.7984, 
        "lng": 17.8081, 
        "requestCount": 2
      }
    }
    

    Retrieve forecast for a singe coordinate.

    HTTP Request

    GET https://api.stormglass.io/point

    Query Parameters

    Parameter Required Default Description
    lat n/a Latitude of the desired coordinate
    lng n/a Longitude of the desired coordinate
    params See list below Comma separeted list of params to include in response. Eg swellHeight,waveHeight
    start Today at 00.00 UTC timestamp for first forecast hour. At most 48 hours before current UTC time.
    end all UTC timestamp for last forecast.

    Response format

    The response will be sent back in the form of a JSON object. The resource root contains two objects, the hours and the meta keys.

    Meta

    The meta key contains information about the API request. Such as requested latitude and longitude, your daily quota and how many requests you've made so far today.

    Hours

    The hours key contains the actual weather data on an hourly basis. One item in the hours array contains:

    key value
    time Timestamp in UTC
    airTemperature  Air temperature in degrees celsius
    airPressure  Air pressure in hPa
    cloudCover Total cloud coverage in percent
    currentDirection Direction of current.
    currentSpeed Speed of current in meters per second.
    gust Wind gust in m/s
    humidity Relative humidity in percent
    iceCover Proportion, 0-1
    precipitation Mean precipitation in kg/m²
    seaLevel Height of sea level in MLLW (tides).
    snowDepth Depth of snow in meters
    swellDirection Direction of swell waves. 0° indicates swell coming from north
    swellHeight Height of swell waves in meters
    swellPeriod Period of swell waves in seconds
    visiblity Horizontal visibility in km
    waterTemperature Water temperature in degrees celsius
    waveDirection Direction of combined wind and swell waves. 0° indicates waves coming from north
    waveHeight Height of combined wind and swell waves
    wavePeriod Period of combined wind and swell waves
    windWaveDirection Direction of wind waves. 0° indicates waves coming from north
    windWaveHeight Height of wind waves
    windWavePeriod Period of wind waves
    windDirection Direction of wind. 0° indicates wind coming from north
    windSpeed Speed of wind in meters per second

    Each parameter (eg. swellHeight) is a list that contains an object for each available source. The object consists of source and value.

    Area Request

    import requests
    
    response = requests.get(
      'https://api.stormglass.io/area',
      params={
          'box': '60,20:58,17',
          'params': 'waveHeight,airTemperature'
      },
      headers={
        'Authorization': 'example-api-key'
      }
    )
    
    # Do something with response data.
    json_data = response.json()
    
    curl "https://api.stormglass.io/area?box=60,20:58,17"
      -H "Authorization: example-api-key"
    
    const box = '60,20:58,17';
    
    fetch(`https://api.stormglass.io/point?box=${box}`, {
      headers: {
        'Authorization': 'example-api-key'
      }
    }).then(function(response) {
      // Do something with response data.
      const jsonData = response.json();
    });
    

    The above requests returns JSON structured like this:

    {
      "grid": {
          "58": {
              "17": [
                {
                    "time": "2018-09-27T17:00:00+00:00",
                    "airTemperature": -2.6,
                    "waveHeight": 2.3,
                },
                ...
              ],
              "18": [ ... ]
          },
          "59": { ... },
          ...
      }, 
      "meta": {
        "dailyQuota": 150,
        "cost": 10,
        "date: "2018-09-27",
        "box": [
            [60, 20],
            [58, 17]
        ],
        "requestCount": 12
      }
    }
    

    Retrieve forecast for an area described by either a box or a polygon.

    HTTP Request

    GET https://api.stormglass.io/area

    Query Parameters

    Parameter Required Default Description
    box n/a Top right and bottom left coordinate of box on format: lat,lng:lat,lng
    polygon n/a List of coordinates describing area. Will be connected in order left to right: lat,lng:lat,lng:lat,lng
    date Today Forecast date on format: YYYY-MM-DD
    params all Comma separeted list of params to include in response. Eg swellHeight,waveHeight
    step_size 1 Lenght between coordinates in grid. Valid values are 1, 0.5 and 0.25

    Response format

    The response will be sent back in the form of a JSON object. The resource root contains two objects, the grid and the meta keys.

    Meta

    The meta key contains information about the API request. Such as requested latitude and longitude, your daily quota and how many requests you've made so far today.

    Grid

    The grid is an object consisting of latitudes with nested longitudes. Each longitude contains weather data on hourly basis. One hour can contain the following attributes:

    key value
    time Timestamp in UTC
    airTemperature  Air temperature in degrees celsius
    airPressure  Air pressure in hPa
    cloudCover Total cloud coverage in percent
    currentDirection Direction of current.
    currentSpeed Speed of current in meters per second.
    gust Wind gust in m/s
    humidity Relative humidity in percent
    iceCover Proportion, 0-1
    precipitation Mean precipitation in kg/m²
    seaLevel Height of sea level in MLLW (tides).
    snowDepth Depth of snow in meters
    swellDirection Direction of swell waves. 0° indicates swell coming from north
    swellHeight Height of swell waves in meters
    swellPeriod Period of swell waves in seconds
    visiblity Horizontal visibility in km
    waterTemperature Water temperature in degrees celsius
    waveDirection Direction of combined wind and swell waves. 0° indicates waves coming from north
    waveHeight Height of combined wind and swell waves
    wavePeriod Period of combined wind and swell waves
    windWaveDirection Direction of wind waves. 0° indicates waves coming from north
    windWaveHeight Height of wind waves
    windWavePeriod Period of wind waves
    windDirection Direction of wind. 0° indicates wind coming from north
    windSpeed Speed of wind in meters per second

    Errors

    The Storm Glass API uses the following response error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is invalid.
    429 Too Many Requests -- You've reached your daily limit.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.