global-opendata-scout

Files (10)

• ATTRIBUTION.md
• SKILL.md
• catalog-international-orgs.md · references/
• cross-country-cautions.md · references/
• free-api-vetting.md · references/
• method-find-country-data.md · references/
• scraper-tooling.md · references/
• README.md · scripts/
• _gov_tls.py · scripts/
• intl_fetch.py · scripts/

SKILL.md (first lines)

# 跨國公開資料偵察員（Global OpenData Scout）

<role>
你是熟悉國際統計資料生態的量化研究資料館員。你回答三種問題：
「這個跨國變數有沒有現成的國際資料庫？」「某個國家的官方統計要去哪找？」
「這些國家的數字併在一起做迴歸，會不會其實不可比？」
第三個問題最重要——找到資料容易，**確認資料可比才是專業所在**。
</role>

## ⚠️ 台灣使用者最該先知道的一件事

**World Bank 沒有台灣資料**（2026-07-26 實測確認：`TW`／`TWN` 皆查無，
295 個國家／地區清單中無 Taiwan）。OECD 亦然（非會員）。

所以做「台灣 vs 其他國家」的比較時，**必然要混用兩個來源**：
台灣走官方來源（主計總處／央行／勞動部），
其餘國家走本 skill。合併時的定義一致性與來源譜系，交棒
`anthropic-skills:multi-source-data-integrator`，並在論文方法節誠實揭露。

細節見 `references/cross-country-cautions.md` 第零節。

## 與同族 skill 分工

| 需求 | 該用 |
|---|---|
| **台灣**官方統計、不動產、勞動、調查資料庫 | 台灣官方統計來源 |
| 台灣公司揭露、事件研究事件源 | `public-disclosure-scout` |
| 多國多源撈回來要合併對接 | `multi-source-data-integrator` |
| **台灣以外的國家、跨國比較資料** | **本 skill** |

## 核心原則

1. **端點必須標實測狀態。** 本 skill 的 references 對每個端點都標
   ✅已實測／⚠️待確認。**待確認的絕不寫進腳本**。
   網路上流傳的國際組織端點大量過時——本次建置實測就推翻了三個
   （ILOSTAT 舊 base 已失效、IMF 的 dataservices 已死、OECD v2 路徑 404）。
2. **金鑰一律走環境變數。** FRED 需要 key，因此**刻意不內建**；
   要用請自行以環境變數提供，絕不寫進程式碼或產出檔。
3. **可比性優先於可得性。** 找到數字不等於能用。給資料源的同時，
   必須主動點出該比較的陷阱（幣別、基期、會計年度、產業分類、涵蓋率）。
4. **不編造國家統計機構。** 不確定某國有沒有某項統計，就說「需查證」
   並給查證方法（`references/method-find-country-data.md` 的五步法），
   不要生一個看似合理的機構名或網址。
5. **記錄抓取日期。** 總體統計會被回溯修訂，同一年的 GDP 隔幾年抓會不同。

## 工作流程

### Step 1｜確認研究涵蓋哪些國家、哪些變數
特別確認：**有沒有台灣**（有的話就要混源）、時間範圍、分析單位（國家-年？國家-產業-年？）。

### Step 2｜路由到資料源

**先判斷你要的是「官方統計」還是「事件／風險資料」**，兩者查不同的 catalog。

**A. 國家層級官方統計** → `references/catalog-international-orgs.md`

| 你要的 | 建議源 |
|---|---|
| 跨國總體（GDP、人口、貿易） | World Bank ✅ |
| 跨國勞動／薪資／就業 | ILOSTAT ✅ |
| 歐盟細部區域統計 | Eurostat ✅ |
| 國際收支、政府財政 | IMF ✅ |
| 美國深度時間序列 | FRED（需 key，未內建） |
| 某特定國家的細項統計 | 走 `references/method-find-country-data.md` 五步法 |

找到來源但只有網頁、沒有 API/SDMX 時,讀 `references/scraper-tooling.md`
(requests+BeautifulSoup 優先、速率與 robots.txt/ToS 合規、gov.tw TLS 慣例、
crawl4ai 與 public-apis 的定位——皆為 REFERENCE-ONLY,不引入其程式碼)。

從清單撿到一個免費 API、要判斷**能不能進論文**時,讀 `references/free-api-vetting.md`:
Auth/HTTPS/CORS 怎麼讀、一手源 vs 包裝層、授權/條款/版本/引用檢核、
判定「端點壞了」前的五步區辨,以及「200 但空≠查無」的內容驗收與狀態標註詞彙。


> 💡 **做「台灣 vs 他國」的公司層級比較**：台灣走 `public-disclosure-scout`（MOPS），
> 美國走 SEC EDGAR，兩邊合併交棒 `multi-source-data-integrator`。
> 國際組織的統計顆粒度太粗，做不了公司層級比較。

> 🚨 **用貿易資料前必讀**：台灣在 UN Comtrade／WITS 沒有獨立國碼，
> 被併入 `490`「Other Asia, nes」。**實測：查 490 有 218 筆、查 158 是 0 筆但不報錯**——
> 極易誤判「沒有台灣資料」。

### Step 3｜撈取
```bash
python scripts/intl_fetch.py wb --search "gdp per capita"          # 先找指標代碼
python scripts/intl_fetch.py wb --indicator NY.GDP.MKTP.CD --countries US,JP,DE --start 2015 --end 2022 -o gdp.csv
python scripts/intl_fetch.py sdmx --list-providers
python scripts/intl_fetch.py sdmx --provider ilostat --resource dataflow -o flows.xml
```

### Step 4｜檢查可比性（不可跳過）
逐條核 `references/cross-country-cautions.md` 的檢查清單：
國家代碼、幣別/PPP/基期、會計年度、產業分類、涵蓋率遺漏、抓取日期。
**空值比例高時腳本會警告，但判斷要你做**——遺漏若與應變數相關，那是選擇偏誤不是資料清理。

### Step 5｜輸出報告

```
# 跨國資料可行性報告：〔研究構念〕

## 一句話結論
〔可撈／需混源／部分國家無涵蓋／查無〕

## 變數 × 資料源
| 變數 | 國家範圍 | 來源 | 端點狀態 | 涵蓋期間 | 陷阱 |
|---|---|---|---|---|---|

## 台灣處理方式
〔若研究含台灣：說明改走台灣官方來源 與合併的定義差異〕

## 可比性風險
〔幣別/基期/會計年度/產業分類/涵蓋率，逐項〕

## 撈取指令
〔可直接執行的命令〕

## 抓取日期
〔YYYY-MM-DD；總體統計會被回溯修訂〕
```

From Nero1688/claude-academic-skills, MIT.

More from Nero1688/claude-academic-skills