datacommons-client

Data Commons Client

概要

Data Commons Python API v2 への包括的なアクセスを提供し、統計的な観測値の照会、ナレッジグラフの探索、エンティティ識別子の解決を行えます。Data Commons は、国勢調査局、保健機関、環境機関、その他の信頼できる情報源からのデータを統合し、一つのナレッジグラフにまとめています。

インストール

Pandas サポート付きで Data Commons Python クライアントをインストールします:

pip install "datacommons-client[Pandas]"

Pandas を使わない基本的な使い方の場合:

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=["MedianIncome_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
children = client.node.fetch_place_children(
    node_dcids=["country/USA"]
)

# Get entity names
names = client.node.fetch_entity_names(
    node_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
dcid = 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"]
   )
   dcids = [r["candidates"][0]["dcid"]
            for r in resolve_response.to_dict().values()
            if r["candidates"]]
   

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 Pandas DataFrame
   df = response.to_observations_as_records()
   

統計変数の探し方

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 での利用

すべての Observation のレスポンスは Pandas と統合されています。

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

# Convert to DataFrame
df = response.to_observations_as_records()
# Columns: date, entity, variable, value

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

API 認証

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

• 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/
• Statistical Variable Explorer: https://datacommons.org/tools/statvar
• Data Commons Browser: https://datacommons.org/browser/
• GitHub リポジトリ: https://github.com/datacommonsorg/api-python

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

1. 常に解決（resolution）から始める: データをクエリする前に、名前を DCID に変換してください
2. 階層には relation 式を使う: 子要素を個別にクエリするのではなく、一度にすべて取得してください
3. 先にデータの可用性を確認する: fetch_available_statistical_variables() を使うと、クエリ可能な項目を確認できます
4. Pandas との連携を活用する: 分析のためにレスポンスを DataFrame に変換してください
5. 解決結果をキャッシュする: 同じエンティティを繰り返しクエリする場合は、名前から DCID へのマッピングを保存してください
6. ファセットでフィルタリングして一貫性を保つ: filter_facet_domains を使い、同じソースからのデータであることを保証してください
7. リファレンスドキュメントを読む: 各エンドポイントの詳細なドキュメントは references/ ディレクトリにあります