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 12-hour and hourly forecasts
• 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
• NOAA Weather Radio - Broadcast transcripts (opt-in via radio feature)
• NWS Text Products - Area Forecast Discussions, watches, and more
• 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 = "1.1.0"

To enable NOAA Weather Radio support (requires the quick-xml dependency):

[dependencies]
noaa_weather_client = { version = "1.1.0", features = ["radio"] }

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", None).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()),
    api_key: None,
    client: reqwest::Client::builder()
        .timeout(std::time::Duration::from_secs(30))
        .build()?,
};

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, 0.0, 0.0).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:

* Requires the radio feature flag.

Authentication

The NOAA Weather API does not require authentication, but NOAA recommends a unique User-Agent to identify your application. An optional API key can be provided via the api_key field on Configuration, which is sent as an X-Api-Key header.

let config = Configuration {
    api_key: Some("your-api-key".to_owned()),
    ..Default::default()
};

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