A unified weather information platform that aggregates global meteorological data from authoritative sources into a single, accessible service for developers, businesses, and end users.
Weather Service combines forecasts, severe weather alerts, earthquakes, hurricanes, and lunar data from 10+ government agencies worldwide through one consistent API and web interface.
- Global weather forecasts (16-day) via Open-Meteo
- Severe weather alerts from 6 countries (NOAA, Environment Canada, UK Met Office, BOM, JMA, CONAGUA)
- Real-time earthquake monitoring via USGS
- Hurricane/tropical storm tracking via NOAA NHC
- Moon phase calculations
- Automatic IP-based location detection
- WebSocket real-time notifications
- Single static binary with all assets embedded
- Multi-platform (Linux, macOS, Windows, FreeBSD - amd64/arm64)
- Production grade with rate limiting, caching, health checks
docker run -d \
--name weather \
-p 64580:80 \
-v ./rootfs/config:/config:z \
-v ./rootfs/data:/data:z \
ghcr.io/apimgr/weather:latestcurl -O https://raw.githubusercontent.com/apimgr/weather/main/docker/docker-compose.yml
docker compose up -d# Download latest release
curl -LO https://github.com/apimgr/weather/releases/latest/download/weather-linux-amd64
# Make executable and run
chmod +x weather-linux-amd64
./weather-linux-amd64# Download and install
sudo mv weather-linux-amd64 /usr/local/bin/weather
sudo useradd -r -s /bin/false weather
sudo mkdir -p /var/lib/weather/{data,config}
sudo chown -R weather:weather /var/lib/weather
# Create service
sudo tee /etc/systemd/system/weather.service > /dev/null <<EOF
[Unit]
Description=Weather API Service
After=network.target
[Service]
Type=simple
User=weather
ExecStart=/usr/local/bin/weather
Restart=always
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now weatherA companion CLI client is available for interacting with the server API.
# Download latest release
curl -LO https://github.com/apimgr/weather/releases/latest/download/weather-cli-linux-amd64
chmod +x weather-cli-linux-amd64
sudo mv weather-cli-linux-amd64 /usr/local/bin/weather-cli# Connect to server (creates ~/.config/apimgr/weather/cli.yml)
weather-cli --server https://api.example.com --token YOUR_API_TOKENweather-cli --help
weather-cli weather Brooklyn,NY
weather-cli severe-weather
weather-cli moonConfiguration is auto-generated on first run. Edit via admin panel at http://{fqdn}:{port}/admin.
Key settings:
server.address- Listen address (default: :80)server.mode- production or development
Configuration file: $CONFIG_DIR/server.yml
server:
address: ":80"
mode: production
logging:
level: info
format: json
geoip:
update_interval: 168h
cache:
weather_ttl: 15m
severe_ttl: 5mFull API documentation available at /openapi when running. Interactive GraphQL at /api/v1/graphql.
| Endpoint | Description |
|---|---|
GET /healthz |
Comprehensive health check |
GET /readyz |
Readiness probe (Kubernetes) |
GET /livez |
Liveness probe (Kubernetes) |
| Endpoint | Description |
|---|---|
GET /api/v1/weather |
Current weather (auto-detect location) |
GET /api/v1/weather/:location |
Weather for specific location |
GET /api/v1/forecast |
Multi-day forecast (up to 16 days) |
GET /api/v1/ip |
Client IP and geolocation info |
GET /api/v1/location |
Auto-detect location from IP |
| Endpoint | Description |
|---|---|
GET /api/v1/severe-weather |
Active severe weather alerts |
GET /api/v1/severe-weather/:id |
Get specific alert by ID |
GET /api/v1/earthquakes |
Recent earthquake data (USGS) |
GET /api/v1/earthquakes/:id |
Get specific earthquake by ID |
GET /api/v1/hurricanes |
Active hurricanes (deprecated) |
| Endpoint | Description |
|---|---|
GET /api/v1/moon |
Moon phase, illumination, rise/set |
GET /api/v1/moon/calendar |
Moon phases for a month |
GET /api/v1/sun |
Sunrise, sunset, day length |
| Endpoint | Description |
|---|---|
GET /api/v1/locations |
List saved locations |
POST /api/v1/locations |
Save a new location |
GET /api/v1/locations/search |
Search for locations |
# Weather for location
curl http://localhost/api/v1/weather/Brooklyn,NY
# Severe weather
curl http://localhost/api/v1/severe-weather
# Moon phase
curl http://localhost/api/v1/moon- Weather: Open-Meteo
- US Alerts: NOAA NWS
- Hurricanes: NOAA NHC
- Earthquakes: USGS
- GeoIP: sapics/ip-location-db
- Check logs:
docker logs weather - Health check:
curl http://{fqdn}:{port}/healthz - Port in use:
netstat -tulpn | grep :80
- Documentation: https://apimgr-weather.readthedocs.io
- Issues: https://github.com/apimgr/weather/issues
Development instructions are for contributors only.
- Docker (for containerized builds)
- Make
# Clone
git clone https://github.com/apimgr/weather
cd weather
# Quick dev build (outputs to binaries/)
make dev
# Full build (all platforms, outputs to binaries/)
make build
# Test
make testsrc/ # Source code
tests/ # Test files
docker/ # Docker files
binaries/ # Built binaries (gitignored)
This software is provided "as is" without warranty of any kind. Use at your own risk.
- No Warranty: The authors are not responsible for any damages, data loss, or issues arising from use of this software
- Not Professional Advice: Weather data is provided for informational purposes only and should not be used as the sole basis for safety decisions during severe weather
- Third-Party Services: This software aggregates data from external APIs (Open-Meteo, NOAA, USGS, etc.) - their terms of service and data accuracy apply separately
- Security: While we strive to follow security best practices, no software is guaranteed to be free of vulnerabilities
- Production Use: Evaluate thoroughly before deploying in production environments
By using this software, you acknowledge that you have read and understood this disclaimer.
MIT - See LICENSE.md