weather-trac API
Weather data API powered by Visual Crossing. Provides current conditions, hourly forecasts, multi-day forecasts, weather alerts, and pre-formatted output for Telegram bots and CLI tools.
Base URL: https://api.weather-trac.com
Interactive Docs →
OpenAPI Spec →
Auth Token Setup →
Authentication
All endpoints except /health and /api/v1/info require a Bearer token.
Authorization: Bearer <token>- Tokens issued by Authentik, expire after 10 minutes
- Obtain a token:
auth-token weather-trac - Config:
~/.config/auth-token.env- setAUTHENTIK_URLandWEATHER_TRAC_PUBLIC_CLIENT_ID
Location Format
All weather endpoints accept a location query parameter in one of two formats:
City,State- e.g.Delano,MNorSandpoint,IDlat,lon- e.g.44.97,-93.79
Endpoints
System
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health | No | Public health check - returns {status, timestamp} |
| GET | /api/v1/info | No | API metadata - version, available endpoints, auth server URL |
| GET | /internal/health | Yes | Detailed health with uptime, version, and authenticated user |
| GET | /debug/whoami | Yes | Returns auth context - email and token claims |
Weather - Raw Payloads
| Method | Path | Params | Description |
|---|---|---|---|
| GET | /api/v1/weather/current |
location* |
Current conditions - temp, feels like, humidity, wind, UV index, visibility, sunrise/sunset |
| GET | /api/v1/weather/hourly |
location*, date |
Hourly forecast for a given date. date: YYYY-MM-DD or today (default: today) |
| GET | /api/v1/weather/forecast |
location*, start, duration |
Daily forecast. start: 1-based day offset (default: 1). duration: number of days (default: 7) |
| GET | /api/v1/weather/alerts |
location* |
Active weather alerts. Returns {has_alerts, alerts[]} with headline, description, severity, onset, ends |
Weather - Formatted Responses
Formatted endpoints return both the raw payload (data) and a pre-formatted string or lines (formatted), ready for display in a terminal or chat bot.
| Method | Path | Params | Description |
|---|---|---|---|
| GET | /api/v1/weather/current/formatted |
location* |
Current conditions with emoji-formatted single-line string. e.g. Delano, MN: 🕘 21:17 ☁️ 🌡 27.9°F 🌬 ↙ 7.0 mph |
| GET | /api/v1/weather/hourly/formatted |
location*, date, start, duration |
Hourly forecast as array of formatted lines. start: start hour 0-23. duration: number of hours (default: 24) |
| GET | /api/v1/weather/forecast/formatted |
location*, start, duration, multiline |
Daily forecast as array of formatted lines. multiline=true expands each day to multiple lines |
| GET | /api/v1/weather/telegram |
location* (repeatable), html |
Multi-city daily summary as a single Telegram message string. Pass location multiple times for multi-city output. html=true adds Telegram HTML tags |
* required parameter
Response Models
CurrentWeather
| Field | Type | Description |
|---|---|---|
location | object | {city, state, resolved, latitude, longitude, timezone} |
observed_at | string | ISO-8601 datetime of observation |
conditions | string | Plain-text description, e.g. Partly Cloudy |
temp | object | {f, c} - temperature in Fahrenheit and Celsius |
feels_like | object | {f, c} |
humidity | float | Percent relative humidity |
wind | object | {speed_mph, speed_kph, direction_deg, direction_label, direction_arrow} |
uv_index | float | UV index |
visibility_mi | float | Visibility in miles |
sun | object | {sunrise, sunset, sunrise_12hr, sunset_12hr} |
ForecastWeather / DailySlot
| Field | Type | Description |
|---|---|---|
location | object | Same as CurrentWeather |
days[] | array | Array of daily slots |
days[].date | string | YYYY-MM-DD |
days[].conditions | string | Short condition label |
days[].description | string | Prose day summary |
days[].temp_high / temp_low | object | {f, c} |
days[].humidity | float | Percent |
days[].wind | object | Wind speed and direction |
days[].precip | object | {probability, amount_in, amount_mm, type} |
days[].snow_accum_in | float | Snow accumulation in inches |
days[].moon_phase | float | 0.0–1.0 (0 = new moon, 0.5 = full moon) |
days[].sun | object | Sunrise and sunset times |
Example Requests
# Get a token
TOKEN=$(auth-token weather-trac)
# Current conditions
curl -H "Authorization: Bearer $TOKEN" \
"https://api.weather-trac.com/api/v1/weather/current?location=Delano,MN"
# Current conditions - formatted single line
curl -H "Authorization: Bearer $TOKEN" \
"https://api.weather-trac.com/api/v1/weather/current/formatted?location=Delano,MN"
# 7-day forecast
curl -H "Authorization: Bearer $TOKEN" \
"https://api.weather-trac.com/api/v1/weather/forecast?location=Sandpoint,ID&duration=7"
# Hourly forecast - next 6 hours starting at 8am
curl -H "Authorization: Bearer $TOKEN" \
"https://api.weather-trac.com/api/v1/weather/hourly/formatted?location=Delano,MN&start=8&duration=6"
# Weather alerts
curl -H "Authorization: Bearer $TOKEN" \
"https://api.weather-trac.com/api/v1/weather/alerts?location=Minneapolis,MN"
# Multi-city Telegram summary
curl -H "Authorization: Bearer $TOKEN" \
"https://api.weather-trac.com/api/v1/weather/telegram?location=Delano,MN&location=Sandpoint,ID"Error Codes
| Status | Meaning |
|---|---|
400 | Bad request - missing or invalid parameter |
401 | Missing or invalid Bearer token |
502 | Upstream Visual Crossing API error |
Contact
Email: [email protected]
License: Internal / Partner Use Only