AliExpress API endpoint
Returns the AliExpress web category ids that its own product cards carry on one listing page, with each id's parent, depth and full category path. Pass q to discover the categories of products matching a keyword, or category_id to inspect one category listing. Pass exactly one of them. The ids are the same web category ids used in /category/<id>/<slug>.html URLs and by the search endpoint's cat_id parameter; they are NOT the platform/taxonomy ids returned by the categories endpoint. A parent category listing contains products from its descendants, so inspecting a category reveals its child ids, and every returned path names that id's ancestors: the value space is discoverable by walking from a keyword or a category id rather than guessing.
/aliexpress/category-idsMCP tool: aliexpress_category_ids
Returns the web category ids AliExpress itself attaches to the product cards
on one listing page, together with each id's parent, depth and full category
path. This is the discovery endpoint for the id namespace that
aliexpress_category_products and the
cat_id parameter of aliexpress_search accept.
These are not the ids aliexpress_categories
returns: those are platform/taxonomy ids in a different namespace and do not
resolve to a category listing.
Query parameters — pass exactly one of q or category_id:
q: free-text keywords, e.g. wireless earbuds. The returned ids are the
web categories of the products that keyword returned.category_id: an AliExpress web category id, the number in a
/category/<id>/<slug>.html URL, e.g. 44 or 5090301. The returned ids are
the categories of the products that listing returns.page (optional): 1-indexed listing page to inspect, 1 through 60;
defaults to 1. Each page carries up to 60 products and therefore several
category paths.Response:
source: search when q selected the page, category when category_id
did.category_id / query: the request echoed back.page, total_results, count, source_url, fetched_at.categories[]: every distinct web category id observed on the page.
category_id: the id, usable as category_id on
aliexpress_category_products and as
cat_id on aliexpress_search.parent_id: the immediately shallower id in the observed path; omitted for
a top-level element.level: 1-based position in the path (1 = top-level display category).leaf: true when the id is a product's post category (the last element of
at least one observed path).product_hits: how many cards on this page cite the id in their path.path: the full observed breadcrumb this id appeared in.paths[]: each distinct breadcrumb with its leaf_id, depth and
products count, ordered by products descending.How to walk the category tree instead of guessing ids:
q) or a known id.category_id=<observed id> inspects that
category's listing. A parent category's listing contains products from its
descendants, so new child ids appear; repeat to go deeper.aliexpress_category_products, or any
observed id as cat_id on aliexpress_search.Notable behavior:
/category/<id>/<slug>.html. The last path element is the product's post
category. Some post categories have no products in the sampled page, and a
category listing for them can legitimately report zero results; an accepted id
is not a promise that the category currently has products.503 rather than as
an empty success.page is an upstream contract
break, not an empty success.Errors:
400 when both q and category_id are supplied or neither is, when
category_id is not a positive web category id, when q is longer than 120
characters, or when page is outside 1-60. These are rejected before any
upstream request.503 when the listing page cannot be used: a bot challenge page, a malformed
embedded payload, or a page that reports results but carries no product cards
or no category path.| Field | Filled in, of 1 checked | Values in the sample |
|---|---|---|
| path | 1 | median 3 entries |
| leaf_id | 1 | |
| depth | 1 | 3 |
| products | 1 | 60 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | No | Free-text keywords whose result cards' web category ids are returned; pass exactly one of q or category_id | wireless earbuds | |
| category_id | integer | No | AliExpress web category id whose listing is inspected; a parent category reveals its descendants' ids. Pass exactly one of q or category_id | 44 | |
| page | integer | No | 1 | 1-indexed listing page to inspect (1-60), defaults to 1 | 1 |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/aliexpress/category-ids?q=coffee&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"source": "category",
"category_id": 5090301,
"page": 1,
"total_results": 601,
"count": 2,
"categories": [
{
"category_id": 509,
"level": 1,
"leaf": false,
"product_hits": 60,
"path": [
509,
5090301
]
},
{
"category_id": 5090301,
"parent_id": 509,
"level": 2,
"leaf": true,
"product_hits": 60,
"path": [
509,
5090301
]
}
],
"paths": [
{
"path": [
509,
5090301
],
"leaf_id": 5090301,
"depth": 2,
"products": 60
}
],
"source_url": "https://www.aliexpress.com/category/5090301/products.html",
"fetched_at": "2026-10-26T09:00:00Z"
}
}Request schema
No body schema
Response schema
#/definitions/aliexpress.categoryIDsResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | aliexpress.CategoryIDsResponse | No | ||||
| data.categories | array | No | ||||
| data.categories[].category_id | integer | No | 5090301 | |||
| data.categories[].leaf | boolean | No | Leaf is true when this id is a product's post category (the last element of at least one observed path). | |||
| data.categories[].level | integer | No | 2 | Level is the 1-based position in the observed path (1 = top-level display category). | ||
| data.categories[].parent_id | integer | No | 509 | ParentID is the immediately shallower id in the observed path; omitted for a path's top-level element. | ||
| data.categories[].path | array | No | 509,5090301 | Path is the full observed breadcrumb this id was seen in. | ||
| data.categories[].product_hits | integer | No | 60 | ProductHits counts cards on this page whose path contains the id. | ||
| data.category_id | integer | No | 5090301 | CategoryID echoes the requested category id, when one was supplied. | ||
| data.count | integer | No | 3 | |||
| data.fetched_at | string | No | ||||
| data.page | integer | No | 1 | |||
| data.paths | array | No | ||||
| data.paths[].depth | integer | No | ||||
| data.paths[].leaf_id | integer | No | ||||
| data.paths[].path | array | No | ||||
| data.paths[].products | integer | No | ||||
| data.query | string | No | wireless earbuds | Query echoes the requested keywords, when q was supplied. | ||
| data.source | string | No | category | Source is "search" when q selected the page, "category" when category_id did. | ||
| data.source_url | string | No | ||||
| data.total_results | integer | No | 601 | |||
| 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/category-ids?q=coffee&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"