This project provides average monthly temperature (Celsius) globally for land areas using 0.1° × 0.1° grids.
The data spans from 1970-01 to 2025-11 with monthly intervals, and the dataset is updated monthly for the current year.
The tool can match any latitude/longitude point to the nearest grid point and return the temperature for a specified year and month.
The yellow areas in this coverage map show the geographical coverage of the project.
The temperature data is partitioned by year, month, and geohash, resulting in small, focused data files ranging from 10KB to 500KB each. This efficient partitioning strategy offers several advantages:
- API-Friendly: Small file sizes make the data suitable for serving behind APIs
- Fast Loading: Only relevant data partitions are loaded on-demand
- Memory Efficient: Reduced memory footprint with targeted data access
- Scalable: Easy to cache and distribute individual partitions
Requires Python >= 3.10
pip install global-temperaturefrom global_temperature.tools.download import download
import global_temperature as gt
# 1. Download data (do this once)
download(years=[2024], target_path="data")
# 2. Create temperature object
temp_tool = gt.TemperatureFactory.create_temperature_object(
data_type="monthly",
source_folder="data"
)
# 3. Query temperature
result = temp_tool.query(2024, 6, 40.7128, -74.0060) # NYC
print(f"Temperature: {result['temperature']:.1f}°C")First, download the temperature data for the years you need. The available range is from 1970 to 2025.
from global_temperature.tools.download import download
# Specify a path where you want to download the data (absolute path recommended)
target_path = "data"
# Method 1: Download data for a specific year range (both inclusive)
start_year = 2023
end_year = 2024
failed_years = download(
start_year=start_year,
end_year=end_year,
target_path=target_path,
# delete_archived_files=False, # Keep zipped files if needed
)
# Method 2: Download specific years
years = [2020, 2022, 2025]
failed_years = download(years=years, target_path=target_path)
if failed_years:
print(f"Failed to download: {', '.join(map(str, failed_years))}")After downloading, you can query temperature data for any location globally (land areas only).
import global_temperature as gt
# Create a temperature object. You only need to create it once.
temperature_monthly = gt.TemperatureFactory.create_temperature_object(
data_type="monthly",
source_folder=target_path, # Path where you downloaded the data
search_radius=0.1, # Search radius in degrees (default: 0.1)
max_cache_size=200 # Maximum number of data partitions to keep in memory cache
)
# Query temperature for a specific location and time
year = 2025
month = 4
latitude = -38.2551 # Melbourne, Australia
longitude = 145.2414
temp = temperature_monthly.query(year, month, latitude, longitude)
print(f"Temperature in {year}-{month} at ({latitude}, {longitude}): {temp['temperature']} °C")
# Output: Temperature in 2025-4 at (-38.2551, 145.2414): 17.17852783203125 °CThe query method returns a dictionary with detailed information:
print(temp)
# Output:
# {
# 'temperature': np.float32(17.178528), # Temperature in Celsius
# 'geohash': 'r', # Geohash of nearest grid point (data is partitioned by year/month/geohash)
# 'distance': np.float32(0.061073482), # Distance to grid point (degrees)
# 'snapped_latitude': np.float32(-38.3), # Latitude of nearest grid point
# 'snapped_longitude': np.float32(145.2) # Longitude of nearest grid point
# }When no grid point exists within the search radius, an exception is raised:
from global_temperature.errors import NoNearbyPointError
try:
# Query a location in the ocean (no nearby land point)
temp = temperature_monthly.query(2025, 4, -38.1235, 144.9779)
print(f"Temperature: {temp['temperature']} °C")
except NoNearbyPointError as e:
print(f"No nearby point found: {e}")Parameters:
- data_type (
str): Currently supports "monthly" for monthly temperature data - source_folder (
str): Directory containing the downloaded temperature data files - search_radius (
float, optional): Maximum distance (in degrees) to search for the nearest grid point. Default: 0.1 - max_cache_size (
int, optional): Maximum number of data partitions to keep in memory cache. Each partition represents one year/month/geohash combination. Default: 200
Parameters:
- year (
int): Year (1970-2025) - month (
int): Month (1-12) - latitude (
float): Latitude in decimal degrees - longitude (
float): Longitude in decimal degrees
Returns: Dictionary with temperature data and metadata
- Create the temperature object once and reuse it for multiple queries
- Increase max_cache_size if you're querying many different locations/times and have sufficient memory
- Use absolute paths for better reliability when specifying data directories
- Download data once and store locally to avoid repeated API calls
You can find additional usage examples in the examples.py file.
This project uses temperature data from the ERA5 reanalysis dataset, which provides high-quality atmospheric data based on weather observations and numerical weather prediction models.
The code in this project is licensed under the MIT License. You are free to use, modify, and distribute it for any purpose.
This project relies on data from the ERA5 dataset, provided by the European Centre for Medium-Range Weather Forecasts (ECMWF). The ERA5 data is governed by the Copernicus License Agreement.
By using this project, you agree to comply with the terms of the Copernicus License Agreement when accessing or using ERA5 data.
Issues and pull requests are welcome! Please feel free to contribute to this project.
If you encounter any problems or have questions, please open an issue on GitHub.