---
reviewed_by:
  rd: tmonk
  pm: 
---
# 實價登錄 — `tw.gov.moi.land~ref~plvr`

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

---

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

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

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

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

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

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 行政院內政部地政司（[實價登錄開放資料下載](https://plvr.land.moi.gov.tw/DownloadOpenData)） |
| 授權 | 政府資料開放授權條款－第1版 |
| 更新頻率 | 每週更新 |
| 涵蓋範圍 | 全台 22 縣市，民國 104 年 S3 起（約 2015 年）至今 |
| 總筆數 | 約 602 萬筆（2026-05-28） |

---

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

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

- 「臺北市大安區近期有哪些不動產成交案件？」
- 「這個門牌的房子賣了多少錢、幾坪？」
- 「台中市 3 房 2 廳的公寓每坪單價大概是多少？」
- 「新北市的租屋行情大概是多少？」
- 「某季度全台灣預售屋交易量有多少？」

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

- 「某筆土地的地主是誰？」（實價登錄不揭露交易雙方身分）
- 「這棟建物的謄本資料？」（需查地政機關謄本，不在此資料集）
- 「某建物現在的市場估價？」（本資料集只有已成交紀錄，不做估價）

---

## 欄位說明

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `type` | keyword（篩選器） | 不動產買賣、預售屋買賣或不動產租賃 |
| `season` | keyword（篩選器） | {民國年}{S1~4} |
| `city` | keyword（篩選器） |  |
| `city_code` | keyword（篩選器） | a~z |
| `編號` | keyword（_id） | 實價登錄唯一識別碼 |
| `鄉鎮市區` | keyword（篩選器） |  |
| `行政區代碼` | keyword（ref: tw.openfun~entity~geo） |  |
| `土地位置建物門牌` | text（_name） |  |
| `都市土地使用分區` | keyword（篩選器） |  |
| `非都市土地使用分區` | keyword（篩選器） |  |
| `非都市土地使用編定` | keyword（篩選器） |  |
| `交易(租賃)年月日` | text |  |
| `交易(租賃)年月日.日期` | date |  |
| `交易(租賃)筆棟數` | text |  |
| `轉移(租賃)層次` | text |  |
| `總樓層數` | text |  |
| `總樓層數.樓層` | number（篩選器） |  |
| `建物型態` | text |  |
| `主要用途` | text |  |
| `主要建材` | keyword（篩選器） |  |
| `建築完成年月` | text |  |
| `建築完成年月.日期` | date |  |
| `土地(移轉)面積平方公尺` | number |  |
| `建物(移轉)總面積平方公尺` | number |  |
| `建物現況格局-房` | number（篩選器） |  |
| `建物現況格局-廳` | number（篩選器） |  |
| `建物現況格局-衛` | number（篩選器） |  |
| `建物現況格局-隔間` | keyword（篩選器） |  |
| `有無管理組織` | keyword（篩選器） |  |
| `有無附傢俱` | keyword（篩選器） |  |
| `總價(額)元` | number |  |
| `單價元平方公尺` | number |  |
| `車位類別` | keyword（篩選器） |  |
| `車位(移轉)總面積平方公尺` | number |  |
| `車位總價(額)元` | number |  |
| `備註` | text |  |
| `主建物面積` | number |  |
| `附屬建物面積` | number |  |
| `陽台面積` | number |  |
| `有無電梯` | keyword（篩選器） |  |
| `移轉編號` | text |  |
| `建案名稱` | text |  |
| `棟及號` | text |  |
| `解約情形` | text |  |
| `出租型態` | keyword（篩選器） |  |
| `有無管理員` | keyword（篩選器） |  |
| `租賃期間` | text |  |
| `附屬設備` | text |  |
| `租賃住宅服務` | keyword（篩選器） |  |

### 關鍵欄位補充說明

| 欄位 | 型別 | 重要說明 |
|------|------|---------|
| `type` | keyword（篩選器） | 類型：`不動產買賣`、`預售屋買賣`、`不動產租賃`；**查詢前必須指定** |
| `season` | keyword（篩選器） | 申報季別，格式 `{民國年}S{季}`，如 `114S1` |
| `city` | keyword（篩選器） | 縣市名稱，如 `臺北市`；`city_code` 為內政部原始英文代碼 |
| `鄉鎮市區` | keyword（篩選器） | 行政區，如 `大安區`、`板橋區` |
| `土地位置建物門牌` | text（_name） | 門牌或地號；全文搜尋：`?q=信義路四段` |
| `交易(租賃)年月日.日期` | date | 西元日期，可用 `[gte]`/`[lte]` 篩選區間；原始民國格式存於 `交易(租賃)年月日` |
| `總價(額)元` | number | 買賣為成交總價；**租賃為月租金**（非年租或總額） |
| `單價元平方公尺` | number | 每㎡單價；換算坪數：÷ 3.3058 |
| `建物(移轉)總面積平方公尺` | number | 建物總登記面積（㎡），含主建物＋附屬建物＋陽台 |
| `建物現況格局-房` / `-廳` / `-衛` | number（篩選器） | 格局篩選，如 `?建物現況格局-房=3` |

---

## 重要注意事項（查詢前必讀）

### ⚠️ 面積單位是平方公尺（㎡），非坪

所有面積欄位均為㎡。換算：**1 坪 ≈ 3.3058 ㎡**。向使用者呈現坪數時需換算。

### ⚠️ 租賃的「總價」是月租金

`type=不動產租賃` 時，`總價(額)元` 欄位為**月租金**，不是年租或合約總額。

### ⚠️ 各欄位在不同 type 下含義不同

- `電梯`（買賣用）vs `有無電梯`（租賃用）是不同欄位
- `建案名稱`、`棟及號` 只有預售屋有值
- `出租型態`、`租賃住宅服務` 只有租賃有值
- 預售屋的 `主建物面積`、`建築完成年月` 等通常為空（房子尚未完工）

### ⚠️ 申報制度不保證完全正確

實價登錄為義務申報制，個別案件可能有申報錯誤。建議參考同地段多筆均值，不宜以單筆作為精確依據。

---

## API 呼叫範例

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

### 範例 1：查詢特定縣市、類型的近期成交

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/records?city=臺北市&type=不動產買賣&per_page=20"
```

用途：取得臺北市最新不動產買賣成交案件。

---

### 範例 2：按行政區＋格局篩選

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/records?city=新北市&鄉鎮市區=板橋區&建物現況格局-房=3&type=不動產買賣&per_page=20"
```

用途：查詢新北市板橋區 3 房不動產買賣案件。

---

### 範例 3：依門牌全文搜尋（含日期區間）

```bash
# 基本門牌搜尋
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/records?q=信義路四段&city=臺北市&type=不動產買賣&per_page=20"

# 門牌 + 近五年（日期篩選要在 API 層做，不要拉全部資料再本地過濾）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/records?q=仁和二街&city=臺中市&鄉鎮市區=南區&type=不動產買賣&交易(租賃)年月日.日期[gte]=2021-06-03&per_page=100"
```

用途：搜尋特定路段的成交紀錄。`q=` 對 `土地位置建物門牌`（text 欄位）進行全文搜尋。

> **⚠️ 使用者說「近 N 年」時，務必換算成西元日期後帶入 `[gte]` 篩選**，不要先拉全部資料再本地過濾。`total` 欄位回傳的是篩選後總筆數，可用來確認篩選是否生效。

---

### 範例 4：租賃行情查詢

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/records?city=臺中市&鄉鎮市區=西屯區&type=不動產租賃&建物現況格局-房=2&per_page=20"
```

用途：查詢臺中市西屯區 2 房租賃行情，`總價(額)元` 為月租金。

---

### 範例 5：指定日期區間

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/records?city=高雄市&type=不動產買賣&交易(租賃)年月日.日期[gte]=2025-01-01&交易(租賃)年月日.日期[lte]=2025-03-31&per_page=20"
```

用途：查詢 2025 年 Q1 高雄市買賣案件。使用 `.日期` 欄位搭配 `[gte]`/`[lte]` 篩選。

---

### 分頁查詢

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

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

---

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

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

用途：按欄位分組統計筆數，適合「各縣市交易量」、「各類型分布」、「各行政區平均單價」等問題。

### 各縣市不動產買賣筆數

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/agg?group_by=city&type=不動產買賣"
```

### 某縣市各鄉鎮市區成交量

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/agg?group_by=鄉鎮市區&city=臺北市&type=不動產買賣"
```

### 各季度交易量趨勢

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/agg?group_by=season&city=臺北市&type=不動產買賣"
```

回應格式：
```json
{
  "total_records": 6021548,
  "total_groups": 3,
  "groups": [
    { "key": "不動產買賣", "stats": { "count": 4733415 } },
    { "key": "不動產租賃", "stats": { "count": 726031 } },
    { "key": "預售屋買賣", "stats": { "count": 562102 } }
  ]
}
```

---

## Python 腳本注意事項

在 bash 中執行含中文字的 Python 腳本時，**不要用 `python3 -c "...中文..."`**，會出現 Non-UTF-8 編碼錯誤。請改用以下兩種方式：

```bash
# ✅ 方法一：heredoc（推薦，對應系統 locale）
python3 << 'EOF'
import json, urllib.request, urllib.parse

token = "YOUR_TOKEN"
params = urllib.parse.urlencode({
    'q': '仁和二街',
    'city': '臺中市',
    '鄉鎮市區': '南區',
    'type': '不動產買賣',
    '交易(租賃)年月日.日期[gte]': '2021-06-03',
    'per_page': '100',
})
req = urllib.request.Request(
    f'https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/records?{params}',
    headers={'Authorization': f'Bearer {token}'}
)
with urllib.request.urlopen(req) as r:
    data = json.load(r)

print(f'共 {data["total"]} 筆')
for rec in data['records']:
    addr = rec.get('土地位置建物門牌', '')
    price = rec.get('總價(額)元', 0)
    area_m2 = rec.get('建物(移轉)總面積平方公尺', 0) or 0
    area_ping = area_m2 / 3.3058
    unit = (price / area_ping / 10000) if area_ping else 0
    date = rec.get('交易(租賃)年月日', '')
    print(f'{date} | {addr} | 總價:{price//10000}萬 | 建物:{area_ping:.1f}坪 | 單價:{unit:.1f}萬/坪')
EOF

# ✅ 方法二：寫成 .py 檔再執行（含 # -*- coding: utf-8 -*- 宣告）
```

> **f-string 注意**：Python 3.9 以下，f-string 的 `{}` 內不能用引號括字串（如 `f"{'姓名':<10}"` 會報錯）。需要欄寬格式化時，先把變數存成普通字串再放入 f-string。

---

## 注意事項與限制

1. **面積單位為平方公尺（㎡）**，非坪。換算：1 坪 ≈ 3.3058 ㎡。
2. **租賃的「總價」是月租金**，非年租或總金額。
3. **預售屋資料欄位較少**：`建築完成年月`、`主建物面積`、`附屬建物面積`、`陽台面積` 等通常為空，因為房子尚未完工。
4. **部分欄位僅特定類型有值**：`建案名稱`、`棟及號` 只有預售屋有；`出租型態`、`有無管理員`、`有無電梯`（租賃用）、`附屬設備`、`租賃住宅服務` 只有租賃有。
5. **「電梯」與「有無電梯」是不同欄位**：買賣類用 `電梯`，租賃類用 `有無電梯`。
6. **地號資料**：部分土地交易無門牌，`土地位置建物門牌` 欄位為地段地號（例如「崇仰段四小段675-1地號」）。
7. **主建物面積**：部分早期（104 年以前）資料此欄位為 null，以 `建物(移轉)總面積平方公尺` 替代。
8. **申報制度**：實價登錄為義務申報制，依法申報者不代表完全無誤，個別案件可能有申報錯誤。

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) | 行政區代碼對照 | 可將 `行政區代碼` 對應到完整地名 |

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/records` |
| Agg URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.moi.land~ref~plvr/agg` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | https://data.openfun.tw/user |
| 全文搜尋門牌 | `?q=關鍵字`（對 `土地位置建物門牌` 欄位） |
| 類型篩選 | `?type=不動產買賣`、`?type=不動產租賃`、`?type=預售屋買賣` |
| 縣市篩選 | `?city=臺北市` |
| 行政區篩選 | `?鄉鎮市區=大安區` |
| 日期區間 | `?交易(租賃)年月日.日期[gte]=2025-01-01&交易(租賃)年月日.日期[lte]=2025-12-31` |
| 分頁 | `?page=1&per_page=20`（預設 page=1, per_page=20） |
| 面積換算 | 1 坪 ≈ 3.3058 ㎡ |
| Records 回應 | JSON，含 `total`、`page`、`per_page`、`records[]` |
| Agg 回應 | JSON，含 `total_records`、`total_groups`、`groups[].key`、`groups[].stats.count` |