API Key 与鉴权
统一说明 Mirror Earth API、图层、Python SDK 和 MCP 的 API Key 使用方式。
获取 API Key
登录镜像地球开放平台，在个人中心创建或复制 API Key。
请将 API Key 视为密码，不要写入公开源代码、Git 提交、截图、URL 或普通聊天消息。
各产品的鉴权方式
| 产品 | 是否需要 API Key | 推荐传递方式 |
|---|---|---|
| 实时预报、历史数据、历史预报、无缝数据 API | 是 | URL 查询参数 apikey |
| 图层产品 | 是 | URL 查询参数 apikey |
| 批量下载 API | 是 | Header X-API-Key |
| Python SDK | 是 | SDK 的 apikey 参数 |
| MCP / Agent Skills | 天气查询和批量导出需要 | 环境变量 MIRROR_EARTH_API_KEY |
| 地名解析 API | 否 | 无需鉴权 |
HTTP API
普通天气 API 的请求示例：
curl "https://api.mirror-earth.com/v1/forecast?latitude=32&longitude=118&hourly=temperature_2m&apikey=YOUR_API_KEY"图层 URL 示例：
https://api.mirror-earth.com/api/vis/ecmwf/meta?apikey=YOUR_API_KEY&timezone=Asia/Shanghai批量下载 API
批量任务使用请求头鉴权：
X-API-Key: YOUR_API_KEY
Content-Type: application/json详见批量下载接口文档。
Python SDK
from mirrorearth_sdk import forecast_api
result = forecast_api(
longitude="118",
latitude="32",
apikey="YOUR_API_KEY",
hourly="temperature_2m",
)MCP 与 Agent Skills
在客户端或运行环境中设置：
MIRROR_EARTH_API_KEY=YOUR_API_KEY不要把密钥直接写入 MCP 配置文件并提交到仓库。MCP 与 Agent Skills 的配置方式请参考对应的使用 MCP 文章和使用 Agent Skills 文章。
时区和缺失值
- 未传
timezone时，接口返回 UTC 时间；auto会根据经度自动计算时区。 - 缺失数据在 JSON API 中返回
null；历史预报中部分原始缺失值可能以nan表示，请以具体接口说明为准。 - API Key 无效或缺失时，请检查参数名称、密钥状态和请求产品是否需要鉴权。