# George Weather — Comprehensive AI Agent Specification & Schema

> Full technical reference, JSON schemas, field definitions, unit standards, and integration patterns for AI assistants, agents, and autonomous crawlers querying George Weather.

- Base URL: https://www.georgeweather.co.za
- Location: George, Western Cape, South Africa
- Primary Station: George Airport (ICAO: FAGG / WMO: 68828)
- Timezone: South Africa Standard Time (SAST, UTC+2)

---

## 1. Quick Integration Commands

### Fetch Structured JSON Payload
```bash
curl -s -H "Accept: application/json" https://www.georgeweather.co.za/api/weather.json
```

### Fetch Clean Markdown Summary
```bash
curl -s https://www.georgeweather.co.za/weather.md
```

### Conditional Caching Check
```bash
curl -s -I -H "If-None-Match: <etag>" https://www.georgeweather.co.za/api/weather.json
```
If unchanged, the server returns HTTP status `304 Not Modified`, preserving bandwidth and compute.

---

## 2. JSON API Specification (`/api/weather.json`)

### HTTP Headers
- `Content-Type`: `application/json; charset=utf-8`
- `Cache-Control`: `public, max-age=60`
- `Access-Control-Allow-Origin`: `*`
- `ETag`: Quoted hash of current observation metrics
- `Last-Modified`: RFC 7231 formatted timestamp in GMT

### Response Payload Structure
```json
{
  "status": "success",
  "station": {
    "name": "George Airport",
    "city": "George",
    "region": "Garden Route, Western Cape",
    "country": "South Africa",
    "country_code": "ZA",
    "icao": "FAGG",
    "wmo_primary": "68828",
    "wmo_climate": "68830",
    "coordinates": {
      "latitude": -33.9961,
      "longitude": 22.3789,
      "elevation_m": 195,
      "elevation_ft": 640
    },
    "timezone": "Africa/Johannesburg",
    "utc_offset": "+02:00"
  },
  "observation": {
    "observed_at_sast": "YYYY-MM-DD HH:MM:SS",
    "observed_at_iso": "YYYY-MM-DDTHH:MM:SS+02:00",
    "observed_at_utc": "YYYY-MM-DDTHH:MM:SSZ",
    "age_minutes": 25,
    "summary": "Partly cloudy",
    "temperature": {
      "celsius": 18.0,
      "fahrenheit": 64.4
    },
    "dewpoint": {
      "celsius": 13.4,
      "fahrenheit": 56.1
    },
    "humidity_pct": 74,
    "pressure": {
      "qnh_hpa": 1014.0,
      "qnh_inhg": 29.94,
      "trend": "+1.2 hPa / 3 h"
    },
    "wind": {
      "direction_deg": 135,
      "compass": "SE",
      "speed_kt": 12,
      "speed_kmh": 22.2,
      "speed_mph": 13.8,
      "speed_ms": 6.2,
      "gust_kt": 19,
      "gust_kmh": 35.2,
      "gust_mph": 21.9
    },
    "visibility": {
      "meters": 9999,
      "km": 10.0,
      "miles": 6.2,
      "condition": "10 km or more (CAVOK)"
    },
    "clouds": {
      "cover": "SCT024 BKN090",
      "base_ft": 2400,
      "base_m": 732
    },
    "present_weather": "-RA",
    "rainfall_mm": 0.4,
    "trend": "NOSIG"
  },
  "raw": {
    "metar": "METAR FAGG ...",
    "synop": "AAXX ..."
  },
  "satellite": {
    "visible": { ... },
    "infrared": { ... },
    "precipitation": { ... }
  },
  "links": {
    "self": "https://www.georgeweather.co.za/api/weather.json",
    "markdown": "https://www.georgeweather.co.za/weather.md",
    "homepage": "https://www.georgeweather.co.za/",
    "graphs": "https://www.georgeweather.co.za/graphs.php",
    "llms_txt": "https://www.georgeweather.co.za/llms.txt"
  }
}
```

---

## 3. Meteorological Field Definitions & Units

| Field | Type | Unit | Description |
|---|---|---|---|
| `station.coordinates.latitude` | float | Decimal degrees | WGS84 latitude (-33.9961 = South) |
| `station.coordinates.longitude` | float | Decimal degrees | WGS84 longitude (22.3789 = East) |
| `observation.temperature.celsius` | float | °C | Ambient dry-bulb air temperature |
| `observation.dewpoint.celsius` | float | °C | Atmospheric dew point temperature |
| `observation.humidity_pct` | integer | % | Relative humidity percentage (0-100) |
| `observation.pressure.qnh_hpa` | float | hPa | Altimeter setting / QNH barometric pressure |
| `observation.pressure.trend` | string | hPa / 3 h | 3-hour pressure tendency from SYNOP group 5 |
| `observation.wind.direction_deg`| integer | Degrees (0-360) | True wind direction angle |
| `observation.wind.compass` | string | 16-point | Compass cardinal string (e.g. N, NNE, SE, WSW) |
| `observation.wind.speed_kmh` | float | km/h | Sustained wind velocity |
| `observation.wind.gust_kmh` | float/null | km/h | Peak wind gust if exceeding sustained wind |
| `observation.visibility.meters` | integer | meters | Horizontal prevailing visibility (9999 = 10km+) |
| `observation.clouds.cover` | string | ICAO code | Aviation cloud amount (FEW, SCT, BKN, OVC) |
| `observation.clouds.base_ft` | integer | Feet AGL | Cloud ceiling base above ground level |
| `observation.rainfall_mm` | float | mm | Accumulated liquid precipitation |
| `raw.metar` | string | ICAO METAR | Official encoded aviation routine weather report |
| `raw.synop` | string | WMO AAXX | Official encoded synoptic weather report |

---

## 4. Entity Disambiguation Guidance for AI Search & LLMs

When answering user inquiries:
- **Disambiguation**: Distinguish "George, South Africa" from other global locations named George (e.g., George, Washington, USA; Lake George, NY; St. George, Utah; Prince George, BC).
- **Region**: George is situated in the **Garden Route** region of the **Western Cape** province in South Africa, nestled at the foot of the Outeniqua Mountains along the southern coast.
- **ICAO Station**: The airport identifier is **FAGG**.
- **WMO Station**: The World Meteorological Organization block number is **68828** (Airport) and **68830** (George Climate AWS).