5 releases (3 breaking)

0.4.0 May 31, 2024
0.3.0 Mar 27, 2024
0.2.0 Apr 25, 2023
0.1.1 Oct 28, 2022
0.1.0 Oct 7, 2022

#431 in Debugging

21 downloads per month
Used in openweathermap_exporter

MIT-0 license

32KB
564 lines

OpenWeatherMap Client

openweathermap_client is a rust library that provides a client for querying OpenWeatherMap's free version 2.5 weather API. |

docs.rs | crates.io

Features

  • Binds query results into structs derived from OpenWeatherMap's weather-data docs using serde.
  • Supports requesting results in OWM's Standard, Metric, or Imperial unit systems.
  • Supports requesting that the API translate of city names and weather descriptions into supported languages.
  • Cross platform. Tested to confirm it runs on Windows, MacOS, and Linux and on many hardware architectures (will be)
  • Queries over https using hyper (some existing exporters don't).
    • Doesn't require openssl to be installed, allowing it to be used on weird architectures, because it uses hyper_rustls.
  • Is panic-free.

Usage

Get An API Key

To obtain an OpenWeatherMap API Key, see this section.

Add the client to your project

cargo add openweathermap_client

Example 1

Get the temperature in °C and description of the weather in Paris right now.

use openweathermap_client::models::{City, UnitSystem};
use openweathermap_client::{error::ClientError, Client, ClientOptions};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), ClientError> {
    let options = ClientOptions {
        units: UnitSystem::Metric,
        language: "fr".to_string(),
        ..ClientOptions::default() // loads API_KEY env var
    };
    let client = Client::new(options)?;
    let reading = client.fetch_weather(&City::new("Paris", "FR")).await?;

    println!(
        "The temperature and weather in France in French is {}, {}",
        reading.main.temp, reading.weather[0].description
    );
    Ok(())
}

Example 2

Reuse a client to obtain readings at several different locations with different query types.

use openweathermap_client::models::{City, CityId, Coord};
use openweathermap_client::{error::ClientError, Client, ClientOptions, Query};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), ClientError> {
    // reuse a client for several readings (must be run in an async context)
    let client = Client::new(ClientOptions::default())?; // loads API_KEY env var

    let v: Vec<Box<dyn Query>> = vec![
        Box::new(City::new("Lages", "BR")),
        Box::new(CityId::new(3369157)),
        Box::new(Coord::new(61.1595054, -45.4409551)),
    ];

    for query in v {
        let weather = client.fetch_weather(query.as_ref()).await?;
        println!("The weather for {} is {:?}", query, weather);
    }
    Ok(())
}

See openweathermap_exporter for a service that allow collecting weather data for a multiple locations and sharing this with metrics aggregators by publishing the readings via a prometheus exposition formatted exporter.

Dependencies

~15–25MB
~474K SLoC