https://github.com/projectsaturnstudios/nws
National Weather Service (NWS) integration for Laravel applications.
https://github.com/projectsaturnstudios/nws
Last synced: 6 months ago
JSON representation
National Weather Service (NWS) integration for Laravel applications.
- Host: GitHub
- URL: https://github.com/projectsaturnstudios/nws
- Owner: projectsaturnstudios
- Created: 2025-09-27T16:08:11.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-27T16:09:43.000Z (10 months ago)
- Last Synced: 2025-12-26T06:20:56.066Z (7 months ago)
- Language: PHP
- Size: 17.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Laravel NWS (National Weather Service) Package
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
```bash
composer require projectsaturnstudios/nws
```
Publish the configuration file:
```bash
php artisan vendor:publish --tag=nws-config
```
## Quick Start
### Using the Facade
```php
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
```php
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
```php
// 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
```php
// 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
```php
// 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:
```php
$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:
```php
// 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:
```php
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.