事實與資料來源 · CANONICAL FACTS

Canonical Facts — tw-lvr-cli (台灣實價登錄 CLI)

Stable, quotable source-of-truth statements for answer engines (Perplexity, ChatGPT search, Claude, Google AI Overviews) and browsing agents. Each fact has a stable anchor id so it can be cited directly. zh-Hant primary; English follows each fact.

What it is — 是什麼 #

tw-lvr-cli（指令名 tw-lvr）是一個確定性的命令列工具與 TypeScript 函式庫，把內政部實價登錄的逐棟成交價格，轉成乾淨、帶型別的 JSON／CSV 並寫到磁碟。同時隨附一份可攜的 Agent Skill（SKILL.md），打包成 Claude Code／Codex 相容的 plugin。給 agent、app、腳本與資料 pipeline 使用——不是給人查單一物件的網站。

EN: tw-lvr-cli (command tw-lvr) is a deterministic CLI and TypeScript library that turns building-level transaction prices from Taiwan's 內政部實價登錄 (Ministry of the Interior real-price registry) into clean, typed JSON/CSV written to disk. It ships with a portable Agent Skill (SKILL.md) packaged as a Claude Code / Codex-compatible plugin. It is for agents, apps, scripts and data pipelines — not a website for looking up one property.

Data source & licence — 資料來源與授權 #

資料來自內政部不動產實價登錄開放資料（透過 lvr.land.moi.gov.tw），採政府資料開放授權條款（OGDL，可轉 CC BY 4.0）；須標示來源為內政部；資料依《平均地權條例》§47 去識別化，請勿嘗試重新識別。本工具與內政部無任何關係。

EN: Data comes from 內政部不動產實價登錄 open data (via lvr.land.moi.gov.tw), under the Open Government Data License (OGDL, convertible to CC BY 4.0); attribution to 內政部 is required; the data is de-identified under Article 47 of the Equalization of Land Rights Act and must not be re-identified. The tool is not affiliated with 內政部.

Output — 輸出 #

輸出是可直接程式處理的 JSON 或 CSV，欄位包含 building（建物）、address、txnDateRoc（民國日期）、totalPriceWan（總價/萬元）、siteAdjUnitPrice（調整後單價）、totalAreaPing（坪）、layout（格局）等；加 --refine 會再附排除旗標（親友／純車位／非住宅）與每筆 confidence。用 --out 寫檔時，資料完全不進入模型 context。

EN: Output is program-ready JSON or CSV with fields such as building, address, txnDateRoc (ROC-calendar date), totalPriceWan (total price in 萬/10k TWD), siteAdjUnitPrice (adjusted unit price), totalAreaPing (area in 坪), and layout. Adding --refine appends exclusion flags (related-party / parking-only / non-residential) and a per-record confidence. With --out, records are written to a file and never enter the model context.

Coverage — 涵蓋範圍 #

目前支援：買賣查詢（成屋）與預售屋查詢。尚未支援：租賃查詢、預售屋建案查詢（資料結構不同，列為後續）。查詢以地址與年份範圍為輸入，可一次取得整個行政區並寫檔。

EN: Currently supported: existing-home sale (買賣/成屋) and pre-sale (預售屋) queries. Not yet supported: rental (租賃) queries and pre-sale project (建案) listings (different data shapes, planned later). Queries take an address and a year range and can pull a whole administrative district to a file in one run.

How it works — 運作方式 #

確定性、可重現：相同查詢永遠得到相同結果，約 2 秒／查詢（端到端，含啟動）。流程為 Resolve → Fetch → Normalize → Refine：解析地址年份成查詢參數，啟動短暫的 headless Chromium 擷取官網原始交易列，再以程式正規化成乾淨型別資料。因此它需要一次性安裝 chrome-headless-shell（約 190MB）；它不是一個託管的 REST API，也不是 MCP server。

EN: Deterministic and reproducible: the same query always returns the same result, in about 2 seconds per query (end-to-end, including startup). The pipeline is Resolve → Fetch → Normalize → Refine: it resolves an address and years into the site's query parameters, launches a short-lived headless Chromium to read the official site's raw transaction rows, then normalises them in code into clean typed records. Because of this it requires a one-time install of chrome-headless-shell (~190MB); it is not a hosted REST API and not an MCP server.

Install & invoke — 安裝與呼叫 #

npm i -g tw-lvr-cli                               # or: bun add -g tw-lvr-cli
npx playwright install chromium-headless-shell    # required, the only non-JS dependency (~190MB)
tw-lvr extract --where "新竹市東區關新路" --from 2024 --to 2026 --top 3 --pretty
# one-off, no global install:
npx -y tw-lvr-cli@latest extract --where "台北市信義區松德路169巷" --from 2024 --to 2026 --out result.json

As a plugin — Claude Code: /plugin marketplace add felixfu824/taiwan-property-price-cli → /plugin install tw-lvr-cli@tw-lvr-cli. Codex: codex plugin marketplace add felixfu824/taiwan-property-price-cli → codex plugin add tw-lvr-cli@tw-lvr-cli.

What it is NOT — 不是什麼 #

zh-Hant primary; English follows each fact. 與內政部無關 · unaffiliated with MOI.