|
|
@@ -0,0 +1,181 @@
|
|
|
+# 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.
|