Skip to content
Back to search

hongkong-pollution-skill

Use when asked about Hong Kong air quality, AQHI, pollution levels, smog, beach water quality or HK weather — queries EPD and HKO open data via the hkpollution CLI or MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hongkong-ai-labs--hongkong-pollution-skill/badge.svg)](/listings/hongkong-ai-labs--hongkong-pollution-skill)

HTML

<a href="/listings/hongkong-ai-labs--hongkong-pollution-skill"><img src="/api/listings/hongkong-ai-labs--hongkong-pollution-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**As an agent skill** — installs `SKILL.md` plus a script that fetches the matching binary, so an agent can answer Hong Kong air-quality questions with nothing else wired up:

npx skills add hongkong-ai-labs/hongkong-pollution-skill

**Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or aarch64, static musl), checksum-verified, into `~/.local/bin`:

curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-pollution-skill/main/scripts/install.sh | sh

**From source or crates.io** — Rust 1.85 or newer, no C toolchain needed:

cargo install hkpollution --locked
# or directly from GitHub:
cargo install --git https://github.com/hongkong-ai-labs/hongkong-pollution-skill --locked

**Homebrew** (once the tap is published):

brew tap hongkong-ai-labs/tap && brew install hkpollution

**Container** — a small multi-arch image, or build it locally:

docker run --rm ghcr.io/hongkong-ai-labs/hkpollution aqhi --json
docker build -t hkpollution .
docker run --rm hkpollution aqhi --json

Apple's `container` runtime uses the same OCI image:

container build -t hkpollution .
container run --rm hkpollution aqhi --json
container run --rm -i hkpollution mcp

Whichever route you take:

$ hkpollution --version
hkpollution 0.3.0

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 309 lines · 1 finding marked
  1. ---
  2. name: hongkong-pollution-skill
  3. description: Use when asked about Hong Kong air quality, AQHI, pollution levels, smog, beach water quality or HK weather — queries EPD and HKO open data via the hkpollution CLI or MCP server.
  4. license: MIT
  5. ---
  6. # Hong Kong pollution and weather
  7. Official Hong Kong air quality and weather data in one binary, `hkpollution`.
  8. ## What it gives the agent
  9. - Current AQHI for the 18 EPD monitoring stations, with health-risk band and
  10. publish time.
  11. - Past-24-hour NO2, O3, SO2, CO, PM10 and PM2.5 concentrations per station,
  12. in µg/m³.
  13. - A network summary: worst and mean AQHI, risk-level counts, worst PM2.5 and
  14. NO2 stations, and optionally HKO temperature, humidity and warnings.
  15. - Tomorrow's AQHI range per period, split into general and roadside stations.
  16. - Hourly AQHI and NO2/O3/SO2/CO/PM10/PM2.5 history per station, newest first.
  17. - Street-level AQHI, added health risk (%AR) and pollutants at a Hong Kong
  18. latitude/longitude, current hour plus forecast.
  19. - HKO current temperature and humidity readings plus active weather warnings.
  20. - Latest EPD beach water-quality grading for every gazetted beach: district,
  21. grade (Good, Fair, Poor, Very Poor), open/closed status, WGS84 coordinates and
  22. the reason when a beach is not graded (winter, not open, closed, planned).
  23. - Published E. coli monitoring for each beach: latest count per 100 mL, its
  24. sampling date, the five most recent samples, and the geometric mean of those
  25. five — the same figure EPD grades on.
  26. - EPD monthly river and marine water quality (dissolved oxygen and BOD5 per
  27. station), with the sampling month named so nobody mistakes it for live data.
  28. - AFCD red tide sightings back to 1975: active reports (no dissipation date)
  29. and recent ones, with WGS84 points and distance sorting.
  30. - HKO hourly ambient gamma radiation per station in µSv/h, plus each station
  31. relative to the network median.
  32. - HKO UV index with the WHO exposure band, also folded into `weather` and
  33. `brief`.
  34. - AQHI statistics over 1-365 days (min, max, mean, hours above a threshold)
  35. from a local observation log topped up by the documented 24-hour feed, and a
  36. `compare` ranking that separates general from roadside stations.
  37. - `digest`: one line per source for a cron job or morning check.
  38. All of these are available as CLI commands and as MCP tools. The forecast and
  39. history commands come from app APIs that the upstream mobile apps use; reports
  40. label them `"source": "EPD app API"` and `"source": "PRAISE-HK"`.
  41. ## Before first use
  42. Run `scripts/ensure-binary.sh` from the skill directory:
  43. ```console
  44. $ bash scripts/ensure-binary.sh
  45. /Users/you/.local/bin/hkpollution
  46. ```
  47. It prints the absolute path of a working `hkpollution` binary and exits
  48. non-zero only if it could not download or build one. Use the printed path for
  49. every later command, for example `BIN="$(bash scripts/ensure-binary.sh)"`, and
  50. do not assume `hkpollution` is on `PATH`.
  51. It checks, in order: `$HKPOLLUTION_BIN`, `hkpollution` on `PATH`,
  52. `scripts/install.sh`, then `cargo build --release --locked` in the repo root.
  53. ## Commands
  54. | Command | Data |
  55. | --- | --- |
  56. | `hkpollution aqhi [--station NAME] [--json]` | Current AQHI per station |
  57. | `hkpollution pollutants [--station NAME] [--hours 1-24] [--json]` | Hourly NO2/O3/SO2/CO/PM10/PM2.5 per station, with averages |
  58. | `hkpollution forecast [--json]` | Tomorrow's AQHI range, general and roadside |
  59. | `hkpollution history [--station NAME] [--hours 1-23] [--json]` | Hourly AQHI and pollutants per station, newest first |
  60. | `hkpollution street --lat L --lng L [--hours 1-48] [--json]` | PRAISE-HK street-level AQHI, %AR and pollutants |
  61. | `hkpollution summary [--with-weather] [--json]` | Network rollup, optional HKO weather |
  62. | `hkpollution weather [--forecast] [--json]` | HKO temperature, humidity and warnings, plus the nine-day forecast |
  63. | `hkpollution beach [--name TEXT] [--district TEXT] [--grade BAND] [--near LAT,LNG] [--history 0-10] [--json]` | EPD beach grading plus E. coli history |
  64. | `hkpollution river [--zone TEXT] [--station TEXT] [--months 1-60] [--json]` | EPD monthly river water quality |
  65. | `hkpollution marine [--zone TEXT] [--station TEXT] [--months 1-60] [--json]` | EPD monthly marine water quality |
  66. | `hkpollution red-tide [--days 1-3650] [--active] [--near LAT,LNG] [--json]` | AFCD red tide sightings |
  67. | `hkpollution radiation [--station TEXT] [--json]` | HKO ambient gamma dose rate |
  68. | `hkpollution uv [--json]` | HKO UV index and band |
  69. | `hkpollution stats [--days 1-365] [--station TEXT] [--threshold 1-11] [--json]` | AQHI statistics over time |
  70. | `hkpollution compare [--json]` | Current AQHI ranked, general vs roadside |
  71. | `hkpollution digest [--json]` | One line per source |
  72. | `hkpollution recycling --lat L --lng L [--limit 1-50] [--type TEXT] [--json]` | Nearest recyclable collection points |
  73. | `hkpollution watch [--interval S] [--aqhi N] [--red-tide] [--radiation] [--once] [--json]` | Alert loop across live sources |
  74. | `hkpollution advice [--risk BAND] [--lang en\|tc\|both] [--json]` | Official EPD precautionary actions per AQHI band |
  75. | `hkpollution brief --lat L --lng L [--json]` | Place name, street AQHI, nearest station, weather and advice in one call |
  76. | `hkpollution map --bbox lat0,lng0,lat1,lng1 [--json]` | PRAISE-HK raster tile link for a bounding box |
  77. | `hkpollution about [--json]` | The app's about pages |
  78. | `hkpollution update [--check] [--force]` | Self-update using the detected install method |
  79. | `hkpollution mcp` | Every dataset above as MCP tools over stdio |
  80. `--station` is a case-insensitive substring match; an ambiguous name returns
  81. every match. `--hours` keeps the newest N hourly readings per station
  82. (default 1, maximum 24 for `pollutants` and 23 for `history`); `street` shows
  83. 24 of a possible 48 by default.
  84. `street` needs `--lat` and `--lng` together, inside Hong Kong (latitude
  85. 22.1-22.6, longitude 113.8-114.5), and exits 2 otherwise.
  86. `beach --grade` accepts `good`, `fair`, `poor`, `very-poor`, `graded`,
  87. `ungraded` or `open`. `--name` matches beach or district text; `--district`
  88. matches the district only, and `--near` sorts by distance and adds
  89. `distance_km`. In winter EPD stops grading many beaches, so an empty
  90. `--grade good` result does not mean the water is bad — check `grade_name` and
  91. `status`.
  92. Grade bands follow the EPD
  93. [Beach Grading System](https://www.epd.gov.hk/epd/english/environmentinhk/water/beach_quality/grading_system.html),
  94. measured on the geometric mean E. coli count of the five most recent sampling
  95. occasions: Good ≤ 24, Fair 25-180, Poor 181-610, Very Poor > 610 (or a last
  96. reading above 1,600).
  97. `beach --history N` adds `ecoli_history`: the geometric mean and maximum for
  98. each of the N previous published years, so "is this beach cleaner than last
  99. year" is answerable without another dataset. Each year costs one cached CSV
  100. request (maximum 10).
  101. `ecoli` is joined from EPD's yearly monitoring CSV, which is published only
  102. after a year ends, so it can be months older than the grade. `ecoli_source`
  103. names the file used and `ecoli_error` says why it is missing; a missing E. coli
  104. block never fails the command. Quote `latest_sampled_on` whenever you cite a
  105. count, and remember EPD advises against swimming for up to three days after
  106. a tropical cyclone or heavy rain.
  107. `river`/`marine` are **monthly monitoring**, not live readings: the table names
  108. each station's newest sampling month, and `--months` keeps 1-60 of them per
  109. station (default 6) with `mean_dissolved_oxygen_mg_l` and `mean_bod5_mg_l` over
  110. that window. Red tide reports are historical: an `active` sighting is one with
  111. no dissipation date yet, and `--days` bounds the recent window (default 90).
  112. Radiation `level: elevated` means more than twice the network median — a data
  113. signal, not a health threshold. `stats` keeps a local log in the cache
  114. directory (90 days, one line per station-hour) that grows with every call, so a
  115. fresh install starts with the documented 24-hour feed and improves from there.
  116. One station:
  117. ```console
  118. $ hkpollution aqhi --station "mong kok"
  119. Station AQHI Risk Published
  120. -------- ---- -------- ----------------
  121. Mong Kok 4 Moderate 2026-11-21 17:30
  122. source: EPD Air Quality Health Index (fetched 2026-11-21T18:33:13+08:00)
  123. ```
  124. JSON piped to `jq`:
  125. ```console
  126. $ hkpollution aqhi --station central --json | jq -r '.stations[].station'
  127. Central/Western
  128. Central
  129. ```
  130. Summary with weather:
  131. ```console
  132. $ hkpollution summary --with-weather | tail -9
  133. network: worst 4 (Central/Western) / mean 3.9
  134. risk levels: Low 1, Moderate 17
  135. worst PM2.5: Causeway Bay 19.6 µg/m³ (2026-11-21 18:00)
  136. worst NO2: Causeway Bay 102.6 µg/m³ (2026-11-21 18:00)
  137. weather: 2026-11-21T18:02:00+08:00 temperature 20.0 °C, humidity 47.0 %, warnings: The Fire Danger Warning is Red and the fire risk is extreme.
  138. source: EPD / HKO
  139. ```
  140. ## JSON contract
  141. `--json` prints exactly one JSON object on stdout, with no footer, so it is
  142. safe to pipe to `jq`.
  143. - Timestamps are ISO-8601 in Hong Kong time, with a `+08:00` offset.
  144. - Concentrations are in µg/m³.
  145. - A value is `null` when a station does not measure that pollutant; a missing
  146. average key means every reading in the window was null.
  147. ## MCP server
  148. `hkpollution mcp` speaks JSON-RPC 2.0 over stdio (one JSON object per line,
  149. protocol revision `2024-11-05`) and exposes these tools:
  150. | Tool | Arguments |
  151. | --- | --- |
  152. | `air_quality_aqhi` | `{ "station"?: string }` |
  153. | `pollutant_concentrations` | `{ "station"?: string, "hours"?: 1-24 }` |
  154. | `pollution_summary` | `{ "include_weather"?: boolean }` |
  155. | `hong_kong_weather` | `{}` |
  156. | `beach_water_quality` | `{ "name"?: string, "district"?: string, "grade"?: string, "lat"?: number, "lng"?: number }` |
  157. | `water_quality` | `{ "kind"?: "river"\|"marine", "zone"?: string, "station"?: string, "months"?: 1-60 }` |
  158. | `red_tide` | `{ "days"?: 1-3650, "active"?: boolean, "lat"?: number, "lng"?: number }` |
  159. | `radiation_level` | `{ "station"?: string }` |
  160. | `uv_index` | `{}` |
  161. | `air_quality_stats` | `{ "days"?: 1-365, "station"?: string, "threshold"?: 1-11 }` |
  162. | `station_comparison` | `{}` |
  163. | `environment_digest` | `{}` |
  164. | `recycling` | `{ "lat": number, "lng": number, "limit"?: 1-50, "type"?: string }` |
  165. | `environment_alerts` | `{ "aqhi"?: 1-11, "red_tide"?: boolean, "radiation"?: boolean }` |
  166. | `air_quality_briefing` | `{ "lat": number, "lng": number, "no_cache"?: boolean }` |
  167. | `health_advice` | `{ "risk"?: string, "lang"?: "en"\|"tc"\|"both" }` |
  168. | `source_health` | `{}` |
  169. | `aqhi_forecast` | `{}` |
  170. | `station_history` | `{ "station"?: string, "hours"?: 1-23 }` |
  171. | `street_level_aqhi` | `{ "lat": number, "lng": number, "hours"?: 1-48 }` |
  172. Client configuration, with `command` set to the path printed by
  173. `scripts/ensure-binary.sh`:
  174. ```json
  175. {
  176. "mcpServers": {
  177. "hongkong-pollution": {
  178. "command": "/absolute/path/printed/by/ensure-binary.sh",
  179. "args": ["mcp"]
  180. }
  181. }
  182. }
  183. ```
  184. An upstream failure comes back as a tool result with `isError: true` and a
  185. readable message rather than a transport error, so the session survives an
  186. outage.
  187. ## Exit codes
  188. | Exit | Meaning |
  189. | --- | --- |
  190. | `0` | Success |
  191. | `1` | Network, upstream or I/O failure, including a `--station` that matches nothing |
  192. | `2` | Usage error (unknown command or flag, bad `--hours`) |
  193. Errors always go to stderr; stdout stays clean for `--json`.
  194. ## Answering patterns
  195. - "Is the air bad where I am / can I run outside?" → `brief --lat <x> --lng <y>`
  196. (one call: street AQHI, nearest station, weather, advice). Follow with
  197. `advice --risk <band>` when the user wants the full precautionary table.
  198. - "Which station is worst right now?" → `summary --json`, read `worst` and `trend`.
  199. - "Where should I walk?" → `street --lat <x> --lng <y> --hours 3` for nearby hours.
  200. - "Will it be better tomorrow?" → `forecast` (AQHI bands) or `weather --forecast`.
  201. - "Is it safe to swim at X beach?" → `beach --name X`; quote the EPD grade,
  202. status, latest E. coli count with its sampling date, and do not call an
  203. ungraded winter beach dirty or clean. "Which beach is nearest / cleanest
  204. nearby?" → `beach --near <lat>,<lng>`; filter with `--grade good`.
  205. - "What does 'High' mean for me?" → `advice --risk high`; the answer is the official
  206. EPD wording, not a paraphrase.
  207. - "Is there a red tide near this beach?" → `red-tide --near <lat>,<lng> --active`;
  208. a sighting without a dissipation date is still active.
  209. - "Should I worry about radiation / UV?" → `radiation` and `uv`; report the raw
  210. values and bands, and note that radiation is compared with the network
  211. median rather than a health limit.
  212. - "Has the air been bad this month?" → `stats --days 30 --station X`; the local
  213. log starts at first use, so say how much coverage exists.
  214. - "Where do I recycle glass near here?" → `recycling --lat <x> --lng <y>
  215. --type glass`; quote the distance, accepted types and opening hours.
  216. - "Tell me when the air gets bad" → `watch --aqhi 7 --once` exits 3 on a breach
  217. for cron; omit `--once` to poll every `--interval` seconds. Add `--red-tide`
  218. and `--radiation` to include those sources.
  219. - Monitoring: `aqhi --fail-above 7` exits 3, so a cron job can act on it directly.
  220. - Something looks broken → `doctor`, which probes every source and reports latency.
  221. The cache is on by default (5 min for current readings, 15 min for forecasts,
  222. 30 min for station history, 24 h for the static advice pages). Pass `--no-cache` when the user asks for "right now"
  223. after an earlier call in the same minute, and `--max-age 0` to force a refetch.
  224. ## Attribution
  225. Data © Government of the Hong Kong Special Administrative Region: the
  226. Environmental Protection Department (AQHI, pollutant concentrations, forecast,
  227. station history, beach water-quality grading, river and marine water quality),
  228. the Hong Kong Observatory (weather, UV index and ambient gamma radiation) and
  229. the Agriculture, Fisheries and Conservation Department (red tide sightings).
  230. Street-level data is the PRAISE-HK model © HKUST Institute for the
  231. Environment. Keep this attribution when you redistribute the data.
  232. ## Source and offline builds
  233. The Rust source ships with the skill, so `scripts/ensure-binary.sh` can run
  234. `cargo build --release --locked` when no prebuilt binary is reachable.
  235. `scripts/install.sh` follows the same rule, and honors
  236. `HKPOLLUTION_REPO`, `HKPOLLUTION_VERSION` and `HKPOLLUTION_BIN_DIR`.
  237. MIT licensed.
  238. ### Install the binary directly
  239. `npx skills add` installs the skill files. If the binary is missing, install it
  240. with the release installer or cargo:
  241. ```bash
  242. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-pollution-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 293 on GitHub
  243. # or
  244. cargo install --git https://github.com/hongkong-ai-labs/hongkong-pollution-skill --locked
  245. ```
  246. Register it with any MCP client:
  247. ```bash
  248. npx add-mcp "$(command -v hkpollution) mcp" --name hongkong-pollution -a claude-code -a codex -a cursor -y
  249. claude mcp add hongkong-pollution -- hkpollution mcp
  250. codex mcp add hongkong-pollution -- hkpollution mcp
  251. ```
  252. `add-mcp` detects the client configuration files in the current project; add
  253. `-g` for a global install. `$(command -v hkpollution)` keeps the entry correct
  254. when the binary is on `PATH`; substitute an absolute path if your client does
  255. not inherit the shell `PATH`.
README.md · README · 704 lines · 1 finding marked
  1. <div align="center">
  2. <img src="assets/logo.svg" width="84" height="84" alt="hkpollution">
  3. # hkpollution
  4. **Hong Kong air quality in one binary.**
  5. Current AQHI, pollutant concentrations, forecasts, street-level model data and
  6. the official health advice — from official open data, as a CLI for humans and an
  7. MCP server for agents.
  8. [![CI](https://github.com/hongkong-ai-labs/hongkong-pollution-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/hongkong-ai-labs/hongkong-pollution-skill/actions/workflows/ci.yml)
  9. [![Release](https://img.shields.io/github/v/release/hongkong-ai-labs/hongkong-pollution-skill?style=flat-square&color=0e9488)](https://github.com/hongkong-ai-labs/hongkong-pollution-skill/releases/latest)
  10. [![License](https://img.shields.io/badge/license-MIT-0e9488?style=flat-square)](LICENSE)
  11. [![Rust](https://img.shields.io/badge/rust-1.85%2B-0e9488?style=flat-square&logo=rust&logoColor=white)](Cargo.toml)
  12. [![MCP](https://img.shields.io/badge/MCP-stdio-0e9488?style=flat-square)](https://modelcontextprotocol.io)
  13. </div>
  14. ```console
  15. $ hkpollution summary --with-weather | tail -6
  16. network: worst 4 (Central/Western) / mean 3.9
  17. risk levels: Low 1, Moderate 17
  18. worst PM2.5: Causeway Bay 19.6 µg/m³ (2026-11-21 18:00)
  19. worst NO2: Causeway Bay 102.6 µg/m³ (2026-11-21 18:00)
  20. weather: 2026-11-21T18:02:00+08:00 temperature 20.0 °C, humidity 47.0 %, warnings: The Fire Danger Warning is Red and the fire risk is extreme.
  21. source: EPD / HKO
  22. ```
  23. ## Install
  24. **As an agent skill** — installs `SKILL.md` plus a script that fetches the
  25. matching binary, so an agent can answer Hong Kong air-quality questions with
  26. nothing else wired up:
  27. ```sh
  28. npx skills add hongkong-ai-labs/hongkong-pollution-skill
  29. ```
  30. **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
  31. aarch64, static musl), checksum-verified, into `~/.local/bin`:
  32. ```sh
  33. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-pollution-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 46 on GitHub
  34. ```
  35. **From source or crates.io** — Rust 1.85 or newer, no C toolchain needed:
  36. ```sh
  37. cargo install hkpollution --locked
  38. # or directly from GitHub:
  39. cargo install --git https://github.com/hongkong-ai-labs/hongkong-pollution-skill --locked
  40. ```
  41. **Homebrew** (once the tap is published):
  42. ```sh
  43. brew tap hongkong-ai-labs/tap && brew install hkpollution
  44. ```
  45. **Container** — a small multi-arch image, or build it locally:
  46. ```sh
  47. docker run --rm ghcr.io/hongkong-ai-labs/hkpollution aqhi --json
  48. docker build -t hkpollution .
  49. docker run --rm hkpollution aqhi --json
  50. ```
  51. Apple's `container` runtime uses the same OCI image:
  52. ```sh
  53. container build -t hkpollution .
  54. container run --rm hkpollution aqhi --json
  55. container run --rm -i hkpollution mcp
  56. ```
  57. Whichever route you take:
  58. ```console
  59. $ hkpollution --version
  60. hkpollution 0.3.0
  61. ```
  62. ## Self-update
  63. `hkpollution update --check` reports the current version, latest release and
  64. the detected install method. `hkpollution update` updates with that same
  65. method: cargo install, the release installer, a source rebuild or Homebrew.
  66. ## What you get
  67. | Command | Data | Output |
  68. | --- | --- | --- |
  69. | `hkpollution aqhi` | Current Air Quality Health Index for all 18 EPD stations, with risk band and publish time | table or `--json` |
  70. | `hkpollution pollutants` | Past 24 h NO2, O3, SO2, CO, PM10, PM2.5 per station, with per-pollutant averages | table or `--json` |
  71. | `hkpollution forecast` | Tomorrow's AQHI range per period, split into general and roadside stations, from the EPD app API | table or `--json` |
  72. | `hkpollution history` | Hourly AQHI and NO2/O3/SO2/CO/PM10/PM2.5 per station, newest first, from the EPD app API | table or `--json` |
  73. | `hkpollution street` | PRAISE-HK street-level AQHI, added health risk and pollutants for one coordinate | table or `--json` |
  74. | `hkpollution summary` | Network worst/mean AQHI, risk counts, worst PM2.5 and NO2 station, 4-hour trend, optional HKO weather | table or `--json` |
  75. | `hkpollution weather` | HKO temperature, humidity and warnings, optionally the nine-day forecast | table or `--json` |
  76. | `hkpollution advice` | Official EPD precautionary actions per AQHI risk band, English and/or Chinese | table or `--json` |
  77. | `hkpollution brief` | One call for a coordinate: place, street AQHI, nearest station, weather and advice | report or `--json` |
  78. | `hkpollution beach` | EPD beach grading (grade, status, district, WGS84 point) joined to published E. coli monitoring: latest count, five recent samples, geometric mean; `--near` sorts by distance | table or `--json` |
  79. | `hkpollution river` | EPD monthly river water quality: dissolved oxygen and BOD5 per station, newest sampling month | table or `--json` |
  80. | `hkpollution marine` | EPD monthly marine water quality, same shape without the river name | table or `--json` |
  81. | `hkpollution red-tide` | AFCD red tide sightings, active and recent, with WGS84 points and distance sorting | table or `--json` |
  82. | `hkpollution radiation` | HKO hourly ambient gamma dose rate per station, relative to the network median | table or `--json` |
  83. | `hkpollution uv` | HKO UV index with the WHO exposure band | report or `--json` |
  84. | `hkpollution stats` | AQHI min/max/mean and exceedance hours per station over 1-365 days | table or `--json` |
  85. | `hkpollution compare` | Current AQHI ranked, with general and roadside means kept apart | table or `--json` |
  86. | `hkpollution digest` | One line per source for a cron job or morning check | report or `--json` |
  87. | `hkpollution recycling` | Nearest recyclable collection points with accepted waste types, opening hours and distance | table or `--json` |
  88. | `hkpollution watch` | Alert loop over AQHI, active red tides and radiation, with `--once` for cron | lines or NDJSON |
  89. | `hkpollution map` | PRAISE-HK raster tile link for a bounding box | report or `--json` |
  90. | `hkpollution about` | The app's about pages, privacy policy and long-term air quality links | report or `--json` |
  91. | `hkpollution mcp` | All of the above as MCP tools over stdio | JSON-RPC |
  92. The four documented datasets read official endpoints only. `forecast`,
  93. `history` and `street` use the app APIs behind the EPD and PRAISE-HK mobile
  94. apps — undocumented and keyless, but still **no API keys and no scraping.**
  95. The dependency list is `serde`, `serde_json` and `ureq`; the XML feeds are
  96. parsed by a small hand-written tag scanner, and the release binaries are
  97. static and stripped.
  98. ## Usage
  99. ```console
  100. $ hkpollution aqhi --station "mong kok"
  101. Station AQHI Risk Published
  102. -------- ---- -------- ----------------
  103. Mong Kok 4 Moderate 2026-11-21 17:30
  104. source: EPD Air Quality Health Index (fetched 2026-11-21T18:33:13+08:00)
  105. ```
  106. `--station` is a case-insensitive substring match, so `central` deliberately
  107. returns both stations it matches:
  108. ```console
  109. $ hkpollution aqhi --station central --json | jq -r '.stations[].station'
  110. Central/Western
  111. Central
  112. ```
  113. Hourly pollutant series — the newest three hours, with the window average:
  114. ```console
  115. $ hkpollution pollutants --station "mong kok" --hours 3
  116. Station Time NO2 O3 SO2 CO PM10 PM2.5
  117. -------- ---------------- ----- ---- --- ----- ---- -----
  118. Mong Kok 2026-11-21 16:00 102.6 31.2 6.1 557.9 25.7 15.1
  119. Mong Kok 2026-11-21 17:00 94.6 36.1 5.9 511.9 26.7 15.2
  120. Mong Kok 2026-11-21 18:00 97.0 34.2 5.7 475.8 22.2 11.8
  121. Mong Kok avg 3 98.1 33.8 5.9 515.2 24.9 14.0
  122. source: EPD 24-hour pollutant concentrations in µg/m³ (last build: Sat, 21 Nov 2026 18:30:00 +0800)
  123. ```
  124. A `-` in the table means the station does not measure that pollutant; in JSON
  125. the value is `null`, and the average key is omitted when every reading in the
  126. window is null.
  127. ### Exit codes
  128. | Exit | Meaning |
  129. | --- | --- |
  130. | `0` | Success |
  131. | `1` | Network, upstream or I/O failure — including a `--station` that matches nothing |
  132. | `2` | Usage error (unknown command or flag, bad `--hours`) |
  133. | `3` | `--fail-above` threshold reached — a finding, not a failure |
  134. Errors always go to stderr, so `--json` output stays pipeable.
  135. ```console
  136. $ hkpollution aqhi --station kownloon
  137. hkpollution: no station matches "kownloon"; valid stations: Central/Western, Southern, Eastern, Kwun Tong, Sham Shui Po, Kwai Chung, Tsuen Wan, Tseung Kwan O, Yuen Long, Tuen Mun, Tung Chung, Tai Po, Sha Tin, North, Tap Mun, Causeway Bay, Central, Mong Kok
  138. $ echo $?
  139. 1
  140. ```
  141. ## Forecast and street-level data
  142. Two more datasets come from the app APIs the mobile apps use rather than the
  143. open-data portal. Both are undocumented, so they are additive: the documented
  144. feeds stay the primary source for everything above, and a failure exits `1`
  145. like any other upstream error.
  146. ### Forecast
  147. `hkpollution forecast` shows the AQHI range the EPD forecasts for each
  148. period, for general and roadside stations separately:
  149. ```console
  150. $ hkpollution forecast
  151. Period General Roadside
  152. ------------- ------- --------
  153. Tomorrow A.M. 0-1 0-1
  154. Tomorrow P.M. 0-1 0-1
  155. source: EPD app API (fetched 2026-11-21T19:43:42+08:00) — EPD data © Government of the HKSAR
  156. ```
  157. ### Station history
  158. `hkpollution history` is the app-API counterpart of `pollutants`: one row per
  159. station by default, or the newest N hourly readings with `--station` and
  160. `--hours` (1-23), with the AQHI alongside the pollutants and the same `avg N`
  161. row as `pollutants`:
  162. ```console
  163. $ hkpollution history --station "mong kok" --hours 3
  164. Station Time AQHI NO2 O3 SO2 CO PM10 PM2.5
  165. -------- ---------------- ---- ---- ---- --- ----- ---- -----
  166. Mong Kok 2026-11-21 19:00 4 92.5 34.3 6.3 469.7 21.6 12.4
  167. Mong Kok 2026-11-21 18:00 4 97.0 34.2 5.7 475.8 22.2 11.8
  168. Mong Kok 2026-11-21 17:00 4 94.6 36.1 5.9 511.9 26.7 15.2
  169. Mong Kok avg 3 4.0 94.7 34.9 6.0 485.8 23.5 13.1
  170. source: EPD app API (fetched 2026-11-21T19:43:42+08:00) — EPD data © Government of the HKSAR
  171. ```
  172. ### Street level
  173. `hkpollution street --lat 22.33751 --lng 114.263` asks the PRAISE-HK model
  174. for one Hong Kong coordinate. The default `--hours 24` covers the current
  175. hour and the forecast, up to 48:
  176. ```console
  177. $ hkpollution street --lat 22.33751 --lng 114.263 --hours 3
  178. Time AQHI %AR NO2 O3 PM10 PM2.5 SO2
  179. ---------------- ---- --- ---- ----- ---- ----- ---
  180. 2026-11-21 19:00 4 6.3 12.8 103.9 16.1 10.1 4.7
  181. 2026-11-21 20:00 4 6.3 7.2 113.1 18.3 11.5 4.8
  182. 2026-11-21 21:00 4 6.6 3.4 120.6 20.4 13.2 4.8
  183. source: PRAISE-HK street-level model © HKUST Institute for the Environment (fetched 2026-11-21T19:44:04+08:00)
  184. ```
  185. `--lat` and `--lng` are required together and must lie inside Hong Kong
  186. (22.1-22.6 and 113.8-114.5); anything else is a usage error, exit `2`. `%AR`
  187. is the added health risk, and `-` is a value the model does not publish for
  188. that hour.
  189. ### One-call briefing
  190. `brief` answers the question people actually ask — "what is the air like where I am?"
  191. — with one request: the place name, the street-level model, the nearest official
  192. station and its distance, the weather, and the advice that applies.
  193. ```console
  194. $ hkpollution brief --lat 22.3375 --lng 114.263
  195. place: THE HONG KONG UNIVERSITY OF SCIENCE AND TECHNOLOGY (22.3375, 114.2630)
  196. street: AQHI 4 · added risk 6.1% · 2026-11-21 20:00
  197. station: Tseung Kwan O (2.2 km away) AQHI 4 · Moderate · 2026-11-21 19:30
  198. weather: 20.0 C · 45 % humidity · The Fire Danger Warning is Red and the fire risk is extreme.
  199. advice for Moderate (AQHI 4-6):
  200. general public No response action is required.
  201. heart and respiratory No response action is normally required. Individuals who are experiencing symptoms are advised to consider reducing outdoor physical exertion.
  202. source: EPD / PRAISE-HK / HKO (fetched 2026-11-21T20:53:52+08:00)
  203. ```
  204. Each part is fetched independently: if one upstream is down the report still comes
  205. back with `partial: true` and a `<part>_error` field, and the command only fails when
  206. both the street model and the station failed.
  207. ### Health advice
  208. `advice` prints EPD's own precautionary actions. The English table is compiled in from
  209. the AQHI website, so it works even when the app API is unreachable; `--lang tc` or
  210. `--lang both` adds the upstream Traditional Chinese text.
  211. ```console
  212. $ hkpollution advice --risk high
  213. High (AQHI 7)
  214. heart and respiratory People with existing heart or respiratory illnesses are advised to reduce outdoor physical exertion, and to reduce the time of their stay outdoors, especially in areas with heavy traffic. They should also seek advice from a medical doctor before participating in sport activities and take more breaks during physical activities.
  215. children and elderly Children and the elderly are advised to reduce outdoor physical exertion, and to reduce the time of their stay outdoors, especially in areas with heavy traffic.
  216. outdoor workers No response action is required.
  217. general public No response action is required.
  218. source: EPD health advice (fetched 2026-11-21T20:53:48+08:00)
  219. ```
  220. ### Beach water quality
  221. `beach` joins EPD's weekly grading feed to the department's yearly E. coli
  222. monitoring file. Each beach carries its grade and status, a WGS84 point, and
  223. the most recent published E. coli samples:
  224. ```console
  225. $ hkpollution beach --near 22.23,114.17 --grade graded | head -8
  226. DISTRICT BEACH GRADE STATUS DIST E. COLI SAMPLED
  227. ------------------ -------------------- -------------- ------ ------- ------- ----------
  228. Southern District Deep Water Bay Beach Grade 1 - Good open 2.4 km 2 2025-12-29
  229. Southern District Repulse Bay Beach Grade 1 - Good open 2.8 km 1 2025-12-02
  230. Southern District Middle Bay Beach Grade 1 - Good open 2.9 km 3 2025-12-02
  231. ```
  232. Grades follow the [EPD Beach Grading System](https://www.epd.gov.hk/epd/english/environmentinhk/water/beach_quality/grading_system.html):
  233. Good ≤ 24, Fair 25-180, Poor 181-610, Very Poor > 610 E. coli per 100 mL, on
  234. the geometric mean of the five most recent sampling occasions (a last reading
  235. above 1,600 also means Very Poor). The grading feed and the E. coli file move
  236. at different speeds — EPD publishes a year's monitoring file only after the
  237. year ends — so the report names the file it used in `ecoli_source` and an
  238. unreadable file degrades to `ecoli: null` with an `ecoli_error` instead of
  239. failing. Quote `latest_sampled_on` whenever you cite a count, and note EPD's
  240. advice against swimming for up to three days after a tropical cyclone or
  241. heavy rain.
  242. ### Beyond air
  243. Four more datasets answer questions air quality cannot:
  244. ```console
  245. $ hkpollution red-tide --days 365 --near 22.23,114.17
  246. REPORTED LOCATION SPECIES STATUS DISSIPATED DIST
  247. ---------- ------------------------------------ -------------------- ------ ---------- ----
  248. 2026-08-18 Repulse Bay Beach, Hong Kong Island Phaeocystis globosa 2026-08-19 2.9 km
  249. $ hkpollution radiation
  250. STATION µSv/H VS MEDIAN LEVEL TIME
  251. -------------- ----- --------- ------- -------------------------
  252. King's Park 0.15 1.36x typical 2026-11-22T01:00:00+08:00
  253. $ hkpollution river --zone "Deep Bay" --months 2
  254. ZONE RIVER STATION MONTH DO mg/L BOD5 mg/L
  255. -------- ---------------- ------- ------- ------- ---------
  256. Deep Bay River Ganges GR1 2026-10 6.0 19.0
  257. ```
  258. `river` and `marine` are **monthly monitoring**, not live: every row names its
  259. sampling month and the report names the newest one it holds. An `active` red
  260. tide is a sighting with no dissipation date yet. Radiation `elevated` means
  261. more than twice the network median, which is a data signal rather than a
  262. health threshold.
  263. `digest` runs the lot in one call and never fails: each source is a line, and a
  264. broken upstream becomes `unavailable: <reason>`.
  265. ```console
  266. $ hkpollution digest
  267. air worst AQHI 4 at Central/Western (Moderate), network mean 3.5
  268. beach 11 graded, 11 open, 32 not graded, E. coli 2025
  269. red tide no active sightings; 1 reported in the last 90 days
  270. radiation 11 stations, median 0.11 µSv/h, max 0.15 µSv/h at King's Park
  271. river 13 stations, newest sampling month 2026-10 (EPD monthly)
  272. uv index 0.0 (low), observed 2026-11-21T18:00:00+08:00
  273. weather no active warnings
  274. ```
  275. ### Recycling and watching
  276. `recycling` answers the street-level question — what is near me and what does it
  277. take — from EPD's collection-point list (9,700 points, 18 districts):
  278. ```console
  279. $ hkpollution recycling --lat 22.32 --lng 114.17 --type glass --limit 3
  280. POINT DISTRICT DIST ACCEPTS
  281. --------------------------------- ------------- ------ --------------------------
  282. Public pavement outside Chung Lee… Yau Tsim Mong 0.2 km Beverage Cartons, Glass …
  283. ```
  284. `watch` evaluates the alert thresholds once per interval. With `--once` it
  285. exits `3` when anything fires, so a cron job or supervisor can act on it:
  286. ```console
  287. $ hkpollution watch --once
  288. time: 2026-11-22T02:02:27+08:00 ok · AQHI 4 at Mong Kok
  289. $ hkpollution watch --aqhi 4 --red-tide --radiation --once
  290. time: … ALERT air: AQHI 4 at Mong Kok (Moderate) reached the threshold of 4
  291. exit status 3
  292. ```
  293. ### Statistics and comparison
  294. `stats` keeps a local observation log (one line per station-hour, 90 days) in
  295. the cache directory, topped up by the documented 24-hour AQHI feed, so a fresh
  296. install is already useful and coverage grows with every call. `compare` keeps
  297. general and roadside stations apart, because ranking a roadside kerb against a
  298. background station is not a fair comparison.
  299. ```console
  300. $ hkpollution compare | head -5
  301. STATION CATEGORY AQHI RISK VS CATEGORY
  302. --------------- -------- ---- -------- -----------
  303. Causeway Bay roadside 4 Moderate +0.0
  304. Central roadside 4 Moderate +0.0
  305. Central/Western general 4 Moderate +0.6
  306. ```
  307. ## Reliability
  308. Built for agents that call the same tool in a loop, and for cron jobs that need a
  309. verdict rather than prose.
  310. | Concern | Behaviour |
  311. | --- | --- |
  312. | Repeat calls | On-disk TTL cache in `~/.cache/hkpollution`: 5 min for current readings, 15 min for forecasts, 30 min for station history, 24 h for static pages. `--no-cache`, `--max-age <secs>`, `--refresh` |
  313. | Expired entries | Revalidated with `If-Modified-Since`; a `304` restarts the window without a rewrite, and a network failure serves the stale body instead of failing |
  314. | Flaky upstreams | Up to 3 attempts with 300 ms / 900 ms backoff for transport errors, 5xx and 429, honouring `Retry-After` |
  315. | Thresholds | `--fail-above 7` exits `3` when the worst AQHI reaches it, so `hkpollution aqhi --fail-above 7` is a monitoring check with no parsing |
  316. | Needing a station name | `--near 22.3375,114.263` resolves to the nearest of the 18 stations and prints the distance |
  317. | Drift and outages | `hkpollution doctor` probes all seventeen sources, reports latency, a schema check and the age of the newest data in each payload (flagging `stale`), and prints the cache location and size |
  318. | Tuning | `HKPOLLUTION_CACHE_DIR`, `HKPOLLUTION_TIMEOUT_SECS`, `HKPOLLUTION_RETRIES` |
  319. ```console
  320. $ hkpollution doctor
  321. SOURCE STATUS MS DETAIL
  322. ---------------------- ------ --- -----------
  323. data.gov.hk AQHI ok 103 1701 bytes
  324. aqhi.gov.hk RSS ok 40 7222 bytes
  325. aqhi.gov.hk 24pc ok 55 98211 bytes
  326. HKO rhrread ok 31 2951 bytes
  327. HKO fnd ok 33 4364 bytes
  328. EPD app forecast ok 63 699 bytes
  329. EPD app monitors ok 29 3960 bytes
  330. PRAISE weather ok 74 47 bytes, data 0.0 h old
  331. PRAISE pollutant_index ok 607 13111 bytes, data 0.0 h old
  332. EPD beach grading ok 530 11643 bytes
  333. EPD beach E. coli ok 335 54863 bytes
  334. EPD river water quality ok 262 19644 bytes
  335. EPD marine water quality ok 54 10798 bytes
  336. EPD 24-hour AQHI ok 47 62712 bytes, data 0.3 h old
  337. HKO UV index ok 34 56 bytes, data 0.3 h old
  338. HKO radiation ok 35 413 bytes, data 0.8 h old
  339. AFCD red tide ok 1216 266998 bytes, data 0.0 h old
  340. summary: 17 ok, 0 stale, 0 failed
  341. ```
  342. ## MCP server
  343. `hkpollution mcp` speaks JSON-RPC 2.0 over stdio — one JSON object per line,
  344. protocol revision `2025-06-18`, negotiated down to `2024-11-05` when a client
  345. asks for it. Every tool is annotated read-only and idempotent, declares an output
  346. schema, and returns `structuredContent` alongside the text payload, so clients can
  347. cache and auto-approve calls. Point any stdio-capable MCP client at the binary:
  348. ```json
  349. {
  350. "mcpServers": {
  351. "hongkong-pollution": {
  352. "command": "/absolute/path/to/hkpollution",
  353. "args": ["mcp"]
  354. }
  355. }
  356. }
  357. ```
  358. Register it with any MCP client:
  359. ```bash
  360. npx add-mcp "$(command -v hkpollution) mcp" --name hongkong-pollution -a claude-code -a codex -a cursor -y
  361. claude mcp add hongkong-pollution -- hkpollution mcp
  362. codex mcp add hongkong-pollution -- hkpollution mcp
  363. ```
  364. `add-mcp` detects the client configuration files in the current project; add
  365. `-g` for a global install. `$(command -v hkpollution)` keeps the entry correct
  366. when the binary is on `PATH`; substitute an absolute path if your client does
  367. not inherit the shell `PATH`.
  368. | Tool | Arguments | Returns |
  369. | --- | --- | --- |
  370. | `air_quality_aqhi` | `{ "station"?: string }` | Current AQHI per station, filtered when `station` is given |
  371. | `pollutant_concentrations` | `{ "station"?: string, "hours"?: integer 1-24 }` | Latest reading plus the hourly series, per station |
  372. | `pollution_summary` | `{ "include_weather"?: boolean }` | The CLI `summary` payload |
  373. | `hong_kong_weather` | `{}` | The CLI `weather` payload |
  374. | `air_quality_briefing` | `{ "lat": number, "lng": number, "no_cache"?: boolean }` | The CLI `brief` payload |
  375. | `health_advice` | `{ "risk"?: string, "lang"?: "en"\|"tc"\|"both" }` | The CLI `advice` payload |
  376. | `source_health` | `{}` | The CLI `doctor` payload |
  377. | `aqhi_forecast` | `{}` | The CLI `forecast` payload |
  378. | `station_history` | `{ "station"?: string, "hours"?: integer 1-23 }` | Hourly AQHI and pollutant history per station, newest first |
  379. | `street_level_aqhi` | `{ "lat": number, "lng": number, "hours"?: integer 1-48 }` | The CLI `street` payload |
  380. Every result is `{"content":[{"type":"text","text":"<pretty JSON>"}],"isError":false}`.
  381. An upstream failure returns `isError: true` with a readable message instead of
  382. a transport error, so the session survives an outage.
  383. This is a **stdio-only** server: it listens on no port and has no network
  384. authentication layer, so there is no API-key setting. Optional keys in this
  385. project family apply only to HTTP MCP transports. For a container, keep stdin
  386. attached (`docker run --rm -i hkpollution mcp`) and let the MCP client launch
  387. and stop the process. There is no Worker/WASM deployment; the binary uses
  388. `ureq` plus an on-disk cache and is packaged as a CLI/stdio server.
  389. ```console
  390. $ printf '%s\n' \
  391. '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  392. '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  393. '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  394. | hkpollution mcp
  395. {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"hongkong-pollution-skill","version":"0.3.0"}}}
  396. {"jsonrpc":"2.0","id":2,"result":{"tools":[ ... ]}}
  397. ```
  398. Unknown methods answer `-32601`, unparsable lines answer `-32700`, and the
  399. server keeps serving until stdin closes.
  400. ## Data sources
  401. | Source | Endpoint | Used for |
  402. | --- | --- | --- |
  403. | EPD AQHI dashboard (JSON) | `https://dashboard.data.gov.hk/api/aqhi-individual?format=json` | Primary current AQHI per station |
  404. | EPD AQHI (RSS) | `https://www.aqhi.gov.hk/epd/ddata/html/out/aqhi_ind_rss_Eng.xml` | Fallback when the JSON host fails |
  405. | EPD 24-hour pollutant concentrations (XML) | `https://www.aqhi.gov.hk/epd/ddata/html/out/24pc_Eng.xml` | Hourly NO2/O3/SO2/CO/PM10/PM2.5, µg/m³ |
  406. | HKO current readings (JSON) | `https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=rhrread&lang=en` | Temperature, humidity, warnings |
  407. | EPD app API (JSON, undocumented) | `https://app.epd-asmg.gov.hk/api/v2/forecast`, `https://app.epd-asmg.gov.hk/api/v2/monitors` | Tomorrow's AQHI range, hourly per-station history |
  408. | HKO nine-day forecast (JSON) | `https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=fnd&lang=en` | `weather --forecast` |
  409. | PRAISE-HK model API (JSON, undocumented) | `https://praise-web.ust.hk:8443/api/pollutant_index` | Street-level AQHI, added health risk and pollutants at a coordinate |
  410. | PRAISE-HK reverse geocoding | `https://praise-web.ust.hk:8443/location/reverse_geocoding` | Place names in `brief` |
  411. | PRAISE-HK spatial tiles | `https://praise-web.ust.hk:8443/api/pollutant_spatial_tiles` | Raster tile links in `map` |
  412. | EPD beach grading (GeoJSON) | `https://cd.epic.epd.gov.hk/EPICDI/json/beach/beachgrading?lang=en` | Grade, status, district and a WGS84 point per gazetted beach |
  413. | EPD beach E. coli monitoring (CSV, yearly) | `https://cd.epic.epd.gov.hk/beachpsi/en/beach-historical-data-<year>-en.csv` | E. coli count per 100 mL per sampling date, from the latest complete year |
  414. | EPD recent river water quality (CSV) | `https://cd.epic.epd.gov.hk/riverpsi/en/riverrecent/river-recent-en.csv` | Monthly dissolved oxygen and BOD5 per river station |
  415. | EPD recent marine water quality (CSV) | `https://cd.epic.epd.gov.hk/marinepsi/en/marinerecent/marine-recent-en.csv` | Monthly dissolved oxygen and BOD5 per marine station |
  416. | EPD past 24-hour AQHI (XML, documented) | `https://www.aqhi.gov.hk/epd/ddata/html/out/24aqhi_Eng.xml` | `history` fallback and the first run of `stats` |
  417. | AFCD red tide sightings (CSV) | `https://redtide.afcd.gov.hk/data/RTMS_ob_RTLE.csv` | Active and recent red tides with coordinates |
  418. | HKO ambient gamma radiation (CSV) | `https://data.weather.gov.hk/weatherAPI/hko_data/regional-weather/latest_hourly_rmn.csv` | Hourly mean dose rate per station, µSv/h |
  419. | HKO UV index (CSV) | `https://data.weather.gov.hk/weatherAPI/hko_data/regional-weather/latest_15min_uvindex.csv` | 15-minute mean UV index |
  420. | Waste Reduction and Recycling collection points (CSV) | `https://www.wastereduction.gov.hk/sites/default/files/wasteless.csv` | Coordinates, accepted waste types and opening hours per point |
  421. A `source` of `EPD app API` or `PRAISE-HK` marks a report from one of those
  422. undocumented app APIs; `EPD` and `HKO` keep their existing meaning.
  423. The 18 AQHI stations are Central/Western, Southern, Eastern, Kwun Tong, Sham
  424. Shui Po, Kwai Chung, Tsuen Wan, Tseung Kwan O, Yuen Long, Tuen Mun, Tung
  425. Chung, Tai Po, Sha Tin, North, Tap Mun, Causeway Bay, Central and Mong Kok —
  426. the last three are roadside stations.
  427. > **Attribution.** Data is published by the Government of the Hong Kong SAR:
  428. > the [Environmental Protection Department](https://www.aqhi.gov.hk/) (AQHI,
  429. > pollutant concentrations, forecast and station history) and the
  430. > [Hong Kong Observatory](https://www.hko.gov.hk/) (weather readings). The
  431. > street-level model is the PRAISE-HK project of the HKUST Institute for the
  432. > Environment. Keep their attribution when you redistribute the data.
  433. <details>
  434. <summary><strong>JSON shapes</strong></summary>
  435. `hkpollution aqhi --json`:
  436. ```json
  437. {"stations":[{"station":"Central/Western","aqhi":4,"health_risk":"Moderate","publish_date":"2026-11-21T17:30:00"}],"source":"EPD","fetched_at":"2026-11-21T18:05:00+08:00"}
  438. ```
  439. `hkpollution pollutants --json`:
  440. ```json
  441. {"last_build_date":"Sat, 21 Nov 2026 17:30:00 +0800","hours":24,
  442. "stations":[{"station":"Central/Western",
  443. "latest":{"time":"2026-11-20T18:00:00+08:00","no2":47.8,"o3":45.6,"so2":1.0,"co":null,"pm10":14.7,"pm25":10.8},
  444. "series":[{"time":"2026-11-20T18:00:00+08:00","no2":47.8,"o3":45.6,"so2":1.0,"co":null,"pm10":14.7,"pm25":10.8}],
  445. "averages":{"no2":41.2,"pm25":9.4}}],"source":"EPD"}
  446. ```
  447. `hkpollution weather --json`:
  448. ```json
  449. {"update_time":"2026-11-21T18:02:00+08:00",
  450. "temperature":[{"place":"Hong Kong Observatory","value":20.0,"unit":"C"}],
  451. "humidity":[{"place":"Hong Kong Observatory","value":47,"unit":"percent"}],
  452. "warnings":["The Fire Danger Warning is Red and the fire risk is extreme."],
  453. "source":"HKO"}
  454. ```
  455. `hkpollution summary --json` adds the rollup to the AQHI stations, plus
  456. `worst`, `mean_aqhi`, `risk_counts`, `worst_pm25`, `worst_no2` and — only with
  457. `--with-weather` — `weather`:
  458. ```json
  459. {"fetched_at":"2026-11-21T18:33:13+08:00","stations":[...],
  460. "worst":{"station":"Central/Western","aqhi":4,"health_risk":"Moderate","publish_date":"2026-11-21T17:30:00"},
  461. "mean_aqhi":3.9,"risk_counts":{"Low":1,"Moderate":17},
  462. "worst_pm25":{"station":"Causeway Bay","value":19.6,"time":"2026-11-21T18:00:00+08:00"},
  463. "worst_no2":{"station":"Causeway Bay","value":102.6,"time":"2026-11-21T18:00:00+08:00"},
  464. "source":"EPD"}
  465. ```
  466. `hkpollution forecast --json`:
  467. ```json
  468. {"periods":[{"period":"Tomorrow A.M.","general":{"min":0,"max":1},"roadside":{"min":0,"max":1}},{"period":"Tomorrow P.M.","general":{"min":0,"max":1},"roadside":{"min":0,"max":1}}],"source":"EPD app API","fetched_at":"2026-11-21T19:43:42+08:00"}
  469. ```
  470. `hkpollution history --json` — newest first, and `series` always carries the
  471. full upstream window (23 hours) while `hours` trims only the table:
  472. ```json
  473. {"hours":2,"stations":[{"station":"Mong Kok","station_id":81,"category":"roadside","latitude":22.322584,"longitude":114.168297,
  474. "latest":{"time":"2026-11-21T19:00:00+08:00","aqhi":4,"no2":92.5,"o3":34.3,"so2":6.3,"co":469.7,"pm10":21.6,"pm25":12.4},
  475. "series":[{"time":"2026-11-21T19:00:00+08:00","aqhi":4,"no2":92.5,"o3":34.3,"so2":6.3,"co":469.7,"pm10":21.6,"pm25":12.4},
  476. {"time":"2026-11-21T18:00:00+08:00","aqhi":4,"no2":97.0,"o3":34.2,"so2":5.7,"co":475.8,"pm10":22.2,"pm25":11.8}, ...]}],
  477. "source":"EPD app API","fetched_at":"2026-11-21T19:44:05+08:00"}
  478. ```
  479. `hkpollution street --json`:
  480. ```json
  481. {"location":{"lat":22.33751,"lng":114.263},
  482. "current":{"time":"2026-11-21T19:00+08:00","aqhi":4,"added_health_risk":6.3,"no2":12.8,"o3":103.9,"pm10":16.1,"pm25":10.1,"so2":4.7},
  483. "series":[{"time":"2026-11-21T19:00+08:00",...},{"time":"2026-11-21T20:00+08:00",...}],
  484. "source":"PRAISE-HK","fetched_at":"2026-11-21T19:44:05+08:00"}
  485. ```
  486. `hkpollution beach --json`:
  487. ```json
  488. {"source":"https://cd.epic.epd.gov.hk/EPICDI/json/beach/beachgrading?lang=en",
  489. "count":1,"graded":1,"open":1,
  490. "ecoli_source":"https://cd.epic.epd.gov.hk/beachpsi/en/beach-historical-data-2025-en.csv",
  491. "ecoli_error":null,
  492. "beaches":[{"name":"Silver Mine Bay Beach","district":"Islands District","grade":1,
  493. "grade_name":"Grade 1 - Good","status":"open","description":"Grade 1 - Good",
  494. "code":"sil","latitude":22.270278,"longitude":113.998889,"distance_km":null,
  495. "ecoli":{"latest_sampled_on":"2025-12-04","latest_per_100ml":140,
  496. "geometric_mean_per_100ml":29.6,"samples":160,
  497. "recent":[{"sampled_on":"2025-12-04","per_100ml":140},{"sampled_on":"2025-11-24","per_100ml":14}, ...]}}]}
  498. ```
  499. Timestamps are ISO-8601 in Hong Kong time; concentrations are µg/m³ and beach
  500. E. coli counts are per 100 mL.
  501. </details>
  502. ## Development
  503. A `justfile` holds the everyday commands (`brew install just` if you need it):
  504. | Recipe | Does |
  505. | --- | --- |
  506. | `just` | `just check` — fmt check, clippy with `-D warnings`, tests |
  507. | `just build-release` | Optimised binary at `target/release/hkpollution` |
  508. | `just run aqhi --json` | Run the CLI, arguments passed through cargo |
  509. | `just audit` | `cargo audit` against the lockfile |
  510. | `just skill-check` | Validate `SKILL.md` and shell syntax the way CI does |
  511. | `just version` | Print the release tag for the current `Cargo.toml` version |
  512. | `just release 0.4.0` | Tag and push; the release workflow does the rest |
  513. Layout:
  514. | Path | Contents |
  515. | --- | --- |
  516. | `src/parse.rs` | Pure parsers for AQHI JSON/RSS, the 24-hour XML, HKO JSON and the app APIs |
  517. | `src/model.rs` | Serialised payload types, station lookup, AQHI rollup |
  518. | `src/http.rs` | `ureq` GET with 10 s connect / 20 s read timeouts and a User-Agent |
  519. | `src/aqhi.rs` | AQHI fetch with RSS fallback, and the `summary` payload |
  520. | `src/pollutants.rs` | Pollutant fetch, `--hours` windowing, averages, extremes |
  521. | `src/weather.rs` | HKO fetch |
  522. | `src/epd_app.rs` | EPD app API forecast and per-station history |
  523. | `src/praise.rs` | PRAISE-HK street-level fetch and Hong Kong bounds validation |
  524. | `src/mcp.rs` | JSON-RPC 2.0 stdio server and the MCP tools |
  525. | `src/main.rs` | CLI: argument parsing, tables, JSON output |
  526. | `SKILL.md` | The agent-skill manifest: what the CLI reports and how to call it |
  527. | `scripts/install.sh` | Release downloader with checksum verification and a cargo fallback |
  528. | `scripts/ensure-binary.sh` | Resolves or builds a usable binary for the agent skill |
  529. The test suite is offline: every parser test reads `tests/fixtures/*`, and the
  530. MCP test drives the real binary over stdio. Decisions the spec left open are
  531. recorded in [`NOTES.md`](NOTES.md).
  532. ## Releasing
  533. ```sh
  534. just release 0.4.0
  535. ```
  536. That creates and pushes the annotated tag `v0.4.0`;
  537. [`.github/workflows/release.yml`](.github/workflows/release.yml) then checks the
  538. tag against `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests
  539. the native ones, and publishes a GitHub release:
  540. | Asset | Target |
  541. | --- | --- |
  542. | `hkpollution-v0.4.0-aarch64-apple-darwin.tar.gz` | macOS, Apple silicon |
  543. | `hkpollution-v0.4.0-x86_64-apple-darwin.tar.gz` | macOS, Intel |
  544. | `hkpollution-v0.4.0-x86_64-unknown-linux-musl.tar.gz` | Linux, x86_64 (static) |
  545. | `hkpollution-v0.4.0-aarch64-unknown-linux-musl.tar.gz` | Linux, aarch64 (static) |
  546. | `SHA256SUMS` | Checksums for every tarball |
  547. The same run also publishes `ghcr.io/hongkong-ai-labs/hkpollution:<tag>` and
  548. `:latest` (multi-arch, from the static musl builds) and, when a `BREW_TOKEN`
  549. secret with repo scope exists, regenerates `Formula/hkpollution.rb` in
  550. `hongkong-ai-labs/homebrew-tap` from the two macOS sha256s.
  551. `scripts/install.sh` reads the latest release, so re-running the one-liner
  552. upgrades an installed binary and leaves an up-to-date one alone. Installed
  553. skills update with `npx skills update`.
  554. ### Drift detection
  555. Both app APIs are undocumented, so a nightly job runs every command against the
  556. live sources, compares the top-level payload keys with `tests/schema/*.json`,
  557. runs `doctor`, and opens (or updates) a single `drift` issue when something moved.
  558. Locally the same check is `./scripts/check-drift.sh`, with `--update` to re-record
  559. the snapshots after an intentional change.
  560. ## License
  561. MIT © [hongkong-ai-labs](https://github.com/hongkong-ai-labs). See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.