datacommons-client

用途

Data Commons Client 提供对 Data Commons Python API v2 的完整访问能力，用于查询统计观测值、探索知识图谱以及解析实体标识符。Data Commons 将来自人口普查机构、卫生组织、环境机构等权威来源的公共统计数据聚合为统一的知识图谱。

安装

安装带 Pandas 支持的 Data Commons Python 客户端：

uv pip install "datacommons-client[Pandas]"

基础用法（不含 Pandas）：

uv pip install datacommons-client

主要能力

Data Commons API 由三个主要端点组成：

1. Observation 端点 — 统计数据查询

查询实体的时间序列统计数据。主要用例包括：检索人口、经济、健康或环境统计；访问历史时间序列数据用于趋势分析；查询层级数据（某州所有县、某地区所有国家）；比较多个实体的统计数据；按数据源过滤以保持一致性。

常见用法示例：

from datacommons_client import DataCommonsClient

client = DataCommonsClient()

# 获取最新人口数据
response = client.observation.fetch(
    variable_dcids=["Count_Person"],
    entity_dcids=["geoId/06"],  # California
    date="latest"
)

# 获取时间序列
response = client.observation.fetch(
    variable_dcids=["UnemploymentRate_Person"],
    entity_dcids=["country/USA"],
    date="all"
)

# 按层级查询
response = client.observation.fetch(
    variable_dcids=["MedianIncome_Household"],
    entity_expression="geoId/06<-containedInPlace+{typeOf:County}",
    date="2020"
)

2. Node 端点 — 知识图谱探索

探索知识图谱中的实体关系与属性。主要用例包括：发现实体可用属性；导航地理层级（父子关系）；检索实体名称与元数据；探索实体间连接；列出图中所有实体类型。

常见用法示例：

# 发现属性
labels = client.node.fetch_property_labels(
    node_dcids=["geoId/06"],
    out=True
)

# 导航层级
children = client.node.fetch_place_children(
    node_dcids=["country/USA"]
)

# 获取实体名称
names = client.node.fetch_entity_names(
    node_dcids=["geoId/06", "geoId/48"]
)

3. Resolve 端点 — 实体识别

将实体名称、坐标或外部 ID 转换为 Data Commons ID（DCID）。主要用例包括：将地名转换为 DCID 以便查询；将坐标解析为地点；将 Wikidata ID 映射到 Data Commons 实体；处理有歧义的实体名称。

常见用法示例：

# 按名称解析
response = client.resolve.fetch_dcids_by_name(
    names=["California", "Texas"],
    entity_type="State"
)

# 按坐标解析
dcid = client.resolve.fetch_dcid_by_coordinates(
    latitude=37.7749,
    longitude=-122.4194
)

# 解析 Wikidata ID
response = client.resolve.fetch_dcids_by_wikidata_id(
    wikidata_ids=["Q30", "Q99"]
)

使用方式

大多数 Data Commons 查询遵循以下流程：

解析实体（如果从名称开始）：

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"]]

发现可用变量（可选）：

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

查询统计数据：

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

处理结果：

# 作为字典
data = response.to_dict()

# 作为 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 — 年龄中位数

发现方法：

# 检查某实体可用的变量
available = client.observation.fetch_available_statistical_variables(
    entity_dcids=["geoId/06"]
)

也可通过网页界面探索：https://datacommons.org/tools/statvar

与 Pandas 配合使用

所有观测响应均可与 Pandas 集成：

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

# 转换为 DataFrame
df = response.to_observations_as_records()
# 列：date, entity, variable, value

# 重塑以便分析
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：完整的 Resolve API 文档，用于实体识别和 DCID 解析
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

有效使用建议

始终从解析开始：在查询数据前先将名称转换为 DCID
使用关系表达式处理层级：一次性查询所有子级，而非逐个查询
先检查数据可用性：使用 fetch_available_statistical_variables() 查看可查询内容
利用 Pandas 集成：将响应转换为 DataFrame 以便分析
缓存解析结果：若重复查询相同实体，存储名称→DCID 映射
按 facet 过滤以保持一致性：使用 filter_facet_domains 确保数据来自同一来源
阅读参考文档：每个端点在 references/ 目录中都有详尽文档

适用场景

适用于需要查询和分析公共统计数据的场景，包括人口统计、经济指标、健康数据、环境统计等。典型用户包括数据分析师、研究人员、开发者等需要以编程方式访问权威统计数据的人员。

限制

使用 datacommons.org 默认实例时需要 API 密钥
具体数据覆盖范围、更新频率等细节暂未提供
自定义实例的配置细节暂未提供

技能介绍

用途

安装

主要能力

1. Observation 端点 — 统计数据查询

2. Node 端点 — 知识图谱探索

3. Resolve 端点 — 实体识别

使用方式

查找统计变量

与 Pandas 配合使用

API 认证

参考文档

附加资源

有效使用建议

适用场景

限制