Documentation

Historical Data & Climate

Access decades of historical weather data dating back to 1979, along with comprehensive climate summaries and location services. Perfect for climate research, trend analysis, and long-term planning.

Historical Weather Data

Get Historical Weather

Retrieve detailed historical weather records for any date range and location. Our historical database contains over 40 years of quality-controlled meteorological data.

Endpoint: GET /weather/historical

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude coordinate
`lon`	number	Yes	Longitude coordinate
`start_date`	string	Yes	Start date (YYYY-MM-DD format)
`end_date`	string	Yes	End date (YYYY-MM-DD format)

Date Range Limits

Maximum range: 366 days per request
Available data: January 1, 1979 to present
Data resolution: Daily aggregated values

Example Request

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/weather/historical?lat=48.8566&lon=2.3522&start_date=2023-06-01&end_date=2023-06-30" \
  -H "X-API-Key: your-api-key-here"

Example Response

Code(json)
 
{
  "location": {
    "lat": 48.8566,
    "lon": 2.3522,
    "name": "Paris",
    "country": "France",
    "region": "Île-de-France",
    "timezone": "Europe/Paris"
  },
  "data": [
    {
      "date": "2023-06-01",
      "temperature": {
        "min": 15.2,
        "max": 24.1,
        "avg": 19.7
      },
      "precipitation": 2.4,
      "humidity": 68,
      "pressure": 1016.3
    },
    {
      "date": "2023-06-02",
      "temperature": {
        "min": 16.8,
        "max": 26.3,
        "avg": 21.6
      },
      "precipitation": 0.0,
      "humidity": 61,
      "pressure": 1018.7
    }
  ],
  "period": {
    "start_date": "2023-06-01",
    "end_date": "2023-06-30"
  }
}

Climate Summaries

Get Climate Summary

Access statistical climate data including monthly averages, extremes, and climate normals based on long-term weather patterns.

Endpoint: GET /weather/historical/summary

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude coordinate
`lon`	number	Yes	Longitude coordinate
`month`	integer	No	Specific month (1-12) for climate data
`period`	string	No	Climate period: `1991-2020`, `1981-2010`, `1971-2000`

Example Request

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/weather/historical/summary?lat=35.6762&lon=139.6503&month=7&period=1991-2020" \
  -H "X-API-Key: your-api-key-here"

Example Response

Code(json)
 
{
  "location": {
    "lat": 35.6762,
    "lon": 139.6503,
    "name": "Tokyo",
    "country": "Japan",
    "region": "Tokyo",
    "timezone": "Asia/Tokyo"
  },
  "period": "1991-2020",
  "monthly_data": [
    {
      "month": 7,
      "month_name": "July",
      "temperature": {
        "avg_high": 29.2,
        "avg_low": 23.1,
        "record_high": 39.5,
        "record_low": 15.4,
        "avg_mean": 26.2
      },
      "precipitation": {
        "avg_total": 153.5,
        "avg_days": 12.3,
        "record_daily": 87.2
      },
      "humidity": {
        "avg": 77,
        "morning": 82,
        "afternoon": 71
      }
    }
  ],
  "annual_summary": {
    "avg_annual_temperature": 15.8,
    "total_annual_precipitation": 1528.8,
    "warmest_month": "August",
    "coldest_month": "January",
    "wettest_month": "September",
    "driest_month": "December"
  }
}

Climate Periods

We provide climate data for three standard meteorological periods:

1991-2020: Current climate normals (WMO standard)
1981-2010: Previous climate normals
1971-2000: Historical reference period

Climate normals are 30-year averages used as a baseline for comparing current weather conditions.

Geocoding Services

Forward Geocoding

Convert location names, addresses, or landmarks to coordinates.

Endpoint: GET /geocoding/search

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Location query (city, address, landmark)
`limit`	integer	No	Max results (1-20, default: 5)

Example Request

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/geocoding/search?q=Sydney,%20Australia&limit=3" \
  -H "X-API-Key: your-api-key-here"

Example Response

Code(json)
 
{
  "results": [
    {
      "name": "Sydney",
      "lat": -33.8688,
      "lon": 151.2093,
      "country": "Australia",
      "region": "New South Wales",
      "local_names": {
        "en": "Sydney",
        "zh": "悉尼",
        "ja": "シドニー",
        "ar": "سيدني"
      }
    },
    {
      "name": "Sydney",
      "lat": 46.1351,
      "lon": -60.1831,
      "country": "Canada",
      "region": "Nova Scotia",
      "local_names": {
        "en": "Sydney",
        "fr": "Sydney"
      }
    }
  ],
  "count": 2
}

Reverse Geocoding

Convert coordinates to detailed address information.

Endpoint: GET /geocoding/reverse

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude coordinate
`lon`	number	Yes	Longitude coordinate

Example Request

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/geocoding/reverse?lat=51.5074&lon=-0.1278" \
  -H "X-API-Key: your-api-key-here"

Example Response

Code(json)
 
{
  "address": {
    "house_number": "10",
    "road": "Downing Street",
    "neighbourhood": "Westminster",
    "city": "London",
    "county": "Greater London",
    "state": "England",
    "postcode": "SW1A 2AA",
    "country": "United Kingdom",
    "country_code": "GB"
  },
  "lat": 51.5033,
  "lon": -0.1276,
  "display_name": "10 Downing Street, Westminster, London, Greater London, England, SW1A 2AA, United Kingdom"
}

Use Cases & Applications

Climate Research

Historical weather data is invaluable for:

Climate trend analysis: Identify long-term temperature and precipitation patterns
Extreme weather studies: Analyze frequency and intensity of weather events
Agricultural planning: Understand seasonal patterns for crop selection
Urban planning: Assess climate risks for infrastructure development

Business Applications

Insurance: Risk assessment for weather-related claims
Energy: Heating/cooling demand forecasting
Tourism: Seasonal activity planning
Construction: Weather-related project scheduling

Data Quality

Our historical data undergoes rigorous quality control:

Source verification: Data from certified meteorological stations
Gap filling: Statistical methods for missing data points
Outlier detection: Automated flagging of anomalous values
Homogenization: Corrections for station relocations and instrumentation changes

Code Examples

Python - Climate Analysis

Code(python)
 
import requests
import pandas as pd
import matplotlib.pyplot as plt
from datetime import datetime, timedelta

class SupaWeatherHistorical:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.supaweather.com/v2"

    def get_historical_data(self, lat, lon, start_date, end_date):
        """Get historical weather data for a date range."""
        url = f"{self.base_url}/weather/historical"
        params = {
            "lat": lat,
            "lon": lon,
            "start_date": start_date,
            "end_date": end_date
        }
        headers = {"X-API-Key": self.api_key}

        response = requests.get(url, params=params, headers=headers)
        response.raise_for_status()
        return response.json()

    def get_climate_summary(self, lat, lon, period="1991-2020"):
        """Get climate summary for a location."""
        url = f"{self.base_url}/weather/historical/summary"
        params = {"lat": lat, "lon": lon, "period": period}
        headers = {"X-API-Key": self.api_key}

        response = requests.get(url, params=params, headers=headers)
        response.raise_for_status()
        return response.json()

# Usage example
api = SupaWeatherHistorical("your-api-key")

# Get last year's summer data for London
historical = api.get_historical_data(
    lat=51.5074,
    lon=-0.1278,
    start_date="2023-06-01",
    end_date="2023-08-31"
)

# Convert to DataFrame for analysis
df = pd.DataFrame(historical['data'])
df['date'] = pd.to_datetime(df['date'])

# Plot temperature trends
plt.figure(figsize=(12, 6))
plt.plot(df['date'], [day['temperature']['max'] for day in df.itertuples()],
         label='Max Temperature', color='red')
plt.plot(df['date'], [day['temperature']['min'] for day in df.itertuples()],
         label='Min Temperature', color='blue')
plt.title(f"Summer 2023 Temperature - {historical['location']['name']}")
plt.legend()
plt.show()

JavaScript - Geocoding Integration

Code(javascript)
 
class WeatherGeocoder {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = "https://api.supaweather.com/v2";
  }

  async geocodeLocation(query) {
    const response = await fetch(
      `${this.baseURL}/geocoding/search?q=${encodeURIComponent(query)}&limit=1`,
      {
        headers: { "X-API-Key": this.apiKey },
      },
    );

    if (!response.ok)
      throw new Error(`Geocoding failed: ${response.statusText}`);

    const data = await response.json();
    return data.results[0];
  }

  async getHistoricalWeatherByLocation(locationName, startDate, endDate) {
    // First, geocode the location
    const location = await this.geocodeLocation(locationName);

    if (!location) {
      throw new Error(`Location "${locationName}" not found`);
    }

    // Then get historical weather
    const response = await fetch(
      `${this.baseURL}/weather/historical?lat=${location.lat}&lon=${location.lon}&start_date=${startDate}&end_date=${endDate}`,
      {
        headers: { "X-API-Key": this.apiKey },
      },
    );

    if (!response.ok)
      throw new Error(`Historical data request failed: ${response.statusText}`);

    return response.json();
  }
}

// Usage
const geocoder = new WeatherGeocoder("your-api-key");

geocoder
  .getHistoricalWeatherByLocation("Tokyo, Japan", "2023-07-01", "2023-07-31")
  .then((data) => {
    console.log(`Historical weather for ${data.location.name}:`);
    console.log(
      `Average temperature in July 2023: ${
        data.data.reduce((sum, day) => sum + day.temperature.avg, 0) /
        data.data.length
      }°C`,
    );
  })
  .catch((error) => {
    console.error("Error:", error.message);
  });

PHP - Climate Comparison

Code(php)
 
<?php
class ClimateAnalyzer {
    private $apiKey;
    private $baseUrl = 'https://api.supaweather.com/v2';

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    public function getClimateSummary($lat, $lon, $period = '1991-2020') {
        $url = $this->baseUrl . '/weather/historical/summary';
        $params = http_build_query([
            'lat' => $lat,
            'lon' => $lon,
            'period' => $period
        ]);

        $context = stream_context_create([
            'http' => [
                'method' => 'GET',
                'header' => 'X-API-Key: ' . $this->apiKey
            ]
        ]);

        $response = file_get_contents($url . '?' . $params, false, $context);
        return json_decode($response, true);
    }

    public function compareClimatePeriods($lat, $lon) {
        $currentPeriod = $this->getClimateSummary($lat, $lon, '1991-2020');
        $previousPeriod = $this->getClimateSummary($lat, $lon, '1981-2010');

        $currentTemp = $currentPeriod['annual_summary']['avg_annual_temperature'];
        $previousTemp = $previousPeriod['annual_summary']['avg_annual_temperature'];

        $tempChange = $currentTemp - $previousTemp;

        return [
            'location' => $currentPeriod['location']['name'],
            'current_avg_temp' => $currentTemp,
            'previous_avg_temp' => $previousTemp,
            'temperature_change' => $tempChange,
            'warming_trend' => $tempChange > 0
        ];
    }
}

// Usage
$analyzer = new ClimateAnalyzer('your-api-key');
$comparison = $analyzer->compareClimatePeriods(40.7128, -74.006);

echo "Climate change analysis for {$comparison['location']}:\n";
echo "Current period (1991-2020): {$comparison['current_avg_temp']}°C\n";
echo "Previous period (1981-2010): {$comparison['previous_avg_temp']}°C\n";
echo "Change: " . ($comparison['warming_trend'] ? '+' : '') .
     number_format($comparison['temperature_change'], 2) . "°C\n";
?>

Data Availability

Geographic Coverage

Global coverage: Weather stations worldwide
Ocean data: Marine meteorological observations
Remote areas: Satellite-derived estimates where needed

Temporal Coverage

Daily data: January 1, 1979 to present
Quality controlled: Rigorous validation and correction processes
Regular updates: Historical database updated monthly

Parameters Available

Historical weather data includes:

Temperature (min, max, average)
Precipitation amount
Atmospheric pressure
Relative humidity
Wind speed and direction (where available)
Snow depth (in applicable regions)

Current Weather - Real-time conditions
Weather Forecasts - Future predictions
Weather Alerts - Severe weather monitoring

Last modified on July 7, 2025

Alerts Advanced

Historical Data & Climate

Historical Weather Data

Get Historical Weather

Parameters

Date Range Limits

Example Request

Example Response

Climate Summaries

Get Climate Summary

Parameters

Example Request

Example Response

Climate Periods

Geocoding Services

Forward Geocoding

Parameters

Example Request

Example Response

Reverse Geocoding

Parameters

Example Request

Example Response

Use Cases & Applications

Climate Research

Business Applications

Data Quality

Code Examples

Python - Climate Analysis

JavaScript - Geocoding Integration

PHP - Climate Comparison

Data Availability

Geographic Coverage

Temporal Coverage

Parameters Available

Related Endpoints