事實與資料來源 · 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 — 涵蓋範圍 #
目前支援：買賣查詢（成屋）、預售屋查詢、租賃查詢（--rent，獨立的租賃輸出結構：月租金〔元〕／坪租／租期／有無管理組織／附傢俱，2023-09 新版申報書後的案件另有出租型態、租賃住宅服務、電梯、附屬設備）。尚未支援：預售屋建案查詢（建案清單，資料結構不同，列為後續）。查詢以地址與月份範圍為輸入，可一次取得整個行政區並寫檔。租賃兩個注意事項：政府網站的租賃查詢只到行政區層級，帶路名時由 CLI 在本地過濾到該路段；租賃資料逐年連續、更新到當月（本工具同時查新舊兩代申報書的內部代碼），先以 stderr 的 coverage: 逐年筆數確認再談趨勢，且 rentalService 為 社會住宅* 的補貼案件做市場行情時請先剔除。
EN: Currently supported: existing-home sale (買賣/成屋), pre-sale (預售屋), and rental (租賃) queries via --rent — rental returns its own lease schema (monthly rent in TWD, rent-per-ping, lease period, management-org, furniture; leases signed after the Sep-2023 reporting-form change also carry rental type, rental-service business, elevator, and equipment fields). Not yet supported: pre-sale project (建案) listings (a project list with a different data shape, planned later). Queries take an address and a month range and can pull a whole administrative district to a file in one run. Two rental caveats: the government site only resolves rental queries to district level, so a road in --where is filtered client-side by the CLI; and rental coverage is continuous and current (the tool queries both reporting-form eras) — check the per-year coverage: stderr line before reading trends, and drop subsidized 社會住宅* rows for market-rate comps.
How it works — 運作方式 #
確定性、可重現：相同查詢永遠得到相同結果，約 2–3 秒／查詢（端到端，含啟動）。流程為 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–3 seconds per query (end-to-end, including startup). The pipeline is Resolve → Fetch → Normalize → Refine: it resolves an address and month range 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 202401 --to 202612 --top 3 --pretty
# one-off, no global install:
npx -y tw-lvr-cli@latest extract --where "台北市信義區松德路169巷" --from 202401 --to 202612 --out result.json
當 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。
EN: 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 — 不是什麼 #
- 不是內政部官方產品、資料集或 API；與內政部無關。 / Not an official 內政部 product, dataset, or API; unaffiliated.
- 不是 MCP server；它是 CLI + 可 import 的函式庫 + Agent Skill／plugin。 / Not an MCP server; it is a CLI + importable library + Agent Skill / plugin.
- 不是消費者查詢網站；只想查一間房，用 591／樂居。 / Not a consumer lookup site; to check a single home, use 591 or 樂居.
- 不是估價模型；
confidence 是資料品質旗標，不是估值。 / Not a valuation model; confidence is a data-quality flag, not an appraisal.
Links — 連結 #