Overview

Welcome to the Storm Glass API!

Introduction

The Storm Glass API allows you to fetch weather data for any coordinate on the globe 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.

Note: Current version is v1

API Endpoint

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

Authentication

Storm Glass uses API keys to allow access to the API. You can register for a free API key here: register.

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

Authorization: example-api-key

Note: You must replace example-api-key with your personal API key.

Note: When you have signed up your API key is available in the dashboard.

Example

const lat = 58.7984;
const lng = 17.8081;

fetch(`https://api.stormglass.io/v1/weather/point?lat=${lat}&lng=${lng}`, {
  headers: {
    'Authorization': 'example-api-key'
  }
}).then((response) => response.json()).then((jsonData) => {
  // Do something with response data.
});

Weather

The weather requests are used to fetch weather data for a point or an area. The Storm Glass API provides marine weather as well as global weather for land and lakes.

To get marine data you include a coordinate at sea in your request, and to get data for land and lakes - simply send in a coordinate located on land or on a lake.

Point request

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

Available query params:

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 Timestamp in UTC for first forecast hour - UNIX format or URL encoded ISO format.
end all Timestamp in UTC for last forecast hour - UNIX format or URL encoded ISO format.
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
secondarySwellPeriod Direction of secondary swell waves. 0° indicates swell coming from north
secondarySwellDirection Height of secondary swell waves in meters
secondarySwellHeight Period of secondary 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.

Default params returned: airTemperature, airPressure, humidity, cloudCover, currentDirection, currentSpeed, precipitation, visiblity, swellDirection, swellHeight, swellPeriod, waterTemperature, waveDirection, waveHeight, wavePeriod, windWaveDirection, windWaveHeight, windWavePeriod, seaLevel, windDirection, windSpeed, gust

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

Example

const lat = 58.7984;
const lng = 17.8081;
const params = 'waveHeight,airTemperature';

fetch(`https://api.stormglass.io/v1/weather/point?lat=${lat}&lng=${lng}&params=${params}`, {
  headers: {
    'Authorization': 'example-api-key'
  }
}).then((response) => response.json()).then((jsonData) => {
  // Do something with response data.
});

Example response

{
  "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
  }
}

Area request

Area Requests are used to retrieve data for multiple coordinates within a geographic 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 coordinate, there will only be one value for each attribute. This will be the value from the "most local" weather source that we have available.

Area requests are deducted from the daily quota included in your monthly plan and are calculated as 0.5 x (the amount of points within the area). As an example a request for an area containing 100 points will equal to 50 single point requests.

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

*Either polygon or box must be defined

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
GET
https://api.stormglass.io/v1/weather/area

Example

const box = '60,20:58,17';

fetch(`https://api.stormglass.io/v1/weather/area?box=${box}`, {
  headers: {
    'Authorization': 'example-api-key'
  }
}).then((response) => response.json()).then((jsonData) => {
  // Do something with response data.
});

Example response

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

Tide

The Storm Glass API provides tide data globally.

Extremes Point Request

Retrieve information about high and low tide for a single coordinate. If nothing is specified the returned values will be in relative to MLLW.

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 Timestamp in UTC for first forecast hour - UNIX format or URL encoded ISO format.
end 10 days from start Timestamp in UTC for last forecast hour - UNIX format or URL encoded ISO format.
datum MLLW Datum values will be relative to. Either MLLW or MSL.

Response format

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

The meta data will also contain a station key with information about the station providing the data.

key value
name Name of tide station
distance Distance between station and requested coordinate in km
lat  Latitude of tide station
lng  Longitude of tide station
source Tide station owner

Extremas

The extremas key contains a list of extreme points occuring during the given time interval. One item in the array will contain:

key value
time Timestamp in UTC
height  Height in meters
type  Type of exreme. Either low or high
GET
https://api.stormglass.io/v1/tide/extremes/point

Example

const lat = 60.936;
const lng = 5.114;

fetch(`https://api.stormglass.io/v1/tide/extremes/point?lat=${lat}&lng=${lng}&start=2019-03-15&end=2019-03-15`, {
  headers: {
    'Authorization': 'example-api-key'
  }
}).then((response) => response.json()).then((jsonData) => {
  // Do something with response data.
});

Example response

{
    "extremas": [
        {
            "height": "1.18",
            "time": "2019-03-15 03:40:44+00:00",
            "type": "high"
        },
        {
            "height": "0.60",
            "time": "2019-03-15 09:53:54+00:00",
            "type": "low"
        },
        {
            "height": "1.20",
            "time": "2019-03-15 16:23:29+00:00",
            "type": "high"
        },
        {
            "height": "0.61",
            "time": "2019-03-15 22:39:15+00:00",
            "type": "low"
        }
    ],
    "meta": {
        "cost": 1,
        "dailyQuota": 800,
        "end": "2019-03-16 00:00",
        "lat": 60.936,
        "lng": 5.114,
        "requestCount": 145,
        "start": "2019-03-15 00:00",
        "station": {
            "distance": 61,
            "lat": 60.398046,
            "lng": 5.320487,
            "name": "bergen",
            "source": "sehavniva.no"
        }
    }
}

Stations List Request

The Tide Stations List Requests is used to list all available stations.

Note: Querying information about tide stations is free of charge.

Response format

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

Stations

The stations key contains a list of all available stations and each station consists of:

key value
name Name of tide station
lat Latitude of tide station
lng Longitude of tide station
source Tide station owner
GET
https://api.stormglass.io/v1/tide/stations

Example

fetch(`https://api.stormglass.io/v1/tide/stations`, {
  headers: {
    'Authorization': 'example-api-key'
  }
}).then((response) => response.json()).then((jsonData) => {
  // Do something with response data.
});

Example response

{
    "stations": [
      {
        "lat": 61.933776,
        "lng": 5.11331,
        "name": "måløy",
        "source": "sg"
      },
      {
        "lat": 63.113859,
        "lng": 7.734352,
        "name": "kristiansund",
        "source": "sg"
      },
      ...
    ],
    "meta": {
        "cost": 0,
        "dailyQuota": 800,
        "requestCount": 145
    }
}

Stations Area Request

The Tide Stations Area Request will list all available tide stations within a defined geographic area.

Query Parameters

Parameter Required Default Description
box * n/a Top right and bottom left coordinate of box on format: lat,lng:lat,lng

Response format

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

Stations

The stations key contains a list of all available stations and each station consists of:

key value
name Name of tide station
lat Latitude of tide station
lng Longitude of tide station
source Tide station owner
GET
https://api.stormglass.io/v1/tide/stations/area

Example

fetch(`https://api.stormglass.io/v1/tide/stations/area?box=60.1,2:0,-16`, {
  headers: {
    'Authorization': 'example-api-key'
  }
}).then((response) => response.json()).then((jsonData) => {
  // Do something with response data.
});

Example response

{
    "stations": [
      {
        "lat": 61.933776,
        "lng": 5.11331,
        "name": "måløy",
        "source": "sg"
      },
      {
        "lat": 63.113859,
        "lng": 7.734352,
        "name": "kristiansund",
        "source": "sg"
      },
      ...
    ],
    "meta": {
        "cost": 0,
        "dailyQuota": 800,
        "requestCount": 145
    }
}

Astronomy

The Storm Glass API provides astronomical data globally.

Astronomy Point Request

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

Available query params:

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 Timestamp in UTC for first forecast hour - UNIX format or URL encoded ISO format.
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.

The value parameter gives you a float value for the given time where 0.0 or 1.0 equals New moon, 0.25 equals First Quarter, 0.5 equals Full moon and 0.75 equals Third quarter.

Definition of dusk and dawn

Astronomical Dawn occurs when the sun reaches 18° below the horizon, Nautical at 12° and Civil at 6°. The same degrees apply for the Dusk definitions.

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

Example

const lat = 58.7984;
const lng = 17.8081;
const numberOfDays = 7;

fetch(`https://api.stormglass.io/v1/astronomy/point?lat=${lat}&lng=${lng}&numberOfDays=${numberOfDays}`, {
  headers: {
    'Authorization': 'example-api-key'
  }
}).then((response) => response.json()).then((jsonData) => {
  // Do something with response data.
});

Example response

{
    "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"
    }
}

Historical data

To access historical data set the start and end query parameters to the dates you want to query. The maximum length of the response will be 10 days from start.

API data from
Weather 2018-07-01
Tide 2018-03-01
Astronomy "forever"

Example

const lat = 60.936;
const lng = 5.114;
const start = '2018-05-15';
const start = '2018-05-16';


fetch(`https://api.stormglass.io/v1/tide/extremes/point?lat=${lat}&lng=${lng}&start=${start}&end=${end}`, {
  headers: {
    'Authorization': 'example-api-key'
  }
}).then((response) => response.json()).then((jsonData) => {
  // Do something with response data.
});

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.

Name Abbr Resolution Update Frequency Forecast Span Area Description
ICON GWAM icon 0.25°x0.25° Every 12 hours 175 hours Global Germany's National Meteorological Service, the Deutscher Wetterdienst
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

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

Date and time

Dates and times in the Storm Glass API are expressed in UTC timezone.

When sending a request to the API, timestamps in the following formats are accepted:

Name Format
UNIX Timestamp 1542967200
URL Encoded ISO Formatted Timestamp 2018-11-23T10%3A00%3A00%2B00%3A00

Date and time returned from the API will be expressed in ISO format:

Name Format
ISO Formatted Timestamp 2018-11-23T10:00:00+00:00

Error codes

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.
Show examples in: