⚡

DataCommons客户端Skill datacommons-client

Data Commons 客户端是一个 Python 库，用于访问 Data Commons 平台，提供程序化查询全球公共统计数据的功能，包括人口统计、经济指标、健康数据和环境统计等。适用于数据分析、量化金融、经济研究、学术探索和统计建模，关键词包括数据查询、API 集成、统计分析、公共数据访问、知识图谱和 Python 开发。

数据分析 0 次安装 0 次浏览 更新于 3/16/2026

名称: datacommons-client 描述: 使用 Data Commons，一个提供程序化访问来自全球来源的公共统计数据的平台。当处理人口统计数据、经济指标、健康统计、环境数据或任何通过 Data Commons 可用的公共数据集时，使用此技能。适用于查询人口统计、GDP 数字、失业率、疾病流行率、地理实体解析以及探索统计实体之间的关系。

Data Commons 客户端

概述

提供对 Data Commons Python API v2 的全面访问，用于查询统计观察、探索知识图谱和解析实体标识符。Data Commons 将来自人口普查局、卫生组织、环境机构和其他权威来源的数据聚合到统一的知识图谱中。

安装

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

pip install "datacommons-client[Pandas]"

对于不使用 Pandas 的基本用法：

pip install datacommons-client

核心能力

Data Commons API 包括三个主要端点，每个在专用参考文件中详细说明：

1. 观察端点 - 统计数据查询

查询实体的时间序列统计数据。请参阅 references/observation.md 以获取完整文档。

主要用例：

  • 检索人口、经济、健康或环境统计数据
  • 访问历史时间序列数据以进行趋势分析
  • 查询层次结构的数据（州中的所有县、区域中的所有国家）
  • 比较多个实体的统计数据
  • 按数据源过滤以确保一致性

常见模式：

from datacommons_client import DataCommonsClient

client = DataCommonsClient()

# 获取最新人口数据
response = client.observation.fetch(
    variable_dcids=["Count_Person"],
    entity_dcids=["geoId/06"],  # 加利福尼亚州
    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. 节点端点 - 知识图谱探索

探索知识图谱中的实体关系和属性。请参阅 references/node.md 以获取完整文档。

主要用例：

  • 发现实体的可用属性
  • 导航地理层次结构（父/子关系）
  • 检索实体名称和元数据
  • 探索实体之间的连接
  • 列出图谱中的所有实体类型

常见模式：

# 发现属性
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. 解析端点 - 实体识别

将实体名称、坐标或外部 ID 转换为 Data Commons ID（DCIDs）。请参阅 references/resolve.md 以获取完整文档。

主要用例：

  • 将地名转换为 DCIDs 以进行查询
  • 解析坐标到地点
  • 映射 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 查询遵循此模式：

  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. 处理结果：

    # 作为字典
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"]
)

# 或通过 Web 界面探索
# 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()
# 列：日期、实体、变量、值

# 重塑以进行分析
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：快速入门指南，包含端到端示例和常见模式

其他资源

有效使用技巧

  1. 始终从解析开始：在查询数据之前将名称转换为 DCIDs
  2. 使用关系表达式处理层次结构：一次性查询所有子实体，而不是单个查询
  3. 首先检查数据可用性：使用 fetch_available_statistical_variables() 查看可查询内容
  4. 利用 Pandas 集成：将响应转换为 DataFrame 以进行分析
  5. 缓存解析：如果重复查询相同实体，存储名称→DCID 映射
  6. 按面过滤以确保一致性：使用 filter_facet_domains 确保来自同一源的数据
  7. 阅读参考文档：每个端点在 references/ 目录中有详细文档