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

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

---

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

資料集 slug：tw.gov.moi.land~ref~plvr-build
API 端點：https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-build/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-build/records?per_page=20"

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

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

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

---

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

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

- 「這筆交易（編號 XXXXX）包含哪些建物？各是幾坪？」
- 「這棟建物的主要建材是什麼？幾層樓？屋齡幾年？」
- 「這筆交易移轉了哪些部分（主建物、共有部分、停車空間）？」
- 「這筆交易的建物是否為全筆移轉還是持分移轉？」

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

- 「這筆交易的成交金額是多少？」（金額在主表 `tw.gov.moi.land~ref~plvr`，不在本表）
- 「這個門牌的房子賣了多少錢？」（需先查主表取得 `編號`，再查本表取建物明細）
- 「台北市有幾筆鋼筋混凝土造的交易？」（本表無縣市欄位，須 JOIN 主表）

---

## 資料來源與更新頻率

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

---

## 關聯主表的方式

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

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

---

## 欄位說明

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

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `id` | keyword（_id） | 實價登錄交易編號 + 序號 |
| `編號` | keyword（ref: tw.gov.moi.land~ref~plvr） | 對應實價登錄交易編號 |
| `屋齡` | number（篩選器） |  |
| `建物移轉面積平方公尺` | number |  |
| `主要用途` | keyword（篩選器） |  |
| `主要建材` | keyword（篩選器） |  |
| `建築完成日期` | text |  |
| `建築完成日期.日期` | date |  |
| `總層數` | text |  |
| `總層數.樓層` | number（篩選器） |  |
| `建物分層` | text |  |
| `移轉情形` | keyword（篩選器） |  |

| 欄位名稱 | 型別 | filter | 說明 |
|---------|------|--------|------|
| `id` | keyword | — | 唯一識別碼，格式 `{編號}-{序號}` |
| `編號` | keyword | — | 對應主表（`tw.gov.moi.land~ref~plvr`）的 `編號` 欄位 |
| `屋齡` | number | — | 建物屋齡（年） |
| `建物移轉面積平方公尺` | number | — | 本筆建物移轉面積（㎡），非整筆交易總面積 |
| `主要用途` | keyword | ✅ | 常見值：`住家用`、`集合住宅`、`商業用`、`辦公室`；「共有部分」有多種寫法（`共有部分`、`共有部份`、`共用部份`、`共用部分`） |
| `主要建材` | keyword | ✅ | 例如 `鋼筋混凝土造`、`加強磚造`、`鋼骨造`（共約 100 種寫法） |
| `建築完成日期` | text | — | 原始民國格式，例如 `105年9月12日` |
| `建築完成日期.日期` | date | — | 西元日期格式，可用 `[gte]`/`[lte]` 篩選 |
| `總層數` | text | — | 原始中文文字，例如 `二十四層` |
| `總層數.樓層` | number | ✅ | 總層數數值（可篩選） |
| `建物分層` | text | — | 本筆建物所在樓層及附屬構造，例如 `八層 陽臺 雨遮`；共有部分通常為空 |
| `移轉情形` | keyword | ✅ | `全筆移轉`、`持分移轉`、空字串或 null（約 47% 為空） |

---

## API 呼叫範例

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

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

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

用途：取得特定交易的所有建物記錄（主建物、共有部分、停車空間等）。`編號` 從主表取得。

---

### 範例 2：篩選特定主要用途

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-build/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-build/records?主要建材=鋼筋混凝土造&per_page=20"
```

用途：查詢主要建材為鋼筋混凝土造的建物記錄。注意 `主要建材` 有多種相近寫法，建議先用 agg 確認實際值。

---

### 範例 4：篩選建築完成日期區間

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-build/records?建築完成日期.日期[gte]=2010-01-01&建築完成日期.日期[lte]=2020-12-31&per_page=20"
```

用途：取得 2010–2020 年間完工的建物記錄。

---

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

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

用途：篩選整筆所有權移轉（非持分移轉）的建物記錄。

---

### 分頁查詢

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

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

---

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

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

可分組的 keyword 欄位：`主要用途`、`主要建材`、`移轉情形`

### 各主要用途筆數分布

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-build/agg?group_by=主要用途"
```

注意：「共有部分」有 `共有部分`、`共有部份`、`共用部份`、`共用部分` 等多種寫法，各自為獨立 key。

### 各主要建材筆數分布

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-build/agg?group_by=主要建材"
```

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

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

---

## 注意事項與限制

1. **本表無縣市欄位**：無法單獨依縣市篩選，需搭配主表 JOIN 使用。
2. **`主要建材` 有多種寫法**：建議先用 `/agg?group_by=主要建材` 確認實際存在的值再篩選，避免漏查。
3. **`移轉情形` 約 47% 為空**：空字串及 null 都代表未填寫，統計時需注意。
4. **`建物移轉面積平方公尺` 是單筆面積**：一筆交易有多筆建物記錄，各自的面積需加總才等於主表的 `建物(移轉)總面積平方公尺`。
5. **面積單位為平方公尺（㎡）**：換算坪數請除以 3.3058。

---

## 關聯資料集

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

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-build/records` |
| Agg URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr-build/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`（從主表取得 `編號`） |
| 主要建材篩選 | `?主要建材=鋼筋混凝土造`（filter: true） |
| 移轉情形篩選 | `?移轉情形=全筆移轉` 或 `?移轉情形=持分移轉` |
| 分頁 | `?page=1&per_page=20`（預設 page=1, per_page=20） |
| 面積換算 | 1 坪 ≈ 3.3058 ㎡ |