使用新Python API客户端访问Data Commons

原创于 2025-12-28 12:13:08 发布 · 375 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#python #开发语言 #Python #数据获取 #知识图谱 #程序那些事 #AIGC

引言

数据是任何数据专业人员工作的核心。如果没有有用且有效的数据源，我们就无法履行职责。此外，质量低下或不相关的数据只会让我们的工作白费。这就是为什么能够访问可靠的数据集是数据专业人员的重要起点。

Data Commons 是某机构发起的一项开源计划，旨在组织世界上可用的数据，并让每个人都能访问和使用。任何人都可以免费查询公开可用的数据。Data Commons 与其他公共数据集项目的不同之处在于，它已经完成了图式化工作，使数据可以更快地投入使用。

鉴于 Data Commons 在数据工作中的实用性，访问它对于许多数据任务变得至关重要。幸运的是，Data Commons 提供了一个新的 Python API 客户端来访问这些数据集。

使用 Python 访问 Data Commons

Data Commons 的工作原理是将数据组织成一个可查询的知识图谱，该图谱将来自不同来源的信息统一起来。其核心是使用基于 schema.org 的模式模型来标准化数据表示。

利用这种模式，Data Commons 可以将各种来源的数据连接到一个单一的图谱中，其中节点代表实体（如城市、地点、人物）、事件和统计变量。边则描绘了这些节点之间的关系。每个节点都是唯一的，并通过 DCID 进行标识，许多节点包含观测值——与变量、实体和时期相关联的测量值。

通过 Python API，可以轻松访问知识图谱以获取所需数据。让我们尝试一下如何操作。

首先，需要获取一个免费的 API 密钥来访问 Data Commons。创建一个免费账户，并将 API 密钥复制到安全位置。也可以使用试用 API 密钥，但访问权限更为有限。

接下来，安装 Data Commons Python 库。我们将使用 V2 API 客户端，因为它是最新版本。运行以下命令以安装 Data Commons 客户端，并可选地支持 Pandas DataFrame。

pip install "datacommons-client[Pandas]"

库安装完成后，就可以使用 Data Commons Python 客户端获取数据了。

要创建用于从云端访问数据的客户端，请运行以下代码。

from datacommons_client.client import DataCommonsClient

client = DataCommonsClient(api_key="YOUR-API-KEY")

Data Commons 中最重要的概念之一是实体，它指的是现实世界中持久存在且物理存在的事物，例如城市或国家。这成为获取数据的重要组成部分，因为大多数数据集都需要指定实体。您可以访问 Data Commons Place 页面以了解所有可用的实体。

对于大多数用户而言，想要获取的数据更具体：存储在 Data Commons 中的统计变量。要选择要检索的数据，需要知道统计变量的 DCID，您可以通过 Statistical Variable Explorer 找到它。

您可以过滤变量并从上述选项中选择一个数据集。例如，为“每 10 万成年人拥有的 ATM 机数量”选择世界银行数据集。在这种情况下，您可以通过查看资源管理器提供的信息来获取 DCID。

如果点击 DCID，可以看到与该节点相关的所有信息，包括它如何与其他信息连接。

对于统计变量 DCID，我们还需要为地理区域指定实体 DCID。我们可以探索上面提到的 Data Commons Place 页面，或者使用以下代码来查看某个地点名称的可用 DCID。

# 通过地点名称查找 DCID（返回多个候选）
resp = client.resolve.fetch_dcids_by_name(names="Indonesia").to_dict()
dcid_list = [c["dcid"] for c in resp["entities"][0]["candidates"]]
print(dcid_list)

输出类似于：

['country/IDN', 'geoId/...' , '...']

使用上面的代码，我们获取了特定地点名称可用的 DCID 候选列表。例如，在“Indonesia”的候选列表中，可以选择 country/IDN 作为国家 DCID。

现在所有需要的信息都已准备就绪，只需执行以下代码：

variable = ["worldBank/GFDD_AI_25"]
entity = ["country/IDN"]

df = client.observations_dataframe(
    variable_dcids=variable,
    date="all",
    entity_dcids=entity
)

结果显示在下面的数据集中。

当前的代码返回所选变量和实体在整个时间范围内的所有可用观测值。在上面的代码中，您还会注意到我们使用的是列表而不是单个字符串。

这是因为我们可以同时传递多个变量和实体以获取组合数据集。例如，下面的代码同时获取两个不同的统计变量和两个实体。

variable = ["worldBank/GFDD_AI_25", "worldBank/SP_DYN_LE60_FE_IN"]
entity = ["country/IDN", "country/USA"]

df = client.observations_dataframe(
    variable_dcids=variable,
    date="all",
    entity_dcids=entity
)