# Hong Kong — Polymarket Weather Trading Reference

## Overview

Hong Kong is a priority city for the Poly Weather bot. The Hong Kong Observatory (HKO) is the **official settlement source** for Polymarket Hong Kong temperature markets, making HKO data uniquely valuable — it's both the forecast provider and the ground truth.

- **City slug**: `hong_kong`
- **Temperature unit**: °C
- **Timezone**: `Asia/Hong_Kong` (UTC+8)
- **Polymarket URL pattern**: `https://polymarket.com/event/highest-temperature-in-hong-kong-on-{month}-{day}-{year}`
- **Dashboard page**: `/cities/hong-kong`

---

## HKO Open Data API

Base URL: `https://data.weather.gov.hk/weatherAPI/opendata`

No API key required. No documented rate limits. Free and open.

### 1. 1-Minute Temperature CSV (Primary — 0.1°C precision)

**Endpoint**: `GET https://data.weather.gov.hk/weatherAPI/hko_data/regional-weather/latest_1min_temperature.csv`

Returns real-time readings from **30+ automatic weather stations** with **0.1°C precision**, updated every minute.

**CSV format**:
```csv
Date time,Automatic Weather Station,Air Temperature(degree Celsius)
202603191730,HK Observatory,26.4
202603191730,King's Park,25.8
202603191730,Sha Tin,26.8
202603191730,Tai Mo Shan,18.2
```

**Reference station**: "HK Observatory" (尖沙咀天文台總部) — this is the station used for official temperature records and Polymarket settlement.

**Notes**:
- Some stations may report `N/A` when sensors are offline
- Includes additional stations not in the JSON API (e.g. Ngong Ping, Tai Mo Shan, The Peak, Tate's Cairn)
- Updates every 1 minute (much faster than the JSON API's ~10 min interval)

### 2. Current Observations JSON (Fallback — integer precision)

**Endpoint**: `GET /weather.php?dataType=rhrread&lang=en`

Returns real-time readings from **26 monitoring stations** across Hong Kong, updated approximately every 10 minutes. **Integer precision only** (e.g. 27°C instead of 26.4°C).

**Key response fields**:
```json
{
  "temperature": {
    "data": [
      { "place": "Hong Kong Observatory", "value": 27, "unit": "C" },
      { "place": "King's Park", "value": 26, "unit": "C" }
    ],
    "recordTime": "2026-03-19T17:00:00+08:00"
  },
  "humidity": {
    "data": [{ "place": "Hong Kong Observatory", "value": 58 }],
    "recordTime": "2026-03-19T17:00:00+08:00"
  }
}
```

**Note**: Station names differ between CSV and JSON (e.g. "HK Observatory" in CSV vs "Hong Kong Observatory" in JSON).

### 2. 9-Day Forecast (fnd)

**Endpoint**: `GET /weather.php?dataType=fnd&lang=en`

Returns daily max/min temperature forecasts for the next 9 days. Updated ~4 times daily (around 00:00, 06:00, 12:00, 18:00 HKT).

**Key response fields**:
```json
{
  "updateTime": "2026-03-19T16:30:00+08:00",
  "weatherForecast": [
    {
      "forecastDate": "20260320",
      "week": "Friday",
      "forecastMaxtemp": { "value": 28, "unit": "C" },
      "forecastMintemp": { "value": 23, "unit": "C" },
      "forecastMaxrh": { "value": 85, "unit": "percent" },
      "forecastMinrh": { "value": 60, "unit": "percent" },
      "ForecastIcon": 51,
      "forecastWeather": "Mainly fine. Hot during the day.",
      "forecastWind": "South force 3 to 4.",
      "forecastDate": "20260320"
    },
    ...
  ]
}
```

### 3. Other Useful Endpoints

| dataType | Description | Use Case |
|----------|-------------|----------|
| `flw` | Local Weather Forecast (text) | General outlook |
| `warningInfo` | Weather Warnings | Extreme conditions |
| `sundata` | Sunrise/Sunset times | Daytime determination |

---

## Ensemble Model Integration

HKO is one of 4 models in the ensemble probability calculation:

| Model | Weight | Source | Coverage |
|-------|--------|--------|----------|
| ECMWF | 30% | Open-Meteo | Global |
| GFS | 25% | Open-Meteo | Global |
| **HKO** | **25%** | HKO API | **Hong Kong only** |
| ICON | 20% | Open-Meteo | Global |

For non-Hong Kong cities, HKO is excluded and remaining weights are re-normalized.

HKO has **lower standard errors** than other models for Hong Kong forecasts:

| Lead Time | HKO σ | GFS σ | ECMWF σ | ICON σ |
|-----------|--------|-------|---------|--------|
| 24h | 0.8°C | 1.2°C | 1.0°C | 1.3°C |
| 48h | 1.0°C | 1.5°C | 1.3°C | 1.6°C |
| 72h | 1.2°C | 1.8°C | 1.5°C | 1.9°C |

---

## Strategy Considerations for Hong Kong

### OBSERVED_YES / OBSERVED_NO

These strategies are especially effective for Hong Kong because:
1. **HKO updates every ~hour** — faster than market repricing
2. **HKO is the settlement source** — no discrepancy between observation and settlement
3. **Peak hours 11:00–14:00 HKT** — best window for OBSERVED_YES signals
4. **Daily high usually occurs 13:00–15:00 HKT** — after peak, OBSERVED_NO confidence is highest

### TAIL_NO

Hong Kong temperature distribution is narrow (maritime subtropical climate), so tail buckets (e.g. "32°C or higher" in winter) are often overpriced by the market.

### LATENCY_ARB

HKO forecast updates at ~00:00, 06:00, 12:00, 18:00 HKT. The 06:00 and 12:00 updates are most likely to shift probabilities, creating latency arbitrage windows.

---

## Settlement Rules

- Market question: "Will the high temperature in Hong Kong be X°C on [date]?"
- Settlement source: Hong Kong Observatory official daily maximum temperature
- Settlement time: After midnight HKT on the market date (once daily max is finalized)
- The daily max is typically recorded between 13:00–15:00 HKT

---

## Key File Paths

### Weather Engine (backend)
- `packages/weather-engine/src/providers/hko-api.ts` — HKO provider (fetch + fetchCurrentMax)
- `packages/weather-engine/src/providers/open-meteo.ts` — fetchAllModels() conditionally includes HKO for HK
- `packages/weather-engine/src/ensemble.ts` — Ensemble weights and probability calculation

### Dashboard (frontend)
- `packages/dashboard/src/app/cities/hong-kong/page.tsx` — HK page server component
- `packages/dashboard/src/app/cities/hong-kong/HongKongClient.tsx` — HK page client component
- `packages/dashboard/src/app/api/hko-current/route.ts` — HKO real-time temperature API
- `packages/dashboard/src/app/api/hko-forecast/route.ts` — HKO 9-day forecast API

### Core
- `packages/core/src/constants.ts` — City config (lat/lon, timezone, priority)
- `packages/core/prisma/schema.prisma` — Database schema

---

## HKO Weather History (for verification)

Official daily extract: `https://www.weather.gov.hk/en/cis/dailyExtract.htm?y={year}&m={month}`

Use this to verify settlement temperatures and backtest strategy performance.