AliExpress API endpoint
Returns one page (up to 60 products) of public keyword search results with product ids, titles, links, images, prices, ratings, sold text, discount, SKU id, ship-from country, and store name when AliExpress lists them. Results can be sorted and filtered by price, free shipping, the Choice program, and product attributes; list the attribute values for a keyword with the search-filters endpoint. The search uses the anonymous US English/USD locale. Product-detail pages are currently unavailable through the supported HTTP profiles.
/aliexpress/searchq (required): free-text product keywords.page (optional): 1-indexed page from 1 through 60 (AliExpress serves nothing deeper); defaults to 1.sort (optional): one of best_match (default), orders (most sold first), price_asc, price_desc. Any other value returns 400.min_price (optional): minimum price in USD, from 0 through 1000000.max_price (optional): maximum price in USD, from 0 through 1000000; must not be below min_price.free_shipping (optional): true keeps only free-shipping products.choice (optional): true keeps only products in AliExpress's Choice program.attr (optional): product-attribute filter written <attributeId>-<valueId>, for example 3079-4148335 (Main color: Black). Comma-separate up to 5 values, at most one per attribute group. Copy values from /aliexpress/search-filters called with the same q.cat_id (optional): search within one AliExpress web category. This is
the number in a /category/<id>/<slug>.html URL (for example 5090301 for
Cellphones) — note that aliexpress_categories returns taxonomy/platform ids,
a different namespace that is not interchangeable with web category ids.
Discover web ids with aliexpress_category_ids
(q for a keyword, or category_id to walk the tree).
Omit it to search the whole site; the site-wide default the endpoint has always
sent is catId=0.Each page currently contains up to 60 product cards. Search results use the anonymous US English/USD locale so prices and shipping region do not vary by location. Product pages linked in the results are not currently supported by this integration.
Notes on the filters:
total_pages is capped at 60, the deepest page AliExpress serves (measured 2026-10-26: pages 61 and beyond return a fixed fallback page). total_results is AliExpress's own estimate and moves between identical requests; do not use it as a stable count. A filter combination with no matches returns count: 0.attr value that does not belong to the q it is sent with is not rejected by AliExpress; it returns a loosely related, unfiltered-looking result set. Always take attr values from search-filters for the same q. A total_results of exactly 60 with a full first page was seen both for an unknown attr value and for a keyword with no real match, so treat that combination as a degraded result.store_name is present only on some cards. ship_from, sku_id, and discount_percent are present when AliExpress lists them.| Field | Filled in, of 60 checked | Values in the sample |
|---|---|---|
| product_id | 60 | |
| title | 60 | median 124 characters |
| url | 60 | aliexpress.com |
| image_url | 60 | ae-pic-a1.aliexpress-media.com |
| price | 60 | 0.33 to 2,476.59, median 6.03 |
| currency_code | 60 | |
| original_price | 59 | 2.86 to 3,346.75, median 16.85 |
| rating | 49 | 1 to 5, median 4.7 |
| sold_text | 56 | “10,000+ sold” and 30 other values |
| discount_percent | 59 | 9 to 96, median 72 |
| sku_id | 60 | |
| ship_from | 60 | CN (51), US (9) |
| store_name | 26 | “BASEUS Co.,Ltd. Store” and 19 other values |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | Yes | Free-text search keywords | wireless earbuds | |
| page | integer | No | 1 | 1-indexed result page (1-60), defaults to 1 | 1 |
| sort | string | No | Sort order. Allowed values: best_match (default), orders, price_asc, price_desc Allowed values: best_match, orders, price_asc, price_desc. | price_asc | |
| min_price | number | No | Minimum price in USD (0-1000000) | 20 | |
| max_price | number | No | Maximum price in USD (0-1000000), not below min_price | 30 | |
| free_shipping | boolean | No | Only free-shipping products | ||
| choice | boolean | No | Only products in AliExpress's Choice program | ||
| attr | string | No | Attribute filter <attributeId>-<valueId>, from the search-filters endpoint for the same q; comma-separate up to 5 values, one per attribute group | 3079-4148335 | |
| cat_id | integer | No | Search within one AliExpress web category id (the number in a /category/<id>/<slug>.html URL); taxonomy ids from the categories endpoint are a different namespace and are not interchangeable | 5090301 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/aliexpress/search?q=wireless+earbuds&page=1&sort=best_match&free_shipping=true&choice=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"query": "wireless earbuds",
"page": 1,
"page_size": 60,
"total_results": 16889,
"total_pages": 60,
"count": 60,
"filters": {
"sort": "best_match"
},
"source_url": "https://www.aliexpress.com/w/wholesale-wireless-earbuds.html?SearchText=wireless+earbuds&catId=0",
"fetched_at": "2026-10-02T00:00:00Z",
"products": [
{
"product_id": "3256812072210872",
"title": "XIAOMI Redmi Airdots 2 Wireless Bluetooth Headset",
"url": "https://www.aliexpress.com/item/3256812072210872.html",
"image_url": "https://ae-pic-a1.aliexpress-media.com/kf/example.jpg",
"price": 2.18,
"currency_code": "USD",
"original_price": 18.33,
"rating": 4.9,
"sold_text": "3,000+ sold",
"discount_percent": 88,
"sku_id": "12000056622341651",
"ship_from": "CN",
"store_name": "Example Store"
}
]
}
}Request schema
No body schema
Response schema
#/definitions/aliexpress.searchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | aliexpress.SearchResponse | No | ||||
| data.count | integer | No | 60 | |||
| data.fetched_at | string | No | ||||
| data.filters | aliexpress.AppliedFilters | No | ||||
| data.filters.attr | array | No | 3079-4148335 | |||
| data.filters.choice | boolean | No | ||||
| data.filters.free_shipping | boolean | No | ||||
| data.filters.max_price | number | No | 30 | |||
| data.filters.min_price | number | No | 20 | |||
| data.filters.sort | string | No | price_asc | |||
| data.page | integer | No | 1 | |||
| data.page_size | integer | No | 60 | |||
| data.products | array | No | ||||
| data.products[].currency_code | string | No | USD | |||
| data.products[].discount_percent | integer | No | 72 | |||
| data.products[].image_url | string | No | https://ae-pic-a1.aliexpress-media.com/kf/example.jpg | |||
| data.products[].original_price | number | No | 18.33 | |||
| data.products[].price | number | No | 2.18 | Price is always emitted, including 0: AliExpress reports real $0/zero-price deals, and omitting the field would make "free" indistinguishable from "no price parsed". This is an intentional payload-contract change. | ||
| data.products[].product_id | string | No | 3256812072210872 | |||
| data.products[].rating | number | No | 4.9 | |||
| data.products[].ship_from | string | No | US | |||
| data.products[].sku_id | string | No | 12000056622341651 | |||
| data.products[].sold_text | string | No | 3,000+ sold | |||
| data.products[].store_name | string | No | PinZhen Store | |||
| data.products[].title | string | No | Wireless Bluetooth Earbuds | |||
| data.products[].url | string | No | https://www.aliexpress.com/item/3256812072210872.html | |||
| data.query | string | No | wireless earbuds | |||
| data.source_url | string | No | ||||
| data.total_pages | integer | No | 282 | |||
| data.total_results | integer | No | 16912 | |||
| 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/search?q=wireless+earbuds&page=1&sort=best_match&free_shipping=true&choice=true" \
-H "x-api-key: $CRAWLORA_API_KEY"