README

A Laravel package for integrating with the National Weather Service API. Get weather forecasts, current conditions, and alerts directly from the source - no API key required!

Features

🌤️ Current Weather & Forecasts - Get detailed weather information
⚡ Weather Alerts - Real-time warnings, watches, and advisories
🎯 Location-based - Support for coordinates and addresses
🚀 Laravel Native - Built with Laravel HTTP Client and Facades
💾 Smart Caching - Configurable caching for optimal performance
🔧 Builder Pattern - Fluent, chainable API for easy usage
📊 Rich Data - Strongly typed DTOs using Spatie Laravel Data

Installation

composer require projectsaturnstudios/nws

Publish the configuration file:

php artisan vendor:publish --tag=nws-config

Quick Start

Using the Facade

use ProjectSaturnStudios\NWS\Support\Facades\NWS;

// Get current weather for Tampa
$weather = NWS::forTampa()->getCurrentWeather();

// Get 7-day forecast for any location
$forecast = NWS::location(40.7128, -74.0060)->getForecast();

// Get weather alerts for Florida
$alerts = NWS::getAlertsForArea('FL');

Using the Builder Pattern

use ProjectSaturnStudios\NWS\NationalWeatherService;

$nws = NationalWeatherService::make()
    ->location(27.9506, -82.4572)  // Tampa coordinates
    ->units('us');                  // US customary units

$currentWeather = $nws->getCurrentWeather();
$hourlyForecast = $nws->getHourlyForecast();
$alerts = $nws->getAlerts();

API Methods

Weather Data

// Get current conditions and forecast
$weather = NWS::location($lat, $lon)->getCurrentWeather();

// Get 7-day forecast
$forecast = NWS::location($lat, $lon)->getForecast();

// Get hourly forecast
$hourly = NWS::location($lat, $lon)->getHourlyForecast();

// Get point information (grid coordinates, office, etc.)
$point = NWS::location($lat, $lon)->getPoint();

Weather Alerts

// Get alerts for a state/area
$alerts = NWS::getAlertsForArea('FL');

// Get alerts for a specific zone
$alerts = NWS::getAlertsForZone('FLZ151');

// Get alerts for coordinates
$alerts = NWS::location($lat, $lon)->getAlerts();

// Filter severe alerts
$severeAlerts = $alerts->getSevereAlerts();
$activeAlerts = $alerts->getActiveAlerts();

Configuration Options

// Set units (us or si)
$nws = NWS::make()->units('si');

// Enable experimental features
$nws = NWS::make()->withFeatureFlags([
    'forecast_temperature_qv',
    'forecast_wind_speed_qv'
]);

Response Data

All responses are strongly typed using Spatie Laravel Data:

$forecast = NWS::forTampa()->getForecast();

// Access forecast periods
foreach ($forecast->periods as $period) {
    echo $period->name;                    // "This Afternoon"
    echo $period->temperature;             // 89
    echo $period->shortForecast;           // "Partly Sunny"
    echo $period->detailedForecast;        // Full description
    echo $period->probabilityOfPrecipitation->value; // 20
}

// Helper methods
$todaysPeriods = $forecast->getTodaysPeriods();
$currentPeriod = $forecast->getCurrentPeriod();

Configuration

The package includes comprehensive configuration options:

// config/nws.php
return [
    'base_url' => 'https://api.weather.gov',
    'user_agent' => 'Your App Name (contact@example.com)',
    'timeout' => 30,
    'cache' => [
        'enabled' => true,
        'ttl' => [
            'forecasts' => 1800,  // 30 minutes
            'alerts' => 300,      // 5 minutes
            'points' => 86400,    // 24 hours
        ],
    ],
    'default_location' => [
        'latitude' => 27.9506,   // Tampa
        'longitude' => -82.4572,
    ],
];

Caching

The package automatically caches API responses based on configuration:

Points/Offices: 24 hours (rarely change)
Forecasts: 30 minutes (updated regularly)
Observations: 10 minutes (current conditions)
Alerts: 5 minutes (time-sensitive)

Error Handling

The package includes automatic retry logic for temporary failures:

try {
    $weather = NWS::forTampa()->getCurrentWeather();
} catch (\Exception $e) {
    // Handle API errors
    logger()->error('Weather API failed', ['error' => $e->getMessage()]);
}

Requirements

PHP 8.2+
Laravel 10+
Guzzle HTTP Client (via Laravel HTTP Client)

About the NWS API

The National Weather Service API is:

Free - No API key required
Authoritative - Direct from the source
Comprehensive - Forecasts, observations, alerts
Reliable - Government-maintained infrastructure

License

MIT License. See LICENSE file for details.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

projectsaturnstudios / nws

Maintainers

Details