# Historical The historical endpoint contains global historical weather data starting from 2014. The base of stormglass.io's historical weather data is the re-analyzed global weather dataset, ERA5, produced by the European forecasting center ECMWF. Each response contains data for a time period of up to 10 days. The endpoint is continously updated with the most recent data as soon as it is available to us, which is normally within 7 days. Dates more recent than 7 days into the past is likely to return no data. ## Point Request The point request endpoint is used to retrieve time-series data for a single coordinate. ```endpoint GET https://api.stormglass.io/v2/historical/point ``` #### Query Parameters Name | Required | Default | Description -------- | -------- | --------------------- | ---------------------------------------------------------------------------------------------------------------- `lat` | ✔ | | Latitude of the desired coordinate. `lng` | ✔ | | Longitude of the desired coordinate. `params` | ✔ | | Comma-separated list of the desired parameters. Eg `airTemperature` or `airTemperature,waveHeight`. See options below. `start` | \* | 239 hours before end | First hour in UTC. UNIX time or ISO format. `end` | \* | 239 hours after start | Final hour in UTC. UNIX time or ISO format. `source` | | sg | Comma-separated list of the desired sources. Eg `ecmwf` or `ecmwf,sg`. See options below. \* If neither `start` nor `end` are specified, an error will be returned. **params** The following options are available for the `params` parameter. Option | Description ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ `airTemperature` | Air temperature in degrees celsius. `bathymetry` | Wave and currents model depth in meters. `cloudCover` | Total cloud coverage. Percentage. `currentDirection` | Direction of current. 0° indicates current coming from north. `currentSpeed` | Speed of current in meters per second. `dewPointTemperature` | Dew point temperature at 2m above ground in degrees Celsius. `gust` | Wind gust in meters per second. `iceCover` | Ice cover. Unitless factor between 0.0 and 1.0. `precipitation` | Mean precipitation in kg/m²/h = mm/h. `pressure` | Air pressure in hPa. `rain` | Mean rain-type precipitation in kg/m²/h = mm/h. `secondarySwellDirection` | Height of secondary swell waves in meters. `secondarySwellHeight` | Period of secondary swell waves in seconds. `secondarySwellPeriod` | Direction of secondary swell waves. 0° indicates swell coming from north. `snow` | Mean snow-type precipitation in kg/m²/h = mm/h. `snowAlbedo` | Reflectivity of snow cover. Unitless factor between 0.0 and 1.0. `soilMoisture` | Volumetric soil moisture content at 0 to 10 cm below surface. `soilMoisture10cm` | Volumetric soil moisture content at 10 to 40 cm below surface. `soilMoisture40cm` | Volumetric soil moisture content at 40 to 100 cm below surface. `soilMoisture100cm` | Volumetric soil moisture content at 100 to 200 cm below surface. `soilTemperature` | Soil temperature at 0 to 10 cm below surface in degrees Celcius. `soilTemperature10cm` | Soil temperature at 10 to 40 cm below surface in degrees Celcius. `soilTemperature40cm` | Soil temperature at 40 to 100 cm below surface in degrees Celcius. `soilTemperature100cm` | Soil temperature at 100 to 200 cm below surface in degrees Celcius. `solarDownwardRadiationFlux` | Solar downward radiation flux at ground or sea level (W/m²) - (ECMWF source parameter name: "Surface net short-wave solar radiation"). `surfaceNetShortwaveRadiationDownwardsFlux` | Surface net short-wave radiation downwards flux at ground or sea level (W/m²) - (ECMWF source parameter name: "Surface net short-wave solar radiation downwards"). `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. `waterTemperature` | Water temperature in degrees celsius. `waveDirection` | Direction of combined wind and swell waves. 0° indicates waves coming from north. `waveHeight` | Significant height of combined wind and swell waves in meters. `wavePeriod` | Period of combined wind and swell waves in seconds. `windDirection` | Direction of wind at 10m above ground. 0° indicates wind coming from north. `windDirection100m` | Direction of wind at 100m above ground. 0° indicates wind coming from north. `windDirection200hpa` | Direction of wind at 200hpa. 0° indicates wind coming from north. `windDirection500hpa` | Direction of wind at 500hpa. 0° indicates wind coming from north. `windDirection800hpa` | Direction of wind at 800hpa. 0° indicates wind coming from north. `windDirection1000hpa` | Direction of wind at 1000hpa. 0° indicates wind coming from north. `windSpeed` | Speed of wind at 10m above ground in meters per second. `windSpeed100m` | Speed of wind at 100m above ground in meters per second. `windSpeed200hpa` | Speed of wind at 200hpa in meters per second. `windSpeed500hpa` | Speed of wind at 500hpa in meters per second. `windSpeed800hpa` | Speed of wind at 800hpa in meters per second. `windSpeed1000hpa` | Speed of wind at 1000hpa in meters per second. `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. **source** The following options are available for the `source` parameter. Option | Provider | Datasets ------------- | -------------------------------------------------- | ------------------------------------------- `cmems` | Copernicus Marine Environment Monitoring Service | All from provider. `cmems:gopaf` | Copernicus Marine Environment Monitoring Service | Global Ocean Physics Analysis and Forecast (GOPAF) `ecmwf` | European Centre for Medium-Range Weather Forecasts | All from provider. `ecmwf:era5` | European Centre for Medium-Range Weather Forecasts | ECMWF Reanalysis v5 (ERA5) `sg` | stormglass.io | all #### Response Format The response is returned in the JSON format. A successful request returns an object containing two members, `hours` and `meta`. **hours** The `hours` member is an array containing hourly data for the requested time-series. Each item in the array is an object, always containing a `time` member indicating the corresponding hour as an ISO string. The array items also contain data objects for the parameters requested using the parameter name as a key (eg `airTemperature` or `waveHeight`). The data objects contain keys for each requested source that has a value for the corresponding hour, i.e. `{ sg: 10.3 }`. The values are numbers. A data object will be absent when there are no values for any of the requested sources for a requested parameter and a given hour. **meta** The `meta` member is an object containing metadata for the request. It also contains information about your daily quota and current usage. ```json { "hours": [ { "airTemperature": { "sg": -1.23 }, "time": "2026-01-01T00:00:00+00:00", "waveHeight": { "sg": 0.32 } } ], "meta": { "cost": 1, "dailyQuota": 1000, "requestCount": 1 } } ``` #### Example #### ** Python ** ```python 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/v2/historical/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" } ) json_data = response.json() # Do something with the response data. ``` #### ** Curl ** ```curl curl -H "Authorization: example-api-key" "https://api.stormglass.io/v2/historical/point?lat=58.7984&lng=17.8081¶ms=waveHeight,airTemperature" ``` #### ** JavaScript ** ```javascript let lat = 58.7984; let lng = 17.8081; let params = ["waveHeight", "airTemperature"].join(","); fetch(`https://api.stormglass.io/v2/historical/point?lat=${lat}&lng=${lng}¶ms=${params}`, { headers: { "Authorization": "example-api-key" } }) .then((response) => response.json()) .then((json_data) => { // Do something with response data. }); ```