---
reviewed_by:
  rd: Ronny
  pm:
---
# 社會經濟資料庫（SEGIS）— `tw.segis.*` 系列資料集

> **給 AI 閱讀的使用指引。適用所有 `tw.segis.*` 格式的資料集。**
> 詳細產品目錄請見 [tw.segis.product](https://data.openfun.tw/datasets/tw.segis.product)。

---

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

**SEGIS 系列有數千個資料集，slug 不是固定的。**
在查詢資料之前，必須先找到正確的資料集 slug。請依照以下步驟操作：

**步驟一：搜尋產品目錄，找到 MID**

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.segis.product/records?q=人口&per_page=5"
```

回應中每筆記錄含 `mid`（產品代碼）、`name`（產品名稱）、`geotypes`（可用地理層級）。

**步驟二：選擇地理層級，組成 slug**

| `geotypes` 值 | 地理層級 | slug 後綴 | 一個時間點筆數 |
|-------------|---------|----------|-------------|
| `U01CO` | 縣市（22 個） | `.u01co` | ~22 筆 |
| `U01TO` | 鄉鎮市區（~350 個） | `.u01to` | ~350 筆 |
| `U01VI` | 村里（~7,800 個） | `.u01vi` | ~7,800 筆 |

slug 組成規則：`tw.segis.{MID 全小寫}.{level 全小寫}`

範例：MID `TW-04-301000000A-010001` + U01CO → slug `tw.segis.tw-04-301000000a-010001.u01co`

**步驟三：查詢資料**

```bash
# 基本查詢（必須加篩選條件，見下方說明）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/{slug}/records?per_page=20"
```

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

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

授權標注：使用此資料產出的內容需標注「資料來源：歐噴資料庫（data.openfun.tw）／內政部社會經濟資料服務平台」

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 內政部社會經濟資料服務平台（[segis.moi.gov.tw](https://segis.moi.gov.tw/STATCloud/Profile)） |
| 授權 | 政府資料開放授權條款－第 1 版 |
| 更新頻率 | 依各產品不同（月報、季報、年報均有）；`tw.segis.product` 的 `data_end` 欄位顯示最新資料時間 |
| 地理涵蓋 | 依各產品 `bounds` 欄位（全國、特定縣市等） |
| 時間格式 | 民國年格式（如 `97Y03M`）；同時提供西元日期（`INFO_TIME.date`，如 `2008-03-01`） |

---

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

**可以回答：**
- 臺北市各村里的人口數在 2020 年是多少？
- 過去 10 年新北市板橋區的戶數變化趨勢？
- 2023 年全台各縣市的某統計指標排名？
- 某統計項目在全台各鄉鎮的分布情況？

**無法回答：**
- 個別人名、戶籍、個資查詢（SEGIS 只有地理單位的彙整統計，無個人資料）
- 非 SEGIS 收錄的統計項目（先用 `tw.segis.product` 搜尋確認是否有該資料）
- 即時或每日更新的數據（SEGIS 更新頻率依各產品不同，多為月報或年報）

---

## 欄位說明

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `ID` | keyword（_id、篩選器） | 複合識別碼（地理代碼－資料時間，如 63000010-002-97Y03M） |
| `INFO_TIME` | keyword（篩選器） | 資料時間（民國年格式，如 97Y03M） |
| `INFO_TIME.date` | date | 資料時間（西元日期，如 2008-03-01） |
| `ID.TOWN_ID` | keyword（篩選器、ref: tw.openfun~entity~geo） | 鄉鎮市區代碼 |
| `ID.COUNTY_ID` | keyword（篩選器、ref: tw.openfun~entity~geo） | 縣市代碼（鄉鎮市區代碼前 5 碼） |
| `A0A9_M_CNT` | number | 於統計標準日戶籍登記實足年齡為0至未滿10歲原住民；單位：人；資料定義：NUMBER |
| `A0A9_F_CNT` | number | 於統計標準日戶籍登記實足年齡為0至未滿10歲原住民；單位：人；資料定義：NUMBER |
| `A10A19_M_CNT` | number | 於統計標準日戶籍登記實足年齡為10至未滿20歲原住民；單位：人；資料定義：NUMBER |
| `A10A19_F_CNT` | number | 於統計標準日戶籍登記實足年齡為10至未滿20歲原住民；單位：人；資料定義：NUMBER |
| `A20A29_M_CNT` | number | 於統計標準日戶籍登記實足年齡為20至未滿30歲原住民；單位：人；資料定義：NUMBER |
| `A20A29_F_CNT` | number | 於統計標準日戶籍登記實足年齡為20至未滿30歲原住民；單位：人；資料定義：NUMBER |
| `A30A39_M_CNT` | number | 於統計標準日戶籍登記實足年齡為30至未滿40歲原住民；單位：人；資料定義：NUMBER |
| `A30A39_F_CNT` | number | 於統計標準日戶籍登記實足年齡為30至未滿40歲原住民；單位：人；資料定義：NUMBER |
| `A40A49_M_CNT` | number | 於統計標準日戶籍登記實足年齡為40至未滿50歲原住民；單位：人；資料定義：NUMBER |
| `A40A49_F_CNT` | number | 於統計標準日戶籍登記實足年齡為40至未滿50歲原住民；單位：人；資料定義：NUMBER |
| `A50A59_M_CNT` | number | 於統計標準日戶籍登記實足年齡為50至未滿60歲原住民；單位：人；資料定義：NUMBER |
| `A50A59_F_CNT` | number | 於統計標準日戶籍登記實足年齡為50至未滿60歲原住民；單位：人；資料定義：NUMBER |
| `A60A69_M_CNT` | number | 於統計標準日戶籍登記實足年齡為60至未滿70歲原住民；單位：人；資料定義：NUMBER |
| `A60A69_F_CNT` | number | 於統計標準日戶籍登記實足年齡為60至未滿70歲原住民；單位：人；資料定義：NUMBER |
| `A70A79_M_CNT` | number | 於統計標準日戶籍登記實足年齡為70至未滿80歲原住民；單位：人；資料定義：NUMBER |
| `A70A79_F_CNT` | number | 於統計標準日戶籍登記實足年齡為70至未滿80歲原住民；單位：人；資料定義：NUMBER |
| `A80A89_M_CNT` | number | 於統計標準日戶籍登記實足年齡為80至未滿90歲原住民；單位：人；資料定義：NUMBER |
| `A80A89_F_CNT` | number | 於統計標準日戶籍登記實足年齡為80至未滿90歲原住民；單位：人；資料定義：NUMBER |
| `A90A99_M_CNT` | number | 於統計標準日戶籍登記實足年齡為90至未滿100歲原住民；單位：人；資料定義：NUMBER |
| `A90A99_F_CNT` | number | 於統計標準日戶籍登記實足年齡為90至未滿100歲原住民；單位：人；資料定義：NUMBER |
| `A100UP_M_CNT` | number | 於統計標準日戶籍登記實足年齡為100歲以上原住民；單位：人；資料定義：NUMBER |
| `A100UP_F_CNT` | number | 於統計標準日戶籍登記實足年齡為100歲以上原住民；單位：人；資料定義：NUMBER |

### 關鍵欄位補充說明

所有 `tw.segis.*` 資料集都有以下固定欄位：

| 欄位 | 型別 | 重要說明 |
|------|------|---------|
| `ID` | keyword | 複合識別碼（地理代碼-時間），如 `63000-97Y03M` |
| `INFO_TIME` | keyword | 資料時間（民國年格式），如 `97Y03M`、`100Y4S`、`100Y` |
| `INFO_TIME.date` | date | 資料時間（西元日期），可用 `>=`/`<` 篩選範圍，如 `2008-03-01` |
| `ID.COUNTY_ID` | keyword | 縣市代碼，參照 [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) |
| `ID.TOWN_ID` | keyword | 鄉鎮市區代碼（U01TO / U01VI 層級才有） |
| `ID.VILLAGE_ID` | keyword | 村里代碼（U01VI 層級才有） |

**統計欄位（因產品而異）**：請用以下指令查看當前資料集有哪些欄位：

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/{slug}/records?per_page=1" | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print([f['name'] for f in d['schema']])"
```

---

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

SEGIS 資料集資料量很大（VI 層級可達數十萬筆），**請務必搭配篩選條件**，避免取出過多不需要的資料。

**推薦策略（按場景選一種）：**

### 策略 A：看一個地區的時間趨勢（縱切面）
加地理篩選 → 只取該地區所有時間點

```bash
# 臺北市（ID.COUNTY_ID=63000）所有時間點的資料
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.segis.tw-04-301000000a-010001.u01co/records?ID.COUNTY_ID=63000&per_page=100"
```

### 策略 B：比較某一時間點的所有地區（橫切面）
加時間篩選 → 只取該時間點所有地區

```bash
# 2023年9月（INFO_TIME=112Y09M）全台縣市資料（CO 層級只有 22 筆）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.segis.tw-04-301000000a-010001.u01co/records?INFO_TIME=112Y09M"
```

### 策略 C：指定時間範圍（搭配日期範圍篩選）
使用 `INFO_TIME.date` 的範圍運算子：

```bash
# 2020年至2023年的資料
curl -sg -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.segis.tw-04-301000000a-010001.u01co/records?INFO_TIME.date>=2020-01-01&INFO_TIME.date<2024-01-01&ID.COUNTY_ID=63000&per_page=100"
```

> 注意：`INFO_TIME.date` 範圍查詢的 URL 含 `>=`、`<`，請用 curl 的 `-g` 旗標（`--globoff`）
> 避免 shell 將 `[]` 誤解為 glob 模式。上方範例 URL 未含 `[]` 所以不需要，但習慣加 `-g` 較安全。

### 策略 D：統計彙整（不需要原始資料）
用 `/agg` 取得各縣市的統計量，不需逐筆取資料：

```bash
# 最新時間點，各縣市人口數總和
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.segis.tw-04-301000000a-010001.u01co/agg?group_by=ID.COUNTY_ID&field=P_CNT&INFO_TIME=112Y09M"
```

---

## 地理層級選擇指引

| 想做什麼 | 建議層級 | 原因 |
|---------|---------|------|
| 全台縣市比較 | U01CO | 22 筆，查詢快，不需篩選 |
| 某縣市內的鄉鎮比較 | U01TO + `ID.COUNTY_ID=xxx` | 過濾後約 10-30 筆 |
| 精細村里分析 | U01VI + 縣市或鄉鎮篩選 | 不加篩選高達 7800 筆，必須篩選 |
| 全台時序趨勢 | U01CO | 層級最低，資料最少，適合趨勢分析 |

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.moi.segis~ref~product`](../tw.gov.moi.segis~ref~product/skill.md) | SEGIS 產品目錄 | 搜尋有哪些統計產品、確認可用層級與時間範圍 |
| [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) | 行政區代碼對照 | 查縣市 / 鄉鎮 / 村里的代碼與名稱 |

---

## 注意事項與限制

1. **時間格式**：`INFO_TIME` 使用民國年格式（`97Y03M` = 2008年3月、`100Y4S` = 2011年第4季、`100Y` = 2011年）。若要範圍查詢，請用 `INFO_TIME.date`（西元日期格式）。
2. **產品與層級組合**：並非每個產品都有三個層級，查 `tw.segis.product` 的 `geotypes` 欄位確認。
3. **資料缺值**：部分格位因統計限制為 `null`，計算時需注意。
4. **大量資料請分頁**：超過 per_page 上限時，用 `page` 參數翻頁；回應的 `total` 欄位顯示總筆數。

---

## 快速參考

| 項目 | 說明 |
|------|------|
| 產品目錄 | `https://data.openfun.tw/api/v1/datasets/tw.segis.product/records?q=關鍵字` |
| Slug 規則 | `tw.segis.{MID全小寫}.{level全小寫}` |
| Records URL | `https://data.openfun.tw/api/v1/datasets/{slug}/records` |
| Agg URL | `https://data.openfun.tw/api/v1/datasets/{slug}/agg` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 時間篩選（精確） | `?INFO_TIME=112Y09M` |
| 時間篩選（範圍） | `?INFO_TIME.date>=2020-01-01&INFO_TIME.date<2024-01-01` |
| 縣市篩選 | `?ID.COUNTY_ID=63000`（63000 = 臺北市） |
| 鄉鎮篩選 | `?ID.TOWN_ID=63000100`（U01TO / U01VI 層級） |
| 取得 Token | https://data.openfun.tw/user |
| Records 回應 | JSON，含 `total`、`page`、`per_page`、`records[]` |
| Agg 回應 | JSON，含 `total_records`、`total_groups`、`groups[].key`、`groups[].stats.count` |