API 概述

开放 API 是一组基于 HTTPS 的 JSON 接口，用 API Key 认证。本页是所有接口共用的约定；各接口的参数与返回见下方的接口页。

Base URL

https://maxaeo.cn/geoapi/geodata/developer

所有端点都在这个地址下。代码里通常把它存成 BASE_URL，再拼上各接口的路径（如 /task/submit）。

接口列表

接口	完整端点	说明
查询平台列表	`POST https://maxaeo.cn/geoapi/geodata/developer/platforms/get`	已开放的平台、单价、状态与近 24 小时统计
提交任务	`POST https://maxaeo.cn/geoapi/geodata/developer/task/submit`	向指定平台提问，返回 `task_id`
查询任务	`POST https://maxaeo.cn/geoapi/geodata/developer/task/get`	按 `task_id` 读取任务状态与结果
任务列表	`POST https://maxaeo.cn/geoapi/geodata/developer/task/key/list`	列出当前 Key 提交的任务，用于找回 `task_id`
MCP 服务器	`POST https://maxaeo.cn/geoapi/geodata/developer/mcp`	MCP Streamable HTTP 入口，把上面四个接口包装成工具

所有接口返回或操作的任务结构见任务对象。同样的四项能力也以 MCP 工具的形式提供，见接入 MCP。

对接流程

一次完整的对接只用到这四个接口，按下面的顺序串起来：

步骤	调用	要做的事
1. 选平台	`POST https://maxaeo.cn/geoapi/geodata/developer/platforms/get`	取 `platform` 标识与单价，跳过 `platform_status` 为 `maintenance` 的平台；可以缓存几分钟，不要写死在代码里
2. 提交	`POST https://maxaeo.cn/geoapi/geodata/developer/task/submit`	传 `platform`、`query`（可选 `priority`、`thinking`、`country`）；拿到 `task_id` 立即保存
3. 轮询	`POST https://maxaeo.cn/geoapi/geodata/developer/task/get`	每 15 秒左右查一次未结束的任务，直到 `status` 为 `succeeded`、`failed` 或 `canceled`
4. 取结果	同上	`succeeded`：读 `answer` 和 `raw_result.references`；`failed` / `canceled`：按 `error_code` 处理，不扣费
5. 异常兜底	`POST https://maxaeo.cn/geoapi/geodata/developer/task/key/list`	提交超时、断连或返回 `-1` 时，按问题文本和时间找回 `task_id`，确认没有创建再重新提交

判断成败分两层：响应体的 ret 不为 1 表示这次调用没有被受理（不会创建任务）；任务是否成功看 status，失败原因看 error_code。见错误处理。可运行的完整代码见快速开始。

请求

方法：所有接口都用 POST。
请求头：
- Authorization: Bearer <API Key>（必填，见认证与 API Key）
- Content-Type: application/json（建议）
请求体：一个 JSON 对象，不超过 64 KiB。没有参数的接口也要传 {}，空请求体会返回 1001。
只接受已定义的字段：请求体中出现接口未定义的字段（包括拼写错误，如把 task_id 写成 taskId），整个请求返回 1001「请求包含不支持的字段」，不会被静默忽略。
编码：UTF-8。

curl -X POST "https://maxaeo.cn/geoapi/geodata/developer/task/get" \
  -H "Authorization: Bearer $MAXAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23"}'

响应

所有接口的响应体结构相同。成功时 ret 为 1，业务数据在 data.ent：

{
  "ret": 1,
  "data": {
    "ent": { "task_id": "task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23", "status": "queued" }
  }
}

失败时 ret 为错误码，msg 是一个 JSON 字符串，包含中英文两种提示：

{
  "ret": 1001,
  "msg": "{\"zh\":\"参数错误：task_id 不能为空且不超过 64 个字符\",\"en\":\"Invalid parameters: task_id is required and must be at most 64 characters\"}"
}

要点：

用 ret 判断成败。 业务成功和业务失败的 HTTP 状态码都是 200。非 200 只在两种情况出现：请求本身写错（方法不是 POST 返回 405，路径写错返回 404），或请求在网络链路上出错（如代理超时）。处理方式见错误处理。
响应体始终是 JSON，但响应头的 Content-Type 目前可能是 text/plain。请直接把响应体按 JSON 解析，不要依赖 Content-Type 判断。
所有响应都带 Cache-Control: no-store，请不要在客户端或代理层缓存。
全部错误码见错误处理。

字段与数据类型

约定	说明
字段命名	请求与响应字段使用下划线风格，如 `task_id`、`created_at`。例外：`raw_result` 内部使用小驼峰，见任务对象
时间戳	Unix 时间戳，单位秒，`0` 表示尚未发生（如未结束任务的 `finished_at`）
日期	`monitor_date` 为 `YYYY-MM-DD`，按北京时间（UTC+8）
零值	外层字段即使为空也会返回（`""`、`0`、`false`）；`raw_result` 内部的零值字段会被省略
空数组	列表为空时可能返回 `[]` 或 `null`，请统一按空数组处理
新字段	我们可能在响应中新增字段，请让解析代码忽略不认识的字段

认证与安全

API Key 只放在 Authorization 请求头中，不接受放在 URL 或请求体里。
每个请求都会重新校验 Key 的状态；Key 无效统一返回 1030。
只从你的服务端调用。不要在浏览器、小程序或 App 中直接调用开放 API，否则 Key 会暴露给最终用户。

接口页

查询平台列表POST https://maxaeo.cn/geoapi/geodata/developer/platforms/get

提交任务POST https://maxaeo.cn/geoapi/geodata/developer/task/submit

查询任务POST https://maxaeo.cn/geoapi/geodata/developer/task/get

任务列表POST https://maxaeo.cn/geoapi/geodata/developer/task/key/list

任务对象任务与 raw_result 的完整字段定义