API Overview

The MaxAEO API is a small set of JSON endpoints over HTTPS, authenticated with an API key. This page covers the conventions every endpoint shares; see the endpoint pages below for parameters and responses.

Base URL

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

Every endpoint lives under this URL. In code you’d usually store it as BASE_URL and append each endpoint’s path (such as /task/submit).

Endpoints

Endpoint	URL	Description
List platforms	`POST https://maxaeo.ai/geoapi/geodata/developer/platforms/get`	Available platforms, with prices, status, and last-24-hour stats
Submit a task	`POST https://maxaeo.ai/geoapi/geodata/developer/task/submit`	Ask a platform a question and get back a `task_id`
Retrieve a task	`POST https://maxaeo.ai/geoapi/geodata/developer/task/get`	Read a task’s status and result by `task_id`
List tasks	`POST https://maxaeo.ai/geoapi/geodata/developer/task/key/list`	List tasks submitted with the current key, e.g. to recover a `task_id`
MCP server	`POST https://maxaeo.ai/geoapi/geodata/developer/mcp`	MCP Streamable HTTP entry point that wraps the four endpoints above as tools

Every endpoint that returns or operates on a task uses the task object. The same four capabilities are also available as MCP tools — see Connect via MCP.

Integration flow

A complete integration uses only these four endpoints, chained in this order:

Step	Call	What to do
1. Pick a platform	`POST https://maxaeo.ai/geoapi/geodata/developer/platforms/get`	Get the `platform` IDs and prices, skipping any whose `platform_status` is `maintenance`; cache for a few minutes rather than hardcoding them
2. Submit	`POST https://maxaeo.ai/geoapi/geodata/developer/task/submit`	Send `platform` and `query` (optionally `priority`, `thinking`, `country`); save the `task_id` as soon as you get it
3. Poll	`POST https://maxaeo.ai/geoapi/geodata/developer/task/get`	Check unfinished tasks about every 15 seconds until `status` is `succeeded`, `failed`, or `canceled`
4. Read the result	Same as above	`succeeded`: read `answer` and `raw_result.references`; `failed` / `canceled`: handle by `error_code`, nothing is charged
5. Recover	`POST https://maxaeo.ai/geoapi/geodata/developer/task/key/list`	If a submission times out, drops, or returns `-1`, look up the `task_id` by query text and time; only resubmit once you’ve confirmed nothing was created

Success is judged on two levels: a ret other than 1 in the response body means the call wasn’t accepted (no task was created); whether a task succeeded is given by its status, with the reason for a failure in error_code. See Error Handling. For complete runnable code, see the Quickstart.

Requests

Method: every endpoint uses POST.
Headers:
- Authorization: Bearer <API key> (required — see Authentication)
- Content-Type: application/json (recommended)
Body: a single JSON object, no larger than 64 KiB. Endpoints without parameters still need {}; an empty body returns 1001.
Only documented fields are accepted: if the body contains a field the endpoint doesn’t define — including typos such as taskId instead of task_id — the whole request fails with 1001 (“The request contains unsupported fields.”) instead of the field being silently ignored.
Encoding: UTF-8.

curl -X POST "https://maxaeo.ai/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"}'

Response

Every endpoint uses the same response envelope. On success, ret is 1 and the payload is in data.ent:

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

On failure, ret is an error code and msg is a JSON-encoded string holding the message in both Chinese and English:

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

Key points:

Check ret, not the HTTP status. Both successful and failed business responses use HTTP 200. You only see a non-200 status in two cases: the request itself is wrong (a method other than POST returns 405, a wrong path returns 404), or something goes wrong on the network path (a proxy timeout, for example) — see Error Handling.
The body is always JSON, but the Content-Type header may currently be text/plain. Parse the body as JSON directly; don’t rely on Content-Type.
Every response carries Cache-Control: no-store. Don’t cache responses in your client or proxies.
See Error Handling for every error code.

Fields and data types

Convention	Details
Field names	Request and response fields use snake_case, such as `task_id` and `created_at`. Exception: fields inside `raw_result` use lowerCamelCase — see The Task Object
Timestamps	Unix timestamps in seconds; `0` means “hasn’t happened yet” (for example `finished_at` on an unfinished task)
Dates	`monitor_date` is `YYYY-MM-DD` in China Standard Time (UTC+8)
Zero values	Top-level fields are always present even when empty (`""`, `0`, `false`); zero-value fields inside `raw_result` are omitted
Empty arrays	An empty list may come back as `[]` or `null` — treat both as an empty array
New fields	We may add fields to responses. Make your parser ignore fields it doesn’t recognize

Authentication and security

Send the API key only in the Authorization header. Keys in the URL or the request body are not accepted.
The key’s status is re-checked on every request; an invalid key always returns 1030.
Call the API only from your server. Calling it directly from a browser or mobile app exposes your key to end users.

Endpoint pages

List platformsPOST https://maxaeo.ai/geoapi/geodata/developer/platforms/get

Submit a taskPOST https://maxaeo.ai/geoapi/geodata/developer/task/submit

Retrieve a taskPOST https://maxaeo.ai/geoapi/geodata/developer/task/get

List tasksPOST https://maxaeo.ai/geoapi/geodata/developer/task/key/list

The task objectFull field reference for tasks and raw_result