alterlab-datacommons

Data Commons クライアント

概要

統計的な観測値のクエリ、ナレッジグラフの探索、エンティティ識別子の解決を行うための Data Commons Python API v2 への包括的なアクセスを提供します。Data Commons は、国勢調査局、保健機関、環境機関などの信頼できるソースからデータを集約し、統一されたナレッジグラフにまとめています。

datacommons-client 2.1.6 で検証済み（2026-09 時点で最新、Python ≥ 3.10）。これは V2 クライアント（パッケージ datacommons_client）であり、レガシーの datacommons（V1）パッケージではありません。2つの API は異なるため、混同しないでください。キーワード名が重要です。場所の階層ヘルパーは place_dcids を受け取り、fetch_entity_names は entity_dcids を、fetch_property_values は properties を受け取ります。これらに node_dcids を渡すと TypeError が発生します。

このスキルを使用する場合

• 国、州、郡、市などの場所について、人口、経済、健康、教育、環境に関する統計を取得する場合
• 調和された公開ソース（国勢調査、BLS、WHO、World Bank、EPA など）を使って、場所間または時系列の比較を作成する場合
• 場所名、座標、Wikidata ID を Data Commons DCID に解決する場合
• Data Commons ナレッジグラフを探索する場合（場所の階層、プロパティ、統計変数の定義）

対象外

シナリオ	代わりに使用
ビンテージ／改訂データを含む特定の FRED 経済系列（GDP、CPI、金利）	alterlab-fred
米国財務省の財政データ（債務、支出、歳入）	alterlab-usfiscaldata
NCI Imaging Data Commons（CT／MR／病理画像）— 別の「Data Commons」	alterlab-imaging-data-commons
空間結合、バッファー、ジオメトリのマッピング	alterlab-geopandas

インストール

Pandas サポート付きで Data Commons V2 クライアントをインストールします（追加機能名は小文字の pandas です）。

uv pip install "datacommons-client[pandas]"

Pandas を使わない基本的な使用方法：

uv pip install datacommons-client

主な機能

Data Commons API は3つの主要なエンドポイントで構成されており、それぞれ専用のリファレンスファイルで詳しく説明しています。

1. Observation エンドポイント — 統計データのクエリ

エンティティの時系列統計データをクエリします。詳しくは references/observation.md を参照してください。

主な用途：

• 人口、経済、健康、環境に関する統計を取得する
• 傾向分析のために過去の時系列データにアクセスする
• 階層内のデータをクエリする（州内の全郡、地域内の全国家など）
• 複数のエンティティ間で統計を比較する
• 一貫性を保つためにデータソースで絞り込む

一般的なパターン：

from datacommons_client import DataCommonsClient

client = DataCommonsClient()

# Get latest population data
response = client.observation.fetch(
    variable_dcids=["Count_Person"],
    entity_dcids=["geoId/06"],  # California
    date="latest"
)

# Get time series
response = client.observation.fetch(
    variable_dcids=["UnemploymentRate_Person"],
    entity_dcids=["country/USA"],
    date="all"
)

# Query by hierarchy
response = client.observation.fetch(
    variable_dcids=["Median_Income_Household"],
    entity_expression="geoId/06<-containedInPlace+{typeOf:County}",
    date="2020"
)

2. Node エンドポイント — ナレッジグラフの探索

ナレッジグラフ内のエンティティ間の関係やプロパティを探索します。詳しくは references/node.md を参照してください。

主な用途：

• エンティティで利用可能なプロパティを見つける
• 地理的階層（親／子の関係）をたどる
• エンティティ名とメタデータを取得する
• エンティティ間のつながりを探索する
• グラフ内のすべてのエンティティタイプを一覧表示する

一般的なパターン：

# Discover properties
labels = client.node.fetch_property_labels(
    node_dcids=["geoId/06"],
    out=True
)

# Navigate hierarchy (dict: DCID -> list of {"dcid", "name", "types"})
children = client.node.fetch_place_children(
    place_dcids="country/USA",
    children_type="State",
)

# Get entity names (dict: DCID -> Name(value=..., language=...))
names = client.node.fetch_entity_names(
    entity_dcids=["geoId/06", "geoId/48"]
)

3. Resolve エンドポイント — エンティティの識別

エンティティ名、座標、または外部 ID を Data Commons ID（DCID）に変換します。詳しくは references/resolve.md を参照してください。

主な用途：

• クエリに使う場所名を DCID に変換する
• 座標を場所に解決する
• Wikidata ID を Data Commons エンティティに対応付ける
• あいまいなエンティティ名を処理する

一般的なパターン：

# Resolve by name
response = client.resolve.fetch_dcids_by_name(
    names=["California", "Texas"],
    entity_type="State"
)

# Resolve by coordinates (returns a ResolveResponse, not a bare DCID)
coord_response = client.resolve.fetch_dcid_by_coordinates(
    latitude="37.7749",
    longitude="-122.4194"
)

# Resolve Wikidata IDs
response = client.resolve.fetch_dcids_by_wikidata_id(
    wikidata_ids=["Q30", "Q99"]
)

一般的なワークフロー

Data Commons のクエリの多くは、次のパターンに従います。

1. エンティティを解決する（名前から開始する場合）：

   resolve_response = client.resolve.fetch_dcids_by_name(
       names=["California", "Texas"], entity_type="State"
   )
   # to_dict() -> {"entities": [{"node": "California", "candidates": [{"dcid": ...}]}, ...]}
   dcids = [e["candidates"][0]["dcid"]
            for e in resolve_response.to_dict()["entities"]
            if e.get("candidates")]
   # or: resolve_response.to_flat_dict() -> {"California": "geoId/06", ...}
   #     (a list of DCIDs when the name is ambiguous)
   

2. 利用可能な変数を見つける（任意）：

   variables = client.observation.fetch_available_statistical_variables(
       entity_dcids=dcids
   )
   

3. 統計データをクエリする：

   response = client.observation.fetch(
       variable_dcids=["Count_Person", "UnemploymentRate_Person"],
       entity_dcids=dcids,
       date="latest"
   )
   

4. 結果を処理する：

   # As dictionary
   data = response.to_dict()
   
   # As flat records (date, entity, variable, value + facet metadata).
   # to_observation_records() returns a pydantic model — dump it before
   # building a DataFrame, or the columns come out as 0..N.
   records = response.to_observation_records().model_dump()
   df = pd.DataFrame(records)
   

   手動での変換を省略するため、クライアントには専用の DataFrame アクセサーも用意されています。同じクエリを実行し、整形済みの DataFrame を直接返します。

   df = client.observations_dataframe(
       variable_dcids=["Count_Person"],
       entity_dcids=["geoId/06", "geoId/48"],
       date="all",
   )
   

統計変数を見つける

Data Commons の統計変数には、特定の命名パターンがあります。

一般的な変数パターン：

• Count_Person - 総人口
• Count_Person_Female - 女性人口
• UnemploymentRate_Person - 失業率
• Median_Income_Household - 世帯所得の中央値
• Count_Death - 死亡者数
• Median_Age_Person - 年齢の中央値

検索方法：

# Check what variables are available for an entity
available = client.observation.fetch_available_statistical_variables(
    entity_dcids=["geoId/06"]
)

# Or explore via the web interface
# https://datacommons.org/tools/statvar

Pandas の使用

標準的な方法は、クライアントの observations_dataframe() アクセサーを使うことです。このアクセサーは observation.fetch() の引数に対応し、1 回の呼び出しで整形済みの DataFrame を返します（pandas の追加インストールが必要です）。

df = client.observations_dataframe(
    variable_dcids=["Count_Person"],
    entity_dcids=["geoId/06", "geoId/48"],
    date="all",
)
# Columns: date, entity, variable, value (plus facet/provenance columns)

# Reshape for analysis
pivot = df.pivot_table(
    values='value',
    index='date',
    columns='entity'
)

親となる地域の、ある種類に属するすべてのエンティティを取得するには、entity_type と parent_entity とともに entity_dcids="all" を指定します。

df = client.observations_dataframe(
    variable_dcids=["Median_Income_Household"],
    date="latest",
    entity_dcids="all",
    entity_type="County",
    parent_entity="geoId/06",
)

すでにレスポンスオブジェクトがある場合は、to_observation_records()（単数形の「observation」です。to_observations_as_records はありません）でフラット化してから出力します。

response = client.observation.fetch(
    variable_dcids=["Count_Person"],
    entity_dcids=["geoId/06", "geoId/48"],
    date="all",
)
df = pd.DataFrame(response.to_observation_records().model_dump())

API 認証

datacommons.org の場合（デフォルト）：

• 観測データとノードのクエリには API キーが必要です（認証なしの呼び出しは HTTP 401 UNAUTHENTICATED を返します）。名前解決は現在、API キーなしで応答します
• 環境変数で設定します：export DC_API_KEY="your_key"
• または、初期化時に渡します：client = DataCommonsClient(api_key="your_key")
• キーの申請先：https://apikeys.datacommons.org/

カスタム Data Commons インスタンスの場合：

• API キーは不要です
• カスタムエンドポイントを指定します：client = DataCommonsClient(url="https://custom.datacommons.org")

リファレンスドキュメント

各エンドポイントの詳細なドキュメントは、references/ ディレクトリにあります。

• references/observation.md：すべてのメソッド、パラメーター、レスポンス形式、一般的なユースケースを網羅した Observation API の完全なドキュメント
• references/node.md：グラフの探索、プロパティのクエリ、階層のナビゲーションに関する Node API の完全なドキュメント
• references/resolve.md：エンティティの識別と DCID の解決に関する Resolve API の完全なドキュメント
• references/getting_started.md：エンドツーエンドの例と一般的なパターンを含むクイックスタートガイド

その他のリソース

• 公式ドキュメント：https://docs.datacommons.org/api/python/v2/
• 統計変数エクスプローラー：https://datacommons.org/tools/statvar
• Data Commons ブラウザー：https://datacommons.org/browser/
• GitHub リポジトリ：https://github.com/datacommonsorg/api-python

効果的に使うためのヒント

1. まず必ず名前を解決します：データをクエリする前に、名前を DCID に変換します
2. 階層にはリレーション式を使います：個別にクエリするのではなく、すべての子を一度にクエリします
3. まずデータの有無を確認します：fetch_available_statistical_variables() を使って、クエリ可能なデータを確認します
4. Pandas 連携を活用します：レスポンスを DataFrame に変換して分析します
5. 解決結果をキャッシュします：同じエンティティを繰り返しクエリする場合は、名前→DCID の対応を保存します
6. 一貫性を保つため、ファセットでフィルターします：filter_facet_domains を使って、同じソースのデータに絞り込みます
7. リファレンスドキュメントを読みます：各エンドポイントの詳細なドキュメントが references/ ディレクトリにあります

スクリプト

scripts/query_datacommons.py — Data Commons REST v2 API 用の実行可能なヘルパーです（DC_API_KEY に無料のキーが必要です）。

python scripts/query_datacommons.py resolve "California" --type State
python scripts/query_datacommons.py observe Count_Person geoId/06 --date latest