Struct Meteostat

pub struct Meteostat { /* private fields */ }

The main client struct for accessing Meteostat data.

Provides methods to fetch weather data (hourly, daily, monthly, climate) and find weather stations. Handles data caching internally.

Create instances using Meteostat::new or Meteostat::with_cache_folder.

Implementations

impl Meteostat

pub async fn with_cache_folder( cache_folder: PathBuf, ) -> Result<Self, MeteostatError>

Creates a new Meteostat client using a specific cache folder.

Initializes the station locator and frame fetcher, ensuring the specified cache directory exists.

Arguments

• cache_folder - A PathBuf representing the directory to use for caching station metadata and downloaded weather data.

Returns

A Result containing the initialized Meteostat client or a MeteostatError if initialization fails.

Errors

This function can return errors if:

• The cache directory cannot be created (MeteostatError::CacheDirCreation).
• Loading or initializing station data fails (propagated from StationLocator::new, resulting in MeteostatError::LocateStation).

Example

use meteostat::{Meteostat, MeteostatError};
use std::path::PathBuf;
use tempfile::tempdir; // For example purposes

let temp_dir = tempdir()?; // Create a temporary directory
let cache_path = temp_dir.path().join("my_meteostat_cache");

// Create a client with a custom cache location
let client = Meteostat::with_cache_folder(cache_path).await?;

println!("Meteostat client initialized with custom cache.");
// Use the client...

temp_dir.close()?; // Clean up temp directory

pub async fn new() -> Result<Self, MeteostatError>

Creates a new Meteostat client using the default cache folder location.

The default location is platform-dependent (e.g., ~/.cache/meteostat-rs on Linux). Initializes the station locator and frame fetcher, ensuring the default cache directory exists.

Returns

A Result containing the initialized Meteostat client or a MeteostatError if initialization fails.

Errors

This function can return errors if:

• The default cache directory path cannot be determined (MeteostatError::CacheDirResolution).
• The default cache directory cannot be created (MeteostatError::CacheDirCreation).
• Loading or initializing station data fails (propagated from StationLocator::new, resulting in MeteostatError::LocateStation).

Example

use meteostat::{Meteostat, MeteostatError};

// Create a client with the default cache location
let client = Meteostat::new().await?;

println!("Meteostat client initialized with default cache.");
// Use the client...

pub fn hourly(&self) -> HourlyClient<'_>

Prepares a request builder for fetching hourly weather data.

Returns an HourlyClient which allows specifying a station ID or location and optional parameters before executing the request.

Returns

An HourlyClient associated with this Meteostat instance.

Example

let client = Meteostat::new().await?;
let berlin = LatLon(52.52, 13.40);

// Get hourly data for Berlin (nearest station)
let hourly_data = client.hourly().location(berlin).call().await?;

pub fn daily(&self) -> DailyClient<'_>

Prepares a request builder for fetching daily weather data.

Returns a DailyClient which allows specifying a station ID or location and optional parameters before executing the request.

Returns

A DailyClient associated with this Meteostat instance.

Example

let client = Meteostat::new().await?;
let paris = LatLon(48.85, 2.35);

// Get daily data for station "07150" (Paris-Montsouris)
let daily_data = client.daily().station("07150").call().await?;

pub fn monthly(&self) -> MonthlyClient<'_>

Prepares a request builder for fetching monthly weather data.

Returns a MonthlyClient which allows specifying a station ID or location and optional parameters before executing the request.

Returns

A MonthlyClient associated with this Meteostat instance.

Example

let client = Meteostat::new().await?;
let london = LatLon(51.50, -0.12);

// Get monthly data for London (nearest station)
let monthly_data = client.monthly().location(london).call().await?;

pub fn climate(&self) -> ClimateClient<'_>

Prepares a request builder for fetching climate normals data.

Returns a ClimateClient which allows specifying a station ID or location and optional parameters before executing the request.

Returns

A ClimateClient associated with this Meteostat instance.

Example

let client = Meteostat::new().await?;

// Get climate normals for station "10382" (Berlin-Tegel)
let climate_data = client.climate().station("10382").call().await?;

pub async fn clear_station_list_cache(&self) -> Result<(), MeteostatError>

Clears the cached station list file (stations_lite.bin).

This removes the locally stored station metadata. This function doesn’t clear the in-memory tree of stations. To clear that, use Meteostat::rebuild_station_list_cache.

Returns

Ok(()) on success.

Errors

Returns MeteostatError::CacheDeletionError if the file cannot be removed (e.g., due to permissions issues or if the file doesn’t exist).

Example

let client = Meteostat::new().await?;
// ... use client ...

client.clear_station_list_cache().await?;
println!("Station list cache cleared.");

pub async fn rebuild_station_list_cache(&mut self) -> Result<(), MeteostatError>

Forces a rebuild of the station list cache.

This method will delete the existing station cache file (if any) and then immediately download and process the latest station metadata from Meteostat, storing it in the cache.

Note: This requires mutable access (&mut self) because it modifies the internal StationLocator state.

Returns

Ok(()) on success.

Errors

Can return errors related to:

• Deleting the old cache file (MeteostatError::CacheDeletionError).
• Downloading or processing the new station data (propagated as MeteostatError::LocateStation).

Example

let mut client = Meteostat::new().await?;
// ... use client ...

// Ensure the station cache is up-to-date
client.rebuild_station_list_cache().await?;
println!("Station list cache rebuilt.");

pub async fn clear_weather_data_cache_per_station( &self, station: &str, frequency: Frequency, ) -> Result<(), MeteostatError>

Clears the cached weather data file(s) for a specific station and frequency.

Removes the .parquet file associated with the given station ID and data frequency from the cache directory. Also clears any in-memory cache associated with this specific data in the FrameFetcher.

Arguments

• station - The ID of the station whose cache should be cleared.
• frequency - The Frequency of the data cache to clear (e.g., Hourly, Daily).

Returns

Ok(()) on success.

Errors

Returns MeteostatError::CacheDeletionError if the parquet file cannot be removed. Returns MeteostatError::WeatherData if clearing the internal FrameFetcher cache fails.

Example

let client = Meteostat::new().await?;
let station_id = "10382"; // Example: Berlin-Tegel

// Fetch some data first to ensure it's cached
let _ = client.hourly().station(station_id).call().await?;

// Clear only the hourly cache for this station
client.clear_weather_data_cache_per_station(station_id, Frequency::Hourly).await?;
println!("Hourly cache for station {} cleared.", station_id);

pub async fn clear_weather_data_cache(&self) -> Result<(), MeteostatError>

Clears all cached weather data files (.parquet files).

Iterates through the cache directory and removes all files ending with the .parquet extension. This effectively deletes all cached hourly, daily, monthly, and climate normal data. The station list cache (stations_lite.bin) is not removed by this method. Also clears the in-memory cache of the FrameFetcher.

Returns

Ok(()) on success.

Errors

Returns MeteostatError::CacheDeletionError if removing any specific parquet file fails. Returns MeteostatError::WeatherData if clearing the internal FrameFetcher cache fails.

Example

let client = Meteostat::new().await?;
// ... fetch some data ...

// Clear all downloaded weather data
client.clear_weather_data_cache().await?;
println!("All weather data cache cleared.");

pub async fn clear_cache(&self) -> Result<(), MeteostatError>

Clears the entire cache directory.

This removes both the cached station list (stations_lite.bin) and all cached weather data files (.parquet files). It effectively combines Meteostat::clear_station_list_cache and Meteostat::clear_weather_data_cache.

Note: this retains the in-memoryStationLocator state, to clear that as well you have to use Meteostat::clear_cache_and_rebuild.

Returns

Ok(()) on success.

Errors

Can return errors from either Meteostat::clear_station_list_cache or Meteostat::clear_weather_data_cache. See their documentation for specific error types (MeteostatError::CacheDeletionError, MeteostatError::WeatherData).

Example

let client = Meteostat::new().await?;
// ... fetch data ...

// Remove all cached files
client.clear_cache().await?;
println!("Complete cache cleared.");

pub async fn clear_cache_and_rebuild(&mut self) -> Result<(), MeteostatError>

Clears the entire cache directory and then rebuilds the station list cache.

This first removes all cached files (station list and weather data) and then immediately downloads and rebuilds the station list cache. It’s useful for ensuring a completely fresh start while pre-populating the essential station metadata.

Note: This requires mutable access (&mut self) because it modifies the internal StationLocator state during the rebuild step.

Returns

Ok(()) on success.

Errors

Can return errors from Meteostat::clear_cache or Meteostat::rebuild_station_list_cache. See their documentation for specific error types (MeteostatError::CacheDeletionError, MeteostatError::WeatherData, MeteostatError::LocateStation).

Example

let mut client = Meteostat::new().await?;
// ... potentially use client ...

// Clear everything and ensure station list is immediately available again
client.clear_cache_and_rebuild().await?;
println!("Cache cleared and station list rebuilt.");

pub fn find_stations<'f1>(&'f1 self) -> MeteostatFindStationsBuilder<'f1>

Finds weather stations near a given geographical location.

Allows filtering by maximum distance, number of stations, and data inventory requirements. Uses a builder pattern for optional parameters.

Arguments (Builder Methods)

• .location(LatLon): Required. The geographical coordinate LatLon around which to search.
• .inventory_request(InventoryRequest): Optional. Filters stations based on reported data availability using an InventoryRequest.
• .max_distance_km(f64): Optional. The maximum search radius in kilometers. Defaults to 50.0.
• .station_limit(usize): Optional. The maximum number of stations to return, sorted by distance. Defaults to 5.

Returns

A Result containing a Vec<Station> of found stations (sorted by distance, closest first), or a MeteostatError if the search fails.

Errors

Can return errors propagated from the underlying station search mechanism (MeteostatError::LocateStation). Note that finding no stations within the criteria is not considered an error for this method; it will return an empty Vec.

Example

use meteostat::{Meteostat, MeteostatError, LatLon, InventoryRequest, Frequency, RequiredData};

let client = Meteostat::new().await?;
let nyc = LatLon(40.7128, -74.0060);

// Find the 3 closest stations within 100km of NYC
// that have reported *any* Daily data.
let inventory_req = InventoryRequest::new(Frequency::Daily, RequiredData::Any);

let stations = client.find_stations()
    .location(nyc)
    .max_distance_km(100.0)
    .station_limit(3)
    .inventory_request(inventory_req)
    .call()
    .await?;

println!("Found {} stations near NYC matching criteria:", stations.len());
for result in stations {
    println!("  - ID: {}, Name: {:?}, Distance: {}", result.station.id, result.station.name.get("en"), result.distance_km);
}