Search products by keyword
Products matching a keyword, 60 per page, with AliExpress’s own filters: price range, free shipping, four stars and up, Choice only, ship-from country and category. Sort by best match, orders or price. Results are read in the market you pass and echoed as market — the same keyword ranks different products first for a US and a German shopper. AliExpress lists at most 60 pages for one query, so narrow with filters to reach further. Consecutive pages can repeat a product (11 of 60 on one keyword’s second page), so de-duplicate by productId across responses. A search with few matches is padded by AliExpress with loosely related products, and notes says so.
/search-products Products https://api.fetchlayer.dev/aliexpress/search-products Headers
Authorization string required Bearer token — your FetchLayer API key.
Parameters
query string required Keywords to search for (max 200 characters).
categoryId string optional Restrict the search to one category id, as returned on a product.
sort string optional best_match, orders (most sold first), price_asc or price_desc. (default: best_match)
minPrice number optional Lowest price, in the requested currency.
maxPrice number optional Highest price, in the requested currency.
freeShipping boolean optional Only listings with free shipping. (default: false)
fourStarsAndUp boolean optional Only listings rated four stars and up. (default: false)
choiceOnly boolean optional Only AliExpress Choice listings. (default: false)
shipFrom string optional Two-letter country code the item ships from, for example CN, US or ES.
limit number optional Maximum products returned (max 1200), or -1 for the maximum allowed. (default: 60)
pages number optional Pages of 60 to collect in one request (max 20), or -1 for the maximum allowed. Each page counts as one request. (default: 1)
cursor string optional Resume from a previous response's nextCursor.
delayMs number optional Milliseconds to wait between pages (max 30000).
shipTo string optional Two-letter country code the shopper ships to, for example US or DE. Changes prices, shipping and availability. (default: US)
currency string optional Currency prices are returned in: USD, EUR, GBP, CAD, AUD, NZD, BRL, MXN, CLP, COP, PEN, ARS, JPY or KRW. Any other value is a 400. (default: USD)
language string optional Language for titles and labels: en_US, de_DE or pt_BR. Any other value is a 400. (default: en_US)
format string optional json, or markdown to get the result rendered as text. (default: json)
timeoutMs number optional Per-request time limit in milliseconds (max 600000).
Response Fields
search-products
Search products by keyword
query string The keyword searched.
products object[] The matching products, de-duplicated within this response.
products[].productId string Global product id — the handle /product-details, /product-prices and /product-reviews take. US storefront ids are folded into it.
products[].title string Listing title, in the requested language.
products[].url string Public product page URL.
products[].imageUrl string | null Main image. Pass it to /media to download it.
products[].imageUrls string[] Every image shown on the card.
products[].price object | null Current price after the listing discount, the lowest across variants: amount, currency and the price as displayed. Null on new-shopper gift cards, which AliExpress lists without a price.
products[].originalPrice object | null Price before the discount, when one is shown.
products[].discountPercent number | null Discount shown on the card.
products[].rating number | null Average rating out of 5.
products[].soldText string | null Sales label as displayed, for example "10,000+ sold".
products[].soldCount number | null Exact sales where published, otherwise the lower bound of the label.
products[].shipFrom string | null Two-letter country the item ships from.
products[].categoryId string | null Category id — pass it to /category-products or as categoryId on a search.
products[].sponsored boolean A paid placement rather than an organic result.
products[].choice boolean Part of the AliExpress Choice programme.
products[].badges string[] Labels on the card: "Top selling", "Lowest price in 90 days", a delivery window, or the text shown in place of a price on a gift card.
filters object The filters and sort this listing ran with, after defaults were applied.
productCount number Products in this response.
totalResults number | null Matches AliExpress reports for the whole query, before paging.
pagesScraped number Pages actually collected. Each page counts as one request against your plan.
pagesRequested number Pages the request asked for.
nextCursor string | null Pass back as cursor to continue, or null when there is no next page.
hasNextPage boolean Whether more results are available beyond this response.
market object The market this result was read in — shipTo, currency and language — after defaults were applied. Compare prices only between results with the same market.
notes string[] Caveats about this specific result — a walk refused part-way, a padded search, a page repeated by the cursor. Read it before treating a result as complete.
requestedUrl string The AliExpress page this result corresponds to.
scrapedAt string ISO 8601 timestamp of when the data was collected.
resultType string Which shape this response is, e.g. product-search or product-reviews.
transport string The upstream source the data came from: aliexpress.
blocked boolean Always false on a successful response.
Request
curl -X POST "https://api.fetchlayer.dev/aliexpress/search-products" \
-H "Authorization: Bearer ss-your-key" \
-H "Content-Type: application/json" \
-d '{"query":"mechanical keyboard","shipTo":"US","currency":"USD","language":"en_US"}'Response
{
"resultType": "product-search",
"market": {
"shipTo": "US",
"currency": "USD",
"language": "en_US"
},
"notes": [],
"query": "mechanical keyboard",
"productCount": 58,
"totalResults": 16791,
"pagesScraped": 1,
"nextCursor": "eyJwIjoyfQ",
"hasNextPage": true,
"products": [
{
"productId": "1005009494458560",
"title": "AJAZZ NK61 Wired Gaming Mechanical Keyboard 60% RGB Hot-Swappable 61 Keys Red Switch Mini Keyboard for Gamer PC",
"url": "https://www.aliexpress.com/item/1005009494458560.html",
"imageUrl": "https://ae-pic-a1.aliexpress-media.com/kf/S21fa9e98da3547c5a2e840c1917ce9cdI.png",
"price": {
"amount": 16.33,
"currency": "USD",
"formatted": "US $16.33"
},
"originalPrice": {
"amount": 41.14,
"currency": "USD",
"formatted": "US $41.14"
},
"discountPercent": 60,
"rating": 4.7,
"soldText": "10,000+ sold",
"soldCount": 15106,
"shipFrom": "CN",
"categoryId": "70802",
"sponsored": false,
"choice": true,
"badges": [
"Top selling on AliExpress",
"Delivery: Sep 18 - 24"
]
}
]
}