estat-stats

e-Stat(政府統計の総合窓口)のAPI(バージョン3.0)で、統計表の検索からデータ取得までを行うスキル。総務省など各府省の公式統計3,000表以上をカバーする。

実測日: 2026-09-13。本文のコマンド・構造は実測で確認したものを収録(個所ごとの日付は各所の記載を参照)。

appIdの準備(最初の1回だけ)

1. e-Statのユーザ登録ページ( https://www.e-stat.go.jp/mypage/user/preregister )で登録し、マイページからappIdを発行する(無料・即時)。
2. appIdはチャットやコード、コミットに書かない。環境変数(例: ESTAT_APP_ID)に入れて使う。
3. 利用には政府統計利用規約への同意が必要。取得データを使う成果物には出典(クレジット)を明記するルールがある。要件は https://www.e-stat.go.jp/api/api-info/credit を参照。

1. 統計表を検索する (getStatsList)

curl -s "https://api.e-stat.go.jp/rest/3.0/app/json/getStatsList?appId=${ESTAT_APP_ID}&searchWord=%E4%BA%BA%E5%8F%A3&limit=5"

• searchWord: 検索語(URLエンコードする。例の %E4%BA%BA%E5%8F%A3 は「人口」)
• limit: 件数。startPosition でページング
• 応答の GET_STATS_LIST.DATALIST_INF.TABLE_INF が統計表の配列。@id が後続のAPIで使う統計表ID(statsDataId)。STATISTICS_NAME(調査名)、TITLE.$(表題)、GOV_ORG.$(所管)を見て絞る
• appIdなし・無効だと RESULT.STATUS=100「認証に失敗しました」のJSONが返る(HTTP 200のまま。2026-09-13実測)。HTTPステータスではなく応答JSONの STATUS を見る
• 2026-09-13に無料appIdで getStatsList/getMetaInfo/getStatsData の3連を実測(いずれも STATUS=0)。appIdの即時発行を確認

2. 表の構造を調べる (getMetaInfo)

例として 0000150002(人口推計、総務省。2026-09-13に実キーで実測)を使う。

curl -s "https://api.e-stat.go.jp/rest/3.0/app/json/getMetaInfo?appId=${ESTAT_APP_ID}&statsDataId=0000150002"

• 応答の METADATA_INF.CLASS_INF.CLASS_OBJ に、表の軸(表章事項・分類事項・時間軸・地域)と各コード値が入る。この表の実測では cat01(年齢5歳階級、46コード)、cat02(男女別、3コード)、cat03(年、5コード)、area(全国)、time(時間軸) が返った
• データ取得で使う絞り込みコード(cdArea、cdCat01 など)はここで得る。@id がパラメータ名の suffix、CLASS がコードと名称の一覧

3. データを取得する (getStatsData)

curl -s "https://api.e-stat.go.jp/rest/3.0/app/json/getStatsData?appId=${ESTAT_APP_ID}&statsDataId=0000150002&cdCat01=000&cdCat02=000&limit=5"

• cdCat01=000&cdCat02=000 は getMetaInfo で得たコード(年齢総数・男女総数)による絞り込み。cd<軸ID>=<コード> の形式で付ける(2026-09-13実測)
• 応答の STATISTICAL_DATA.DATA_INF.VALUE が値の配列。@time(時間軸コード)、@area(地域コード)、$(値)を持つ。コードの意味は getMetaInfo の結果と突き合わせる
• 大きい表は limit + startPosition で分割取得する(次の開始位置は RESULT_INF の TOTAL_NUMBER/FROM_NUMBER/TO_NUMBER から計算する)

エラー・失敗時の対応

共通の取得時チェックリストは 共通レスポンス契約 の「取得時の落とし穴チェックリスト」を参照。

• タイムアウトを付ける: curl -sm 30 のように必ず制限時間を付ける。
• STATUS=100 (認証エラー): appIdが未設定・無効。ESTAT_APP_ID が設定されているか確認し、「e-StatのappIdが無効な可能性があります。マイページで確認してください」と伝える。HTTPは200でもエラーなので、応答JSONの RESULT.STATUS を必ず見る(0 が成功)。
• STATUS=1 / エラーメッセージ付き: パラメータの誤り(存在しないstatsDataId、不正なコード値など)。ERROR_MSG をそのままユーザーに見せ、getMetaInfoでコードを取り直す。
• 結果が0件: エラーではなく「条件に合う統計表・データがない」正常な結果。その旨を伝える。取得失敗と混同しない。
• HTTP 5xx / タイムアウト: 1〜2回だけ再試行。直らなければe-Stat側の障害の可能性として、 https://www.e-stat.go.jp/api/ のお知らせ確認を案内する。
• 短時間に大量リクエストしない: 分割取得の間隔を空け、同一表の再取得は結果を使い回す。

English summary

Searches and fetches Japanese government statistics via the official e-Stat API v3 (3,000+ tables: population, GDP, CPI, labor, regional data). Requires a free appId from e-Stat user registration - keep it in an environment variable, never in chat or commits. Flow: getStatsList to find a table ID, getMetaInfo to learn its axes and filter codes, getStatsData with pagination to fetch values. The API returns HTTP 200 even for auth failures (STATUS=100 in the JSON body), so always check RESULT.STATUS, not the HTTP status. Data use carries a source-citation requirement under the government's statistics terms.