observation

# Observation 端点 - 统计数据查询 ## 目的 Observation API 用于检索统计观测数据——即连接实体、变量和特定日期的数据点。例如： - “2020 年美国人口” - “加利福尼亚州历年 GDP” - “某州所有县的失业率” ## 核心方法 ### 1. fetch() 用于检索观测数据的主要方法，支持灵活的实体指定。 **关键参数：** - `variable_dcids` (必填): 统计变量标识符列表 - `entity_dcids` 或 `entity_expression` (必填): 通过 ID 或关系表达式指定实体 - `date` (可选): 默认为 "latest"。支持： - ISO-8601 格式 (例如 "2020", "2020-01", "2020-01-15") - "all" 获取完整时间序列 - "latest" 获取最新数据 - `select` (可选): 控制返回字段 - 默认: `["date", "entity", "variable", "value"]` - 备选: `["entity", "variable", "facet"]` 用于检查数据可用性而不获取具体数值 - `filter_facet_domains`: 按数据源域过滤 - `filter_facet_ids`: 按特定分面 (facet) ID 过滤 **响应结构：** 数据按变量 → 实体的层级组织，包含关于 "facets" (数据源) 的元数据，包括： - 来源 URL - 测量方法 - 观测周期 - 导入名称 **使用示例：** python from datacommons_client import DataCommonsClient client = DataCommonsClient() # 获取多个实体的最新人口数据 response = client.observation.fetch( variable_dcids=["Count_Person"], entity_dcids=["geoId/06", "geoId/48"], # 加利福尼亚州和德克萨斯州 date="latest" ) # 获取完整时间序列 response = client.observation.fetch( variable_dcids=["Count_Person"], entity_dcids=["country/USA"], date="all" ) # 使用关系表达式查询层级结构 response = client.observation.fetch( variable_dcids=["Count_Person"], entity_expression="geoId/06<-containedInPlace+{typeOf:County}", date="2020" ) ### 2. fetch_available_statistical_variables() 发现给定实体包含哪些统计变量的数据。 **输入：** 仅实体 DCID **输出：** 按实体组织的可用变量字典 **使用示例：** python # 检查加利福尼亚州有哪些可用变量 available = client.observation.fetch_available_statistical_variables( entity_dcids=["geoId/06"] ) ### 3. fetch_observations_by_entity_dcid() 针对特定实体 DCID 的显式查询方法（功能等同）