NOAA Weather Client Library

A comprehensive Rust client library for the NOAA Weather API. This crate provides type-safe access to weather forecasts, alerts, observations, radar data, and aviation weather products from the National Weather Service.

Features

• 🌡️ Complete API Coverage - All NOAA Weather API endpoints
• 🚨 Weather Alerts - Active alerts, warnings, and watches
• 🗺️ Gridpoint Forecasts - Detailed forecasts with hourly data
• 📡 Radar Data - Real-time radar information
• ✈️ Aviation Weather - SIGMETs, AIRMETs, and Center Weather Advisories
• 🏢 NWS Offices - Office information and products
• 📍 Point Data - Weather data for any coordinates
• 🔄 Async/Await - Built on tokio and reqwest
• 🛡️ Type Safety - Comprehensive data models with serde

Quick Start

Add this to your Cargo.toml:

[dependencies]
noaa_weather_client = "0.1.5"
tokio = { version = "1.0", features = ["full"] }

Running Examples

You can run the provided examples to see the library in action:

# Using Just (recommended)
just example-basic     # Run basic usage example
just example-alerts    # Run weather alerts example
just examples          # Run all examples

# Or using Cargo directly
cargo run --example basic_usage --manifest-path noaa_weather_client/Cargo.toml
cargo run --example weather_alerts --manifest-path noaa_weather_client/Cargo.toml

Basic Example

use noaa_weather_client::apis::configuration::Configuration;
use noaa_weather_client::apis::{points, alerts};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Configuration::default();

    // Get point metadata for coordinates (latitude, longitude)
    let point = points::get_point(&config, "39.7456,-97.0892").await?;
    println!("Forecast office: {:?}", point.properties.forecast_office);

    // Get active weather alerts using struct parameters
    let alert_params = alerts::ActiveAlertsParams::default();
    let alerts = alerts::get_active_alerts(&config, alert_params).await?;
    println!("Active alerts: {}", alerts.features.len());

    Ok(())
}

Weather Alerts

use noaa_weather_client::apis::{configuration::Configuration, alerts};
use noaa_weather_client::models::{AreaCode, AlertSeverity};

let config = Configuration::default();

// Get all active alerts
let alert_params = alerts::ActiveAlertsParams::default();
let active_alerts = alerts::get_active_alerts(&config, alert_params).await?;

// Get alerts for a specific area (state/territory) with filters
let ca_alerts = alerts::get_active_alerts_for_area(&config, &AreaCode::CA).await?;

// Get alerts for a specific zone
let zone_alerts = alerts::get_active_alerts_for_zone(&config, "CAZ006").await?;

// Get severe weather alerts only
let severe_params = alerts::ActiveAlertsParams {
    severity: Some(vec![AlertSeverity::Severe, AlertSeverity::Extreme]),
    ..Default::default()
};
let severe_alerts = alerts::get_active_alerts(&config, severe_params).await?;

Weather Observations

use noaa_weather_client::apis::{configuration::Configuration, stations};

let config = Configuration::default();

// Get latest observation for a station
let observation = stations::get_latest_observations(&config, "KJFK", None).await?;
println!("Temperature: {:?}", observation.properties.temperature);

// Get station metadata
let station = stations::get_observation_station(&config, "KJFK").await?;
println!("Station name: {:?}", station.properties.name);

Forecasts

use noaa_weather_client::apis::{configuration::Configuration, gridpoints};
use noaa_weather_client::models::NwsForecastOfficeId;

let config = Configuration::default();

// Get forecast for specific gridpoint
let forecast = gridpoints::get_gridpoint_forecast(
    &config, 
    NwsForecastOfficeId::TOP, 
    31, 
    80, 
    None, // feature_flags
    None  // units
).await?;

// Get hourly forecast
let hourly = gridpoints::get_gridpoint_forecast_hourly(
    &config, 
    NwsForecastOfficeId::TOP, 
    31, 
    80, 
    None, // feature_flags
    None  // units
).await?;

Configuration

The Configuration struct provides default settings that work out of the box:

use noaa_weather_client::apis::configuration::Configuration;

// Use default configuration
let config = Configuration::default();

// Or customize the client
let config = Configuration {
    base_path: "https://api.weather.gov".to_owned(),
    user_agent: Some("my-app/1.0".to_owned()),
    client: reqwest::Client::builder()
        .timeout(std::time::Duration::from_secs(30))
        .build()?,
    ..Default::default()
};

Error Handling

All API functions return Result<T, Error<E>> where E is the specific error type for that endpoint:

use noaa_weather_client::apis::{configuration::Configuration, points};

let config = Configuration::default();

match points::get_point(&config, "invalid-point").await {
    Ok(point_data) => println!("Success: {:?}", point_data),
    Err(error) => {
        eprintln!("Error: {}", error);
        // Handle specific error types
        match error {
            noaa_weather_client::apis::Error::ResponseError(response) => {
                eprintln!("HTTP {}: {}", response.status, response.content);
            }
            _ => eprintln!("Other error: {}", error),
        }
    }
}

API Coverage

This client covers all major NOAA Weather API endpoints:

Authentication

The NOAA Weather API doesn't require authentication but NOAA recommends a unique User-Agent to identify your application.

From the NOAA Weather API Documentation:

A User Agent is required to identify your application. This string can be anything, and the more unique to your application the less likely it will be affected by a security event. If you include contact information (website or email), we can contact you if your string is associated to a security event. This will be replaced with an API key in the future.

User-Agent: (myweatherapp.com, contact@myweatherapp.com)

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Disclaimer

This project uses data published by NOAA/NWS but is otherwise unaffiliated with the National Weather Service and is not an official NWS library.

Resources

• NOAA Weather API Documentation
• NOAA Weather API GitHub
• National Weather Service