安裝 Install

Install 安裝

用 npm 或 bun 全域安裝。安裝後另需執行一次 Playwright 的 headless Chromium 下載——這是唯一的非 JavaScript 相依套件。

Install globally with npm or bun. After installing, run Playwright's headless Chromium download once — this is the only non-JavaScript dependency.

$ npm i -g tw-lvr-cli
# 或使用 bun · or use bun
$ bun add -g tw-lvr-cli

$ npx playwright install chromium-headless-shell

不想全域安裝？單次執行

No global install? One-off run

$ npx -y tw-lvr-cli@latest extract --where "新竹市東區關新路" --from 202401 --to 202612 --top 3 --pretty

快速開始 Quick start

Quick start 快速開始

指定地址、月份範圍與筆數即可取得結果。--pretty 會輸出排版過的 JSON。

Pass an address, a month range and a count to get results. --pretty prints formatted JSON.

$ tw-lvr extract --where "新竹市東區關新路" --from 202401 --to 202612 --top 3 --pretty

$ tw-lvr extract --where "新竹市東區關新路" --from 202401 --to 202612 --out result.json
# → result.json · 資料留在磁碟，不進 context · data stays on disk, out of context

指令與參數 Commands & flags

Commands & flags 指令與參數

主要指令是 extract，完整簽章如下：

The main command is extract. Full signature:

tw-lvr extract --where <地址> --from <YYYYMM> --to <YYYYMM>
       [--refine] [--ptype 1,2] [--query biz|sale|rent | --presale | --rent]
       [--top N | --limit N] [--community <社區名>]
       [--out <檔案|資料夾>] [--format json|csv] [--pretty]

參數說明

Flag reference

其他指令

Other commands

$ tw-lvr glossary     # 列出完整欄位與詞彙表 · full field glossary
$ tw-lvr --help       # 指令說明 · command help
$ tw-lvr --version    # 版本 · version

輸出欄位 Output fields

Output fields 輸出欄位

每筆交易的核心欄位如下。完整欄位清單請執行 tw-lvr glossary。

Core fields per transaction below. For the full list, run tw-lvr glossary.

結束代碼 Exit codes

Exit codes 結束代碼

指令以下列結束代碼退出，方便在腳本與 CI 中判斷。

The command exits with these codes, for branching in scripts and CI.

架構 Architecture

Architecture 架構

每次查詢經過四個階段。

Each query passes through four stages.

Library API 當函式庫使用

Library API use as a library

同一個引擎可以直接 import。匯出 extract 與 extractRefined，型別定義在 src/index.ts。

The same engine is importable. It exports extract and extractRefined; types live in src/index.ts.

import { extract, extractRefined } from 'tw-lvr-cli';
import type { CleanRawRecord } from 'tw-lvr-cli';

const res = await extract({
  where: '新竹市東區關新路',
  from: '202401', to: '202612',
});
const records: CleanRawRecord[] = res.data ?? [];

// extract returns Result; records live in res.data／extract 回傳 Result；資料在 res.data
console.log(records[0]?.totalPriceWan);

// Use extractRefined() for adjusted prices and flags／需要調整後單價與旗標時，改用 extractRefined()

首次查詢會啟動一個可重用的 headless 瀏覽器；閒置 15 秒後自動關閉，腳本會自行結束（LVR_BROWSER_IDLE_MS 可調）。要立即結束、或在常駐程式中自行控制關閉時機，呼叫 closeBrowser()。

The first query launches one reusable headless browser; it closes itself after 15 seconds idle, so plain scripts exit on their own (tune with LVR_BROWSER_IDLE_MS). For immediate exit, or to own the shutdown in long-lived processes, call closeBrowser().

當 plugin 用 Use as a plugin

Use as a plugin 當 plugin 用

可安裝進 Claude Code 與 Codex，讓 agent 直接呼叫 CLI。

Install into Claude Code and Codex so an agent can call the CLI directly.

/plugin marketplace add felixfu824/taiwan-property-price-cli
/plugin install tw-lvr-cli@tw-lvr-cli

$ codex plugin marketplace add felixfu824/taiwan-property-price-cli
$ codex plugin add tw-lvr-cli@tw-lvr-cli

給 AI agent For AI agents

For AI agents 給 AI agent

agent 應該把 tw-lvr 當成 shell 指令執行，並從 --out 指定的檔案讀取 JSON／CSV，而不是把資料讀進 context。結果是確定性的，每次查詢約 2–3 秒。

An agent should run tw-lvr as a shell command and read the JSON／CSV from the --out file, instead of pulling it into context. Results are deterministic, about 2–3s per query.

本站也提供機器可讀的參考檔：/llms.txt 與 /facts/。

The site also serves machine-readable references: /llms.txt and /facts/.

資料與授權 Data & license

Data & license 資料與授權

資料來源為內政部不動產實價登錄開放資料，採政府資料開放授權條款（OGDL，可轉 CC BY 4.0），須標示來源為內政部，資料依法去識別化。程式碼以 Apache-2.0 授權。

Data comes from the MOI real-price registry open data under the Open Government Data License (OGDL, convertible to CC BY 4.0); the source must be attributed to MOI and the data is de-identified by law. The code is licensed Apache-2.0.

隱私

Privacy

• 本機執行，無 telemetry，不蒐集個資。
• Runs locally, no telemetry, collects no personal data.
• 僅寫入 --out 指定的路徑。
• Writes only to the path given in --out.
• 對外請求僅限 lvr.land.moi.gov.tw。
• Outbound requests are limited to lvr.land.moi.gov.tw.

疑難排解 Troubleshooting

Troubleshooting 疑難排解