批量下载任务

1. 基础信息

• Base URL：https://api.mirror-earth.com
• 鉴权方式：API Key（无需登录）
• 请求头：
  • X-API-Key: <apikey>
  • Content-Type: application/json

---

2. 获取 API Key

API Key 在个人中心查看。请妥善保存，不要泄露。

---

3. 接口列表

• 创建任务：POST /api/tasks/export
• 预估任务：POST /api/tasks/estimate
• 获取任务列表：GET /api/tasks
• 获取任务状态：GET /api/tasks/:task_id/status
• 取消任务：POST /api/tasks/:task_id/cancel
• 删除任务：DELETE /api/tasks/:task_id

---

4. 鉴权方式

4.1 Header

X-API-Key: <apikey>

---

5. 创建任务

5.1 请求

POST /api/tasks/export

请求头：

X-API-Key: <apikey>
Content-Type: application/json

请求体示例：

{
  "domain": "era5_seamless",
  "hourly": ["dew_point_2m"],
  "daily": [],
  "monthly": [],
  "time_range": {
    "type": "date_range",
    "start": "2025-08-01",
    "end": "2025-08-10"
  },
  "area": {
    "type": "grid",
    "lat_min": 30.0,
    "lat_max": 40.0,
    "lon_min": 110.0,
    "lon_max": 120.0
  },
  "time_resolution": "hourly",
  "timezone": "Asia/Shanghai",
  "area_average": false
}

5.2 字段说明（关键字段）

{
  "domain": "ecmwf_ifs",           // 必填：数据模型，详见13
  "hourly": ["temperature_2m"],    // 可选：小时变量列表（与 daily, monthly 互斥）
  "daily": [],                     // 可选：日变量列表（与 hourly, monthly 互斥）
  "monthly": [],                   // 可选：月变量列表（与 hourly, daily 互斥）
  "time_range": {                  // 必填：时间范围
    "type": "date_range",          // date_range 或 forecast
    "start": "2025-01-01",         // date_range 时必填
    "end": "2025-01-31",           // date_range 时必填
    "start_hour": "2025-11-01T00:00", // forecast 时必填
    "forecast_hours": 72           // forecast 时必填
  },
  "area": {                        // 必填：空间范围
    "type": "grid",                // grid 或 point

    // === grid 类型参数 ===
    "lat_min": 30.0,               // grid 时必填
    "lat_max": 40.0,               // grid 时必填
    "lon_min": 110.0,              // grid 时必填
    "lon_max": 120.0,              // grid 时必填

    // === point 类型参数（二选一）===
    "adcodes": [                   // 可选：行政区划代码列表（推荐）
      "110000",                    //   北京
      "310000",                    //   上海
      "440000"                     //   广东
    ],
    "locations": [                 // 可选：经纬度列表
      {
        "id": "1",
        "name": "北京",
        "lat": 39.9,
        "lon": 116.4
      },
      {
        "id": "2",
        "name": "上海",
        "lat": 31.2,
        "lon": 121.5
      }
    ]
  },
  "timezone": "Asia/Shanghai",     // 可选：默认 UTC
  "area_average": false,           // 可选：默认false，下载区域平均数据的时候设置为true
}

5.3 响应示例

{
  "code": 0,
  "message": "任务创建成功",
  "data": {
    "task_id": "515afcc8-8542-40af-a503-69b54190a5a6",
    "status": "pending"
  }
}

---

6. 预估任务

POST /api/tasks/estimate

请求体与创建任务相同，用于估算数据量与限制。

---

7. 获取任务列表

GET /api/tasks?page=1&page_size=20&status=processing

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "tasks": [],
    "total": 0,
    "page": 1,
    "page_size": 20
  }
}

---

8. 获取任务进度

GET /api/tasks/:task_id/status

{
  "code": 0,
  "data": {
    "status": "completed",
    "progress_precent": 100,
    "output_file": "126ad0ec-ddf1-4735-a297-a3b3ca61c26f.zip"
  },
  "message": "success"
}

关键字段：

• status：pending | processing | completed | failed | cancelled
• progress_percent：0~100
• output_file：输出文件

9. 下载任务结果

当获取任务状态为completed的时候，可以下载任务结果文件，获取output_file字段，然后拼接： https://api.mirror-earth.com/user_downloads/<output_file>

---

10. 取消任务

POST /api/tasks/:task_id/cancel

仅允许取消 pending 或 processing 状态。

---

11. 删除任务

DELETE /api/tasks/:task_id

仅允许删除 completed / failed / cancelled 状态。

---

12. 常见错误

• 401 未授权：API Key 缺失或无效
• 403 无权访问：任务不属于该用户
• 404 任务不存在

---

13. 可用数据模型(domain)

13.1 预报模型

13.2 历史预报模型

13.3 历史观测/再分析模型