AliExpress API endpoint
Returns AliExpress's own search-box keyword completions for a query, with a ready-to-use search URL for each suggestion. This is a suggestion/autocomplete surface, not a product feed: the upstream payload contains keyword strings only, so no product id, title, price or seller is returned. AliExpress usually offers 10-12 suggestions; each suggestion's url is the matching AliExpress search page and can be passed to the search endpoint as q.
/aliexpress/suggestMCP tool: aliexpress_suggest
Query parameters:
q (required): partial or full search keywords, for example wireless earbuds. Up to 120 characters.limit (optional): maximum number of suggestions to return, 1 through
20; defaults to 10.Each suggestion is:
keyword: the completed search phrase.url: the AliExpress search page for that phrase, built with the same public
/w/wholesale-<slug>.html?SearchText=... shape aliexpress_search itself
uses, so a suggestion can be followed directly or passed back as q.Notable behavior:
limit above that returns
fewer items rather than erroring.200 with an empty
suggestions list and count: 0.url is derived, not upstream-provided. The suggestion payload carries no
destination URL, so this endpoint builds the same search-page URL the search
endpoint uses. The upstream request URL is never exposed.Errors:
400 for a missing/blank q, an over-long q, or a limit outside 1-20.
These are rejected before any upstream request.503 when AliExpress refuses or cannot serve the request: a bot challenge, a malformed or empty payload, or a transport failure. A transient transport failure is retried once; a challenge is never retried, solved or bypassed.Data source:
Responses are cached for up to 1 hour per query and limit; fetched_at is when AliExpress was last queried.
count is the number of suggestions returned, not a stable upstream total, and
a query with no completions returns "count": 0 with an empty
"suggestions": [].
| Field | Filled in, of 10 checked | Values in the sample |
|---|---|---|
| keyword | 10 | “wireless earbuds” and 9 other values |
| url | 10 | aliexpress.com |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | Yes | Partial or full search keywords to complete | wireless earbuds | |
| limit | integer | No | 10 | Maximum suggestions to return (1-20), defaults to 10 | 10 |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/aliexpress/suggest?q=wireless+earbuds&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"query": "wireless earbuds",
"limit": 10,
"count": 3,
"source_url": "https://www.aliexpress.com/w/wholesale-wireless-earbuds.html?SearchText=wireless+earbuds&catId=0",
"fetched_at": "2026-10-25T10:05:33Z",
"suggestions": [
{
"keyword": "wireless earbuds bluetooth",
"url": "https://www.aliexpress.com/w/wholesale-wireless-earbuds-bluetooth.html?SearchText=wireless+earbuds+bluetooth&catId=0"
},
{
"keyword": "wireless earbuds headphones",
"url": "https://www.aliexpress.com/w/wholesale-wireless-earbuds-headphones.html?SearchText=wireless+earbuds+headphones&catId=0"
},
{
"keyword": "wireless earbuds pro",
"url": "https://www.aliexpress.com/w/wholesale-wireless-earbuds-pro.html?SearchText=wireless+earbuds+pro&catId=0"
}
]
}
}Request schema
No body schema
Response schema
#/definitions/aliexpress.suggestResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | aliexpress.SuggestResponse | No | ||||
| data.count | integer | No | 10 | |||
| data.fetched_at | string | No | ||||
| data.limit | integer | No | 10 | |||
| data.query | string | No | wireless earbuds | |||
| data.source_url | string | No | SourceURL is the gateway operation the suggestions come from. The signed request URL itself is never exposed because it carries a freshly minted token and signature. | |||
| data.suggestions | array | No | ||||
| data.suggestions[].keyword | string | No | wireless earbuds bluetooth | |||
| data.suggestions[].url | string | No | https://www.aliexpress.com/w/wholesale-wireless-earbuds-bluetooth.html?SearchText=wireless+earbuds+bluetooth&catId=0 | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/aliexpress/suggest?q=wireless+earbuds&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"