Copernicus Climate Data Store (CDS) API 使用指南

CDS API 是一个用于访问 Copernicus Climate Data Store (CDS) 的 Python API，提供了便捷的气候数据访问和下载功能。该项目由欧洲中期天气预报中心（ECMWF）开发维护，采用 Apache 2.0 开源许可证。

项目概述

CDS API 允许用户通过 Python 代码访问和下载 Copernicus 气候数据存储库中的大量气候数据，包括再分析数据、预测数据和其他气候相关数据。该项目使用 Python 作为主要开发语言，依赖 requests、tqdm 和 ecmwf-datastores-client 等库实现功能。

安装配置

环境要求

• Python 3.8 或更高版本
• 有效的 CDS 账户和个人访问令牌

安装步骤

pip install cdsapi

配置认证

在用户主目录下创建 .cdsapirc 配置文件：

url: https://cds.climate.copernicus.eu/api
key: <你的个人访问令牌>

个人访问令牌可以从 CDS 门户网站的个人资料页面获取。

核心功能

数据检索

CDS API 的核心功能是通过 retrieve 方法获取气候数据：

import cdsapi

# 创建客户端实例
cds = cdsapi.Client()

# 检索 ERA5 再分析数据
result = cds.retrieve('reanalysis-era5-pressure-levels', {
    "variable": "temperature",
    "pressure_level": "1000",
    "product_type": "reanalysis",
    "date": "2017-12-01/2017-12-31",
    "time": "12:00",
    "format": "grib"
}, 'download.grib')

服务调用

除了数据检索，CDS API 还支持服务调用：

# 调用工具箱服务
result = cds.service('tool.toolbox.orchestrator.run_workflow', {
    'code': '你的工作流代码',
    'workflow_name': 'application'
})

工作流执行

支持执行复杂的工作流：

# 执行工作流
result = cds.workflow('''
# 工作流定义代码
''', workflow_name='custom_workflow')

高级功能

进度显示

CDS API 内置了进度条显示功能，支持大文件下载时的进度监控：

# 启用进度显示
cds = cdsapi.Client(progress=True)

错误重试机制

API 内置了完善的错误重试机制，支持网络中断自动恢复：

# 配置重试参数
cds = cdsapi.Client(
    retry_max=500,      # 最大重试次数
    sleep_max=120,      # 最大等待时间
    timeout=60          # 请求超时时间
)

结果处理

检索结果支持多种处理方式：

# 直接下载到文件
result.download('output_file.grib')

# 获取结果元数据
content_length = result.content_length
content_type = result.content_type
download_url = result.location

使用示例

ERA5 数据检索

import cdsapi

cds = cdsapi.Client()
cds.retrieve('reanalysis-era5-single-levels', {
    'product_type': 'reanalysis',
    'variable': '2m_temperature',
    'year': '2023',
    'month': '01',
    'day': '01',
    'time': '12:00',
    'format': 'netcdf'
}, 'era5_temperature.nc')

冰川数据下载

cds.retrieve('satellite-glacier-elevation-mass', {
    'variable': 'elevation_change',
    'sensor': 'icesat',
    'version': '1',
    'format': 'netcdf'
}, 'glacier_data.nc')

调试和日志

CDS API 提供了详细的日志功能：

# 启用调试模式
cds = cdsapi.Client(debug=True)

# 自定义日志回调
def my_info_callback(message):
    print(f"INFO: {message}")

cds = cdsapi.Client(info_callback=my_info_callback)

注意事项

1. 数据使用条款：在使用任何数据集前，必须同意相应的条款和条件
2. 配额限制：CDS 对数据下载有配额限制，请合理规划数据请求
3. 网络稳定性：大文件下载建议在网络稳定的环境下进行
4. 错误处理：API 内置了完善的错误处理机制，建议启用重试功能

技术支持

CDS API 项目提供了完善的文档和示例代码，开发者可以通过以下方式获取支持：

• 查阅项目文档和示例代码
• 参考 CDS 官方文档
• 查看项目中的测试用例了解使用方法

通过 CDS API，研究人员和开发者可以方便地访问和处理 Copernicus 气候数据存储库中的丰富气候数据，为气候研究和应用开发提供有力支持。