How do you scrape AliExpress products via API without getting blocked?
Call ReefAPI's AliExpress endpoints with a query or product id and read structured JSON back. The parts that break DIY scrapers are not the fetch: they are the destination fields, which silently change what shipping data AliExpress returns at all.
This guide demonstrates the real AliExpress API engine with a captured response from . The example is only published because the engine passed the SEO snapshot gate.
Dropshipping research, price monitoring, catalog enrichment and marketplace analytics.
Call the live endpoint
- 1
Search, or go straight to a product id
aliexpress/v1/search takes a query; aliexpress/v1/product_detail takes product_id or url. Both accept country, language, province and city.
- 2
Always send a destination
country alone is enough for most items. Add province when you need an accurate delivery estimate, or when an item ships from a local warehouse rather than from China.
- 3
Branch on free, not on shipping_cost
Check shipping.free first. null means unknown for that destination - do not fall back to zero, and do not present it as free.
- 4
Read tags.scene_type for the badge
ONLY_CHOICE, LOCAL_PLUS or ONLY_POP. choice and local_plus are never both true because they come from the same source field.
- 5
Check meta before charging downstream jobs
meta.record_count, latency_ms, province_sent and language_sent tell you what was actually asked and answered.
Copy the request
These snippets use the captured request params for aliexpress/v1/search.
curl -X POST https://api.reefapi.com/aliexpress/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"wireless earbuds","country":"US","currency":"USD"}'import requests
r = requests.post(
"https://api.reefapi.com/aliexpress/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "wireless earbuds",
"country": "US",
"currency": "USD"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/aliexpress/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "wireless earbuds",
"country": "US",
"currency": "USD"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.aliexpress.search with {"query":"wireless earbuds","country":"US","currency":"USD"}.Captured output from ReefAPI
Captured on UTC. The response below is the committed snapshot, including the API envelope and metadata.
{
"method": "POST",
"url": "https://api.reefapi.com/aliexpress/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "wireless earbuds",
"country": "US",
"currency": "USD"
}
}{
"ok": true,
"meta": {
"api": "aliexpress",
"endpoint": "search",
"mode": "live",
"latency_ms": 8950.3,
"record_count": 58,
"bytes": 506781,
"cache_hit": false,
"version": "0.1",
"page": 1,
"surface": "search_json",
"related_searches_unavailable": "not served by the search-pc endpoint",
"pagination": {
"page": 1,
"has_more": true
},
"charged_credits": 1
},
"data": {
"query": "wireless earbuds",
"country": "US",
"currency": "USD",
"results": [
{
"product_id": "3256811621288203",
"title": "2026 New Air 3【 Pro 3 】 Bluetooth Wireless Earbuds with Heart Rate Monitoring, Active Noise Cancellation Headphones, Waterproof for Daily Use, For IPhone IOS Smartphone, Gaming /Sports /Fitness Earphones.",
"url": "https://www.aliexpress.com/item/3256811621288203.html",
"image": "https://ae-pic-a1.aliexpress-media.com/kf/Sa57a4580c1274b01988d5df3fa8e76cbx.jpg",
"images": [
"https://ae-pic-a1.aliexpress-media.com/kf/Sa57a4580c1274b01988d5df3fa8e76cbx.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/Sd4e396cd1abe4e8abdd18af12559e993Y.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/S5aa455871a95472c965645aeb8b56df35.jpg"
],
"price": 21.13,
"original_price": 57.24,
"currency": "USD",
"discount_pct": 63,
"price_formatted": "US $21.13",
"sold_count": 4000,
"sold_text": "4,000+ sold",
"rating": 4.9,
"store_name": null,
"store_url": null,
"product_type": "natural",
"promo_tags": [
"New shoppers save $36.11"
],
"sku_id": "12000056622341651"
},
{
"product_id": "3256812118108361",
"title": "Wireless Headphones Bluetooth HTC NE70 Earphones Microphones Earbuds AI Translator 30Hours of Battery Life Full HD LCD Display",
"url": "https://www.aliexpress.com/item/3256812118108361.html",
"image": "https://ae-pic-a1.aliexpress-media.com/kf/Sf103732ee58841f8bbeb48c5e6170acfg.jpg",
"images": [
"https://ae-pic-a1.aliexpress-media.com/kf/Sf103732ee58841f8bbeb48c5e6170acfg.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/S32e8b3ffa8f34715bb580676f8c2d50bx.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/Sd1f37cfd59c74f5890c15273e24d6686g.jpg"
],
"price": 18.2,
"original_price": 50,
"currency": "USD",
"discount_pct": 63,
"price_formatted": "US $18.20",
"sold_count": 4000,
"sold_text": "4,000+ sold",
"rating": 4.9,
"store_name": null,
"store_url": null,
"product_type": "natural",
"promo_tags": [
"New shoppers save $31.8"
],
"sku_id": "12000058017941531"
},
{
"product_id": "3256811844384040",
"title": "Bluetooth TWS Gaming Earphones Low Latency Wireless In-Ear Headphones With Built-in Mic LED Indicator Lights",
"url": "https://www.aliexpress.com/item/3256811844384040.html",
"image": "https://ae-pic-a1.aliexpress-media.com/kf/Sb270915bc0a64740a6cc734578b5500c6.jpg",
"images": [
"https://ae-pic-a1.aliexpress-media.com/kf/Sb270915bc0a64740a6cc734578b5500c6.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/S41fa65f3cde643b6b5e9c043ae5447d6g.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/S96df2ff2dbc542a78a2cea5b5f0e1b1b4.jpg"
],
"price": 4.62,
"original_price": 23.57,
"currency": "USD",
"discount_pct": 80,
"price_formatted": "US $4.62",
"sold_count": 1000,
"sold_text": "1,000+ sold",
"rating": 4.9,
"store_name": null,
"store_url": null,
"product_type": "natural",
"promo_tags": [
"New shoppers save $18.95"
],
"sku_id": "12000057320259387"
}
],
"related_searches": null,
"ranking_searches": null
}
}Why this is hard manually
Most AliExpress write-ups stop at 'it blocks datacenter IPs'. The expensive problems are further in, and they are silent: the response still returns 200 and still looks complete, but a field you depend on is missing or means something other than what you assume.
Destination is the big one. Shipping is not a property of the product, it is a property of the product plus where you are shipping it. Send no destination province and some warehouse-local items return no freight block at all - AliExpress answers 'this product cannot be shipped to your address', even though the same item shows free shipping on the site. We measured this across nine markets on locally warehoused items: adding a sensible default province recovered four products that had been returning nothing, and broke none.
Province values are literal. Plain names resolve ('California', 'Berlin'); two-letter codes do not ('CA', 'NY', 'BE' all failed in our tests). Accents matter too - 'Sao Paulo' made one Brazilian product unreachable where 'Sao Paulo' with the tilde worked.
Then there is free shipping, which AliExpress signals in more than one way. On Choice items the freight is nominally charged and then waived, so naive logic reads it as unknown or as a real charge. Treating 'no freight figure' as 'free' will quietly corrupt any price comparison you build on top.
Why ReefAPI solves it
ReefAPI returns shipping as three explicit states rather than one ambiguous number. free: true means genuinely free and shipping_cost is 0. free: false means there is a real charge and shipping_cost carries it. free: null means AliExpress published no freight figure for that destination - we return null instead of guessing, because a guess here is a wrong price.
Destination is yours to set: country plus an optional province, and the response echoes meta.province_sent so you always know which one was used. Within the US the estimate really does move by state - 3 to 8 days for California against 4 to 14 for Alaska, and some items do not reach Puerto Rico at all.
Language is independent of country, so you can ship to the US and read the content in German. Eleven of twelve languages we tested return localised titles; Chinese often comes back in English because many sellers never publish a Chinese title, which is AliExpress's behaviour rather than ours. We pass your code through untouched and report it back as meta.language_sent.
Two badges come from a single field and are therefore mutually exclusive: tags.choice and tags.local_plus, with tags.scene_type carrying ONLY_CHOICE, LOCAL_PLUS or ONLY_POP. Campaigns arrive as an open set in interest_point - earlyBird is the common one, but full_chain_marketing_card and bulk_purchase_discount also appear, so branch on the code rather than an enum you hard-code.
Measured throughput: 613 requests per minute sustained on product detail. Failed calls are never charged.
Questions developers ask
Do I need an AliExpress account?
No. You call ReefAPI with your x-api-key. No AliExpress account, affiliate key or seller login is involved.
Why is shipping null on some products?
Because AliExpress published no freight figure for that destination. It is not the same as free, and it is not an error. The most common cause is a missing or unrecognised province on an item that ships from a local warehouse - send a province and it usually resolves.
Does the province really change the answer?
Yes, in two ways. It changes the delivery estimate (California 3-8 days against Alaska 4-14), and for warehouse-local items it decides whether any shipping data comes back at all. Use plain names, not two-letter codes.
Can I get prices in one currency but content in another language?
Yes. currency, country and language are independent. Shipping to the US while reading German titles is a valid combination.
What happens if I send a language you do not support?
It falls back to English rather than failing. We pass your code through untouched and report what was sent in meta.language_sent, so an unexpected English response tells you the code was not recognised upstream.
Is Choice the same as Local+?
No, and they cannot both be true. Both are derived from one source field: scene_type is ONLY_CHOICE, LOCAL_PLUS or ONLY_POP.
How fast can I pull?
We measured 613 product-detail requests per minute sustained. Rate limits are set per key; tell us your volume and we will size it.