NAV Navbar
python javascript shell
  • Introduction
  • Authentication
  • Sources
  • Point Request
  • Area Request
  • Astronomy 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 in the dashboard.

    Storm Glass expects the 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 provides data from several weather institutes around the world. Each source contains its' own set of attributes and the data 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 168 hours Global Handpicked local forecast in each geographical area

    Attributes per source

    Attribute noaa meteo dwd meto fcoo fmi yr smhi sg
    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
      }
    }
    

    Point Requests are used to retrieve data for a single coordinate.

    To get data for land and lakes – simply send in a coordinate on land or on a lake.

    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 all (see list below) Comma separeted list of params included in response, Eg swellHeight,waveHeight
    start Today at 00.00 UTC timestamp for first forecast hour
    end all UTC timestamp for last forecast hour
    source all Specify a single source. Eg noaa or dwd

    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. 0° indicates current coming from north
    currentSpeed Speed of current in meters per second
    gust Wind gust in meters per second
    humidity Relative humidity in percent
    iceCover Proportion, 0-1
    precipitation Mean precipitation in kg/m²
    seaLevel Height of sea level in MLLW in meters (tide)
    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 in meters
    wavePeriod Period of combined wind and swell waves in seconds
    windWaveDirection Direction of wind waves. 0° indicates waves coming from north
    windWaveHeight Height of wind waves in meters
    windWavePeriod Period of wind waves in seconds
    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.

    Since the response for this request will have a larger payload than the request for a single point, there will only be one value for each attribute. This will be the value from the "most local" weather source that we have available.

    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

    Astronomy Request

    import arrow
    import requests
    
    # Get first hour of today
    start = arrow.now().floor('day')
    
    # Set how many days we want astronomy data for
    numberOfDays = 7
    
    response = requests.get(
      'https://api.stormglass.io/astronomy',
      params={
        'lat': 58.7984,
        'lng': 17.8081,
        'start': start.to('UTC').timestamp,  # Convert to UTC timestamp
        'numberOfDays': numberOfDays
      },
      headers={
        'Authorization': 'example-api-key'
      }
    )
    
    # Do something with response data.
    json_data = response.json()
    
    curl "https://api.stormglass.io/astronomy?lat=58.7984&lng=17.8081&numberOfDays=7"
      -H "Authorization: example-api-key"
    
    const lat = 58.7984;
    const lng = 17.8081;
    const numberOfDays = 7;
    
    fetch(`https://api.stormglass.io/astronomy?lat=${lat}&lng=${lng}&numberOfDays=${numberOfDays}`, {
      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:

    {
        "days": [
            {
                "astronomicalDawn": "2018-11-22T04:29:13+00:00",
                "astronomicalDusk": "2018-11-22T16:43:25+00:00",
                "civilDawn": "2018-11-22T06:07:58+00:00",
                "civilDusk": "2018-11-22T15:04:39+00:00",
                "moonFraction": 0.9773405348657047,
                "moonPhase": {
                    "closest": {
                        "text": "Full moon",
                        "time": "2018-11-23T10:05:00+00:00",
                        "value": 0.5
                    },
                    "current": {
                        "text": "Waxing gibbous",
                        "time": "2018-11-22T00:00:00+00:00",
                        "value": 0.45190179144442527
                    }
                },
                "moonrise": "2018-11-22T13:58:41.948883+00:00",
                "moonset": "2018-11-22T05:04:59.690726+00:00",
                "nauticalDawn": "2018-11-22T05:17:04+00:00",
                "nauticalDusk": "2018-11-22T15:55:34+00:00",
                "sunrise": "2018-11-22T06:56:32+00:00",
                "sunset": "2018-11-22T14:16:06+00:00",
                "time": "2018-11-22T00:00:00+00:00"
            },
            ...
        ],
        "meta": {
            "cost": 1,
            "dailyQuota": 50,
            "lat": 58.7984,
            "lng": 17.8081,
            "requestCount": 1,
            "start": "2018-11-22T00:00:00+00:00"
        }
    }
    

    Retrieve sunrise, sunset, moonrise, moonset and moon phase for a single coordinate.

    HTTP Request

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

    Query Parameters

    Parameter Required Default Description
    lat n/a Latitude of the desired coordinate
    lng n/a Longitude of the desired coordinate
    start Today at 00.00 UTC timestamp for first forecast hour
    numberOfDays 1 For how many days ahead to receive data. max 31 days

    Response format

    The response will be sent back in the form of a JSON object. The resource root contains two objects, the days 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.

    Days

    The days key contains the actual data on a daily basis. One item in the days array contains:

    key value
    time Timestamp in UTC indicating the day for the data
    sunrise Timestamp for sunrise in UTC. Will return null if no sunsrise occurs on the given day
    sunset Timestamp for sunset in UTC. Will return null if no sunset occurs on the given day
    moonrise Timestamp for moonrise in UTC. Will return null if no moonrise occurs on the given day
    moonset Timestamp for moonset in UTC. Will return null if no moonset occurs on the given day
    moonFraction A float number between 0 and 1 indicating how much of the moon is illuminated
    moonPhase Objects describing the current and the closest moon phase
    astronomicalDawn Timestamp in UTC. Will return null if no dawn occurs on the given day
    astronomicalDusk Timestamp in UTC. Will return null if no dusk occurs on the given day
    civilDawn Timestamp for sunset in UTC. Will return null if no dawn occurs on the given day
    civilDusk Timestamp for sunset in UTC. Will return null if no dusk occurs on the given day
    nauticalDawn Timestamp for sunset in UTC. Will return null if no dawn occurs on the given day
    nauticalDusk Timestamp for sunset in UTC. Will return null if no dusk occurs on the given day

    A moon phase is described by an object with the structure according to the table below. “Current” describes the current moon phase and “Closest” gives you the timestamp for the closest phase being one of “New moon”, “First quarter”, “Full moon” or “Third quarter”.

    key value
    time Timestamp in UTC showing what time the moon phase object describes
    text A string describing the moon phase. The possible values are: New moon, Waxing crescent, First quarter, Waxing gibbous, Full moon, Vaning gibbous, Third quarter, Vaning crescent
    value A float value for the phase of the given time

    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.