---
reviewed_by:
  rd: tmonk
  pm:
---
# 實價登錄（土地附表）— `tw.gov.moi.land~ref~plvr-land`

> **給 AI 閱讀的使用指引。**
> 人類可在 https://data.openfun.tw/datasets/tw.gov.moi.land~ref~plvr-land 看到同份內容的網頁版。
> 詳細資料知識見 [knowledge.md](knowledge.md)。

---

## ⚠️ 開始之前（AI agent 必讀，摘要也請保留這段）

資料集 slug：tw.gov.moi.land~ref~plvr-land
API 端點：https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/records
認證方式（必填）：HTTP Header  Authorization: Bearer {token}

最簡查詢範例：curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/records?per_page=20"

**Token 是必要條件，沒有 Token 就無法查資料。**
如果使用者沒有 Token，請停止並告訴使用者：「請先前往 https://data.openfun.tw/user 免費申請帳號與 API Token，取得後告訴我，我再幫您查詢。」

禁止抓取 HTML 頁面（本平台有 bot 保護，WebFetch 讀 HTML 頁面會失敗）。

授權標注：使用此資料產出的內容需標注「資料來源：歐噴資料庫（data.openfun.tw）／行政院內政部地政司」

---

## 這份資料集能回答什麼問題

以下問題，這份資料集**可以回答**：

- 「這筆交易（編號 XXXXX）包含哪些地號？各地號面積是多少？」
- 「這筆交易的土地使用分區是什麼？」
- 「這個地號（如 03160000）最近有哪些交易？」
- 「這筆交易中，買方取得的土地持分是多少？」

以下問題，這份資料集**無法回答**：

- 「這塊土地賣了多少錢？」（金額在主表 `tw.gov.moi.land~ref~plvr`，不在本表）
- 「台北市住宅用地的交易量？」（本表無縣市欄位，需 JOIN 主表）
- 「土地的地主是誰？」（實價登錄不揭露交易雙方身分）

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 行政院內政部地政司（[實價登錄開放資料下載](https://plvr.land.moi.gov.tw/DownloadOpenData)） |
| 授權 | 政府資料開放授權條款－第1版 |
| 更新頻率 | 每週更新 |
| 總筆數 | 約 970 萬筆（2026-05-28） |

---

## 關聯主表的方式

本資料集為主表 `tw.gov.moi.land~ref~plvr` 的**一對多附表**。

- 主表的 `編號` = 本表的 `編號`
- 本表的 `id` = `{編號}-{序號}`，例如 `RPQQMLKMKIJFFEF97CA-1`
- 查詢流程：先用主表取得目標交易的 `編號`，再用 `?編號=XXXXX` 查本表取土地明細

---

## 欄位說明

> `filter: true` 的欄位支援精確篩選（`?欄位名稱=值`）。

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `id` | keyword（_id） | 實價登錄交易編號 + 序號 |
| `編號` | keyword（ref: tw.gov.moi.land~ref~plvr） | 對應實價登錄交易編號 |
| `土地位置` | keyword |  |
| `土地移轉面積平方公尺` | number |  |
| `使用分區或編定` | keyword（篩選器、多值） |  |
| `權利人持分分母` | number |  |
| `權利人持分分子` | number |  |
| `移轉情形` | keyword（篩選器） |  |
| `地號` | text（_name） |  |

| 欄位名稱 | 型別 | filter | 說明 |
|---------|------|--------|------|
| `id` | keyword | — | 唯一識別碼，格式 `{編號}-{序號}` |
| `編號` | keyword | — | 對應主表（`tw.gov.moi.land~ref~plvr`）的 `編號` 欄位 |
| `土地位置` | keyword | — | 地段名稱，例如 `新興段`、`天生段`（不含縣市） |
| `地號` | text | — | 地號（可全文搜尋，即 `_name` 欄位） |
| `土地移轉面積平方公尺` | number | — | 本筆地號移轉面積（㎡） |
| `使用分區或編定` | keyword（多值） | ✅ | 土地使用分區，例如 `都市：住`、`非都市編定：農牧用地`（多值陣列） |
| `權利人持分分子` | number | — | 持分分子 |
| `權利人持分分母` | number | — | 持分分母 |
| `移轉情形` | keyword | ✅ | `全筆移轉`、`持分移轉`、空字串（約 4.6% 為空） |

---

## API 呼叫範例

**Records URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/records`

### 範例 1：查詢某筆交易的所有土地明細

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/records?編號=RPQQMLKMKIJFFEF97CA"
```

用途：取得特定交易的所有地號記錄。`編號` 從主表取得。

---

### 範例 2：依使用分區篩選

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/records?使用分區或編定=都市：住&per_page=20"
```

用途：篩選都市住宅區的土地記錄。建議先用 `/agg?group_by=使用分區或編定` 確認目標值的確切字串。

---

### 範例 3：依地號搜尋

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/records?q=03160000"
```

用途：搜尋特定地號的交易記錄。`q=` 對 `地號`（text 欄位）進行全文搜尋。

---

### 範例 4：篩選全筆移轉

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/records?移轉情形=全筆移轉&per_page=20"
```

---

### 分頁查詢

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/records?page=2&per_page=50"
```

回應中 `"total"` 欄位是符合條件的總筆數。

---

## 統計聚合（/agg 端點）

**Agg URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/agg`

可分組的欄位：`使用分區或編定`、`移轉情形`

### 各使用分區筆數分布

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/agg?group_by=使用分區或編定"
```

### 各移轉情形筆數分布

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/agg?group_by=移轉情形"
```

---

## 注意事項與限制

1. **本表無縣市欄位**：無法單獨依縣市篩選，需搭配主表 JOIN 使用。
2. **`使用分區或編定` 為多值陣列**：一筆記錄的此欄位為 JSON 陣列（即使通常只有一個值），`?使用分區或編定=都市：住` 可正常篩選。
3. **使用分區值多樣**：同類分區有多種寫法，建議先用 agg 確認精確值再篩選。
4. **`土地移轉面積平方公尺` 為持分後面積**：持分移轉案件此面積已是持分計算後的移轉面積，非地號登記總面積。
5. **面積單位為平方公尺（㎡）**：換算坪數請除以 3.3058。

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| `tw.gov.moi.land~ref~plvr` | 主表 | 透過 `編號` JOIN，取得交易價格、地址、縣市、類型等資訊 |
| `tw.gov.moi.land~ref~plvr-build` | 建物附表 | 同一交易的建物移轉明細 |
| `tw.gov.moi.land~ref~plvr-park` | 停車位附表 | 同一交易的停車位明細 |

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/records` |
| Agg URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-land/agg` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | https://data.openfun.tw/user |
| Records 回應格式 | JSON，含 `total`、`page`、`per_page`、`records[]` |
| Agg 回應格式 | JSON，含 `total_records`、`total_groups`、`groups[].key`、`groups[].stats.count` |
| 依交易查土地 | `?編號=XXXXX`（從主表取得 `編號`） |
| 地號搜尋 | `?q=地號`（全文搜尋） |
| 使用分區篩選 | `?使用分區或編定=都市：住`（filter: true） |
| 移轉情形篩選 | `?移轉情形=全筆移轉` 或 `?移轉情形=持分移轉` |
| 分頁 | `?page=1&per_page=20`（預設 page=1, per_page=20） |
| 面積換算 | 1 坪 ≈ 3.3058 ㎡ |