Crate meteostat 

Provides a Rust interface for accessing historical weather and climate data from Meteostat, using their free bulk data interface.

This crate allows fetching hourly, daily, monthly, and climate normal data for thousands of weather stations worldwide, either by station ID or by geographical coordinates (latitude/longitude). Data is returned efficiently as Polars LazyFrame wrappers, enabling powerful filtering and analysis before loading data into memory. Automatic caching of station metadata and weather data files minimizes redundant downloads.

Features

• Fetch by Station ID or Location: Initiate requests via frequency-specific clients (client.hourly(), client.daily(), etc.) and then specify either .station("ID") or .location(LatLon).
• Find Nearby Stations: Search for stations near coordinates using client.find_stations(), optionally filtering by distance and required data availability (inventory).
• Multiple Frequencies: Supports Hourly, Daily, Monthly, and Climate Normals data.
• Efficient Data Handling: Returns data as wrappers around Polars LazyFrames (e.g., HourlyLazyFrame), allowing for powerful, memory-efficient filtering and manipulation before collecting results.
• Convenient Filtering: Frame wrappers provide methods for easy filtering by date, year, month, or datetime ranges (e.g., daily_lazy.get_for_period(Year(2023))).
• Flexible Collection: Collect results either as a Polars DataFrame (.frame.collect()) or directly into Rust structs (.collect_hourly(), .collect_single_daily(), etc.) using methods on the frame wrappers.
• Automatic Caching: Downloads and caches station metadata and weather data files locally to speed up subsequent requests.
• Asynchronous: Built with tokio for non-blocking I/O.

Basic Usage

use meteostat::{Meteostat, LatLon, MeteostatError, Year};
use polars::prelude::*;
use chrono::{NaiveDate};

#[tokio::main]
async fn main() -> Result<(), MeteostatError> {
    let client = Meteostat::new().await?;
    // Period for which we want hourly data:
    let period = NaiveDate::from_ymd_opt(2023, 9, 1).unwrap();

    // --- Example 1: Collect 24 hourly data points into `Vec<Hourly>` ---
    let hourly_vec = client
        .hourly()
        .location(LatLon(52.0836403, 5.1257283))
        .call()
        .await? // `HourlyLazyFrame`
        .get_for_period(period)? // `HourlyLazyFrame` with filter plan
        .collect_hourly()?; // `Vec<Hourly>`

    // Do something with the hourly data...

    // --- Example 2: Collect daily data from 2023 into a `DataFrame` ---
    let daily_df = client
        .daily()
        .location(LatLon(52.0836403, 5.1257283))
        .call()
        .await? // `DailyLazyFrame`
        .get_for_period(Year(2023))? // `DailyLazyFrame` with filter plan
        .frame // `LazyFrame` with filter plan
        .collect()?; // `DataFrame`

    // Do something with the daily data...

    Ok(())
}

Core Concepts

• Meteostat: The main entry point client struct. Created via Meteostat::new or Meteostat::with_cache_folder.
• Frequency Clients: Accessed via methods on Meteostat (e.g., Meteostat::hourly, Meteostat::daily). These return builders.
• Source Specification: Use .station("ID") or .location(LatLon) on the frequency client builders.
• LazyFrame Wrappers: Fetching data returns structs like HourlyLazyFrame, DailyLazyFrame, MonthlyLazyFrame, ClimateLazyFrame which contain a Polars LazyFrame and provide convenience filtering and collection methods.
• Filtering: Use methods like get_range, get_at, get_for_period on the frame wrappers, or access .frame for advanced Polars operations.
• Collecting: Call .frame.collect()? on the frame wrappers to execute the query and get a DataFrame, OR use specific methods like .collect_daily(), .collect_single_hourly(), etc., to get results directly as Rust structs (e.g., Vec<Daily>, Hourly).
• Finding Stations: Use Meteostat::find_stations to search for Station objects near a LatLon, optionally filtering by InventoryRequest criteria.

Data Source and Attribution

• All weather data is sourced from Meteostat.
• This crate uses Meteostat’s free bulk data interface. No API key is required. Please consider supporting them if you find their service useful.

Structs

Climate

Represents a row of climate normals data, suitable for collecting results.

ClimateClient

A client builder specifically for fetching climate normals data.

ClimateLazyFrame

A wrapper around a Polars LazyFrame specifically for Meteostat climate data.

Daily

Represents a row of daily weather data, suitable for collecting results.

DailyClient

A client builder specifically for fetching daily weather data.

DailyLazyFrame

A wrapper around a Polars LazyFrame specifically for Meteostat daily weather data.

Hourly

Represents a row of hourly weather data, suitable for collecting results.

HourlyClient

A client builder specifically for fetching hourly weather data.

HourlyLazyFrame

A wrapper around a Polars LazyFrame specifically for Meteostat hourly weather data.

InventoryRequest

Represents criteria for filtering weather stations based on their data inventory.

LatLon

Represents a geographical coordinate using Latitude and Longitude.

Meteostat

The main client struct for accessing Meteostat data.

Month

Monthly

Represents a row of monthly weather data, suitable for collecting results.

MonthlyClient

A client builder specifically for fetching monthly weather data.

MonthlyLazyFrame

A wrapper around a Polars LazyFrame specifically for Meteostat monthly weather data.

Station

Represents a single Meteostat weather station and its associated metadata.

Year

Enums

Frequency

Represents the time frequency or granularity of Meteostat weather data.

LocateStationError

MeteostatError

RequiredData

Specifies the criteria for checking if a weather station has the necessary data inventory when searching for stations (e.g., using crate::Meteostat::find_stations).

WeatherCondition

Represents the weather condition code reported by Meteostat.

WeatherDataError

Traits

AnyDate

AnyDateTime

AnyMonth

DatePeriod

DateTimePeriod

MonthPeriod