API Reference

Authentication

All API endpoints require your API key in the X-Api-Key header. Your key is issued when you subscribe to Pro, Ultra, or Agentic.

GET /forecast_v2?lat=51.0447&lon=-114.0719&units=metric HTTP/1.1
Host: xojr-u3gp-4r20.n2.xano.io
X-Api-Key: YOUR_API_KEY

GET /forecast_v2

Returns the full AI-enriched weather payload for the given coordinates. Coordinates are snapped to an H3 Resolution 6 cell (~3.2 km) for cache lookup — exact coordinates are never stored. Cache-first: ~80% of requests return in under 50 ms at zero AI cost.

Query Parameters

Example Request

curl "https://xojr-u3gp-4r20.n2.xano.io/api:z3ww5TpX/forecast_v2?lat=51.0447&lon=-114.0719&units=metric" \
  -H "X-Api-Key: YOUR_API_KEY"

GET /forecast_city

Accepts a city name instead of coordinates. Geocodes via OpenWeather Geocoding API, then returns the same AI-enriched payload as /forecast_v2. Ideal for voice assistants, chatbots, and dashboards where the user supplies a place name. Results are H3-cached the same way — repeat calls for the same city area are instant.

For best results, include a country or state code: Calgary, CA or Portland, OR, US. Requires Pro or higher — not available on the free tier.

Query Parameters

Example Request

curl "https://xojr-u3gp-4r20.n2.xano.io/api:z3ww5TpX/forecast_city?city=Calgary%2C+CA&units=metric" \
  -H "X-Api-Key: YOUR_API_KEY"

Additional Response Fields

The response includes two extra fields not present in /forecast_v2:

{
  "success": true,
  "city_resolved": "Calgary, Alberta, CA",
  "resolved_coordinates": {
    "lat": 51.0447,
    "lon": -114.0719
  },
  "message": { ... }
}

Response Schema

Both endpoints return the same message object. All responses are application/json.

Current conditions

{
  "message": {
    "location_name": "Calgary, Alberta",
    "current": {
      "weather": {
        "main": "Clouds",
        "description": "Overcast clouds"
      },
      "context": {
        "vibe": "A crisp, grey autumn morning with a northwest chill that makes the 4°C feel closer to 1°C.",
        "clothing_hint": "Warm mid-layer and a wind-resistant shell. Gloves optional but appreciated."
      }
    }
  }
}

Telegram-optimised strings

Pre-formatted for TTS. Numbers written as words. No special characters.

{
  "message": {
    "telegram": {
      "temp_metric": "4°C",
      "temp_imperial": "39°F",
      "briefing": "Four degrees Celsius, feels like one. Overcast skies and a northwest wind at twelve kilometres per hour...",
      "morning": "A cold, grey start to the day. Bundle up before heading out.",
      "commute": "Roads are dry but the windchill is a factor on exposed intersections.",
      "tomorrow": "A milder system moves in overnight — expect temperatures closer to ten degrees by midday.",
      "seven_day_summary": "A brief warm spell midweek gives way to another cold front by the weekend."
    }
  }
}

Hourly forecast (next 12 hours)

{
  "message": {
    "next_12h": [
      {
        "time": "2026-08-14T15:00",
        "temp_c": 18.4,
        "weather_description": "Partly cloudy",
        "wind_speed_kmh": 14,
        "wind_direction": "NW",
        "humidity_pct": 52
      }
    ]
  }
}

7-day daily forecast

{
  "message": {
    "daily": [
      {
        "date": "2026-08-14",
        "weather": { "main": "Clouds" },
        "temp_max_c": 22,
        "temp_min_c": 11,
        "temp_max_f": 72,
        "temp_min_f": 52,
        "precip_mm": 0
      }
    ]
  }
}

Air quality

{
  "message": {
    "air_quality": {
      "us_aqi": 24,
      "aqi_category": "Good",
      "pm25": 4.2,
      "pm10": 8.1,
      "ozone": 61.3,
      "no2": 5.8,
      "pollen": {
        "alder": 0,
        "birch": 0,
        "grass": 12,
        "ragweed": 0
      }
    }
  }
}

Cache Headers

Every response includes cache diagnostic headers:

Error Responses