API रेफ़रेंस

परिचय

AliExpress Reviews API, AliExpress प्रोडक्ट रिव्यू JSON में लौटाता है। यह HTTPS पर एक ही REST endpoint है; हर रिस्पॉन्स, एरर समेत, JSON में होता है।

Base URL: https://api.aliexpress-reviews.com
ऑथ: x-api-key हेडर
फ़ॉर्मैट: JSON, UTF-8

क्विकस्टार्ट: मुफ़्त key बनाएँ, फिर डैशबोर्ड के API टेस्टर में आज़माएँ या यह चलाएँ:

curl "https://api.aliexpress-reviews.com/v1/reviews/1005006123456789?filter=5&pageSize=20" \
  -H "x-api-key: $REVIEWS_API_KEY"

ऑथेंटिकेशन

डैशबोर्ड में एक API key बनाएँ और हर रिक्वेस्ट के x-api-key हेडर में उसे भेजें। Keys rv_ से शुरू होती हैं।

Key सिर्फ़ एक बार, बनाते समय दिखाई जाती है: हम key नहीं, उसका hash सेव करते हैं। अगर यह खो जाए, तो डैशबोर्ड से इसे रोटेट करें; पुरानी key 5 मिनट के भीतर काम करना बंद कर देती है।

Key को सर्वर-साइड ही रखें। जिसके पास भी यह होगी, वह आपका कोटा खर्च कर सकता है।

GET `/v1/reviews/{productId}`

किसी प्रोडक्ट के रिव्यू का एक पेज लौटाता है, साथ में उसकी रेटिंग का सारांश भी।

Path पैरामीटर

नाम	टाइप	विवरण
`productId` ज़रूरी	string	AliExpress का न्यूमेरिक प्रोडक्ट id: `aliexpress.com/item/<id>.html` में मौजूद नंबर।

Query पैरामीटर

नाम	टाइप	डिफ़ॉल्ट	प्लान	विवरण
`page`	integer	`1`	Free	पेज नंबर, 1–1000।
`pageSize`	integer	`20`	Free	हर पेज पर रिव्यू: Free पर 20 तक, Pro और Max पर 100 तक।
`filter`	string	`all`	Free	नीचे दिए गए फ़िल्टर में से एक। कुछ वैल्यू के लिए ऊँचा प्लान चाहिए।
`country`	string	`US`	Pro	खरीदार का देश, ISO 3166-1 alpha-2। तय करता है कि `filter=local` कौन-से रिव्यू लौटाएगा और `local` की गिनती क्या होगी।
`lang`	string	`en_US`	Pro	वह भाषा जिसमें रिव्यू का अनुवाद होता है। `originalContent` में खरीदार का टेक्स्ट रहता है।

अज्ञात पैरामीटर 400 लौटाते हैं। जो पैरामीटर आपके प्लान में शामिल नहीं है, वह 403 लौटाता है, भले ही उसकी वैल्यू डिफ़ॉल्ट हो।

उदाहरण रिक्वेस्ट

curl "https://api.aliexpress-reviews.com/v1/reviews/1005006123456789?filter=5&pageSize=20" \
  -H "x-api-key: $REVIEWS_API_KEY"

const url = new URL('https://api.aliexpress-reviews.com/v1/reviews/1005006123456789');
url.search = new URLSearchParams({ filter: '5', pageSize: '20' }).toString();

const res = await fetch(url, { headers: { 'x-api-key': process.env.REVIEWS_API_KEY } });
if (!res.ok) throw new Error((await res.json()).error.message);
const { summary, data } = await res.json();

import os, requests

res = requests.get(
    "https://api.aliexpress-reviews.com/v1/reviews/1005006123456789",
    params={"filter": "5", "pageSize": 20},
    headers={"x-api-key": os.environ["REVIEWS_API_KEY"]},
)
res.raise_for_status()
body = res.json()

फ़िल्टर

फ़िल्टर वही हैं जो AliExpress प्रोडक्ट पेज पर दिखाता है, और उन्हें AliExpress ही लागू करता है। हर रिक्वेस्ट में एक filter भेजें; इन्हें मिलाया नहीं जा सकता।

वैल्यू	प्लान	लौटाता है
`filter=all`	Free	सभी रिव्यू (डिफ़ॉल्ट)।
`filter=5`	Free	सिर्फ़ 5-स्टार रिव्यू।
`filter=4`	Free	सिर्फ़ 4-स्टार रिव्यू।
`filter=3`	Free	सिर्फ़ 3-स्टार रिव्यू।
`filter=2`	Free	सिर्फ़ 2-स्टार रिव्यू।
`filter=1`	Free	सिर्फ़ 1-स्टार रिव्यू।
`filter=additional`	Pro	अतिरिक्त (फ़ॉलो-अप) फ़ीडबैक वाले रिव्यू।
`filter=local`	Pro	`country` पैरामीटर में दिए गए देश के खरीदारों के रिव्यू।
`filter=image`	Max	फ़ोटो वाले रिव्यू।

रिस्पॉन्स का summary.filterCounts बताता है कि हर फ़िल्टर कितने रिव्यू लौटाएगा, ताकि आप बिना अतिरिक्त रिक्वेस्ट के अपने UI में खाली फ़िल्टर छिपा सकें।

भाषाएँ

lang (Pro) के साथ, content और additionalFeedback AliExpress द्वारा अनुवादित होकर आते हैं। originalContent में हमेशा खरीदार के अपने शब्द रहते हैं।

वैल्यू	भाषा
`en_US`	अंग्रेज़ी
`es_ES`	स्पेनिश
`fr_FR`	फ़्रेंच
`de_DE`	जर्मन
`it_IT`	इतालवी
`pt_BR`	पुर्तगाली (ब्राज़ील)
`nl_NL`	डच
`pl_PL`	पोलिश

रिस्पॉन्स

{
  "productId": "1005006123456789",
  "filter": "all",
  "page": 1,
  "pageSize": 20,
  "total": 452,
  "totalPages": 23,
  "summary": {
    "averageRating": 4.4,
    "totalReviews": 452,
    "ratingDistribution": { "5": 323, "4": 54, "3": 33, "2": 12, "1": 30 },
    "filterCounts": { "all": 452, "image": 32, "additional": 6, "local": 63 }
  },
  "data": [
    {
      "id": "60012345678901234",
      "author": "J***n",
      "country": "ES",
      "rating": 5,
      "content": "Very good quality, arrived in 10 days",
      "originalContent": "Muy buena calidad, llegó en 10 días",
      "additionalFeedback": null,
      "date": "2026-08-09",
      "sku": "Color:Black",
      "helpfulVotes": 3,
      "images": ["https://..."],
      "thumbnails": ["https://..."]
    }
  ]
}

पेज फ़ील्ड

फ़ील्ड	टाइप	विवरण
`productId`	string	मांगा गया प्रोडक्ट।
`filter`	string	लागू किया गया फ़िल्टर।
`page`, `pageSize`	integer	लौटाया गया पेज और उसका मांगा गया साइज़।
`total`	integer	फ़िल्टर से मेल खाने वाले रिव्यू।
`totalPages`	integer	इस `pageSize` के साथ उपलब्ध पेज।
`summary.averageRating`	number \| null	प्रोडक्ट के औसत स्टार, रिव्यू न होने पर `null`।
`summary.totalReviews`	integer	प्रोडक्ट के सभी रिव्यू, फ़िल्टर चाहे जो हो।
`summary.ratingDistribution`	object	हर स्टार के रिव्यू, keys `"1"`–`"5"`।
`summary.filterCounts`	object	हर फ़िल्टर के रिव्यू: `all`, `image`, `additional`, `local` (`country` पर निर्भर)।
`data`	Review[]	इस पेज के रिव्यू।

रिव्यू फ़ील्ड

फ़ील्ड	टाइप	विवरण
`id`	string	AliExpress रिव्यू id।
`author`	string	खरीदार का नाम, AliExpress द्वारा मास्क किया हुआ (जैसे `J***n`)।
`country`	string	खरीदार का देश, ISO 3166-1 alpha-2।
`rating`	integer	स्टार, 1–5।
`content`	string	`lang` में अनुवादित रिव्यू टेक्स्ट।
`originalContent`	string	रिव्यू टेक्स्ट, जैसा खरीदार ने लिखा।
`additionalFeedback`	string \| null	फ़ॉलो-अप फ़ीडबैक, अगर हो।
`date`	string	रिव्यू की तारीख, `YYYY-MM-DD`।
`sku`	string \| null	खरीदार द्वारा खरीदा गया वेरिएंट (जैसे `Color:Black`)।
`helpfulVotes`	integer	कितनी बार दूसरे खरीदारों ने इसे helpful बताया।
`images`	string[]	फ़ुल-साइज़ फ़ोटो के URL। सिर्फ़ Max प्लान।
`thumbnails`	string[]	थंबनेल URL। सिर्फ़ Max प्लान।

Free और Pro पर images और thumbnails शामिल नहीं होते।

पेजिनेशन

page=1, 2, … तब तक रिक्वेस्ट करें जब तक page totalPages तक न पहुँच जाए। हर पेज आपके कोटा में एक रिक्वेस्ट है, इसलिए अपने प्लान में मिलने वाला सबसे बड़ा pageSize इस्तेमाल करें।

async function allReviews(productId, filter = 'all') {
  const reviews = [];
  for (let page = 1; ; page++) {
    const url = `https://api.aliexpress-reviews.com/v1/reviews/${productId}?filter=${filter}&page=${page}`;
    const res = await fetch(url, { headers: { 'x-api-key': process.env.REVIEWS_API_KEY } });
    const body = await res.json();
    reviews.push(...body.data);
    if (page >= body.totalPages) return reviews;
  }
}

रेट लिमिट

प्लान	प्रति दिन रिक्वेस्ट	अधिकतम `pageSize`
Free	100	20
Pro	1,000	100
Max	10,000	100

कोटा 00:00 UTC पर रीसेट होता है। कोटा में गिना जाने वाला हर रिस्पॉन्स (200, 404, 429, 502) ये हेडर लाता है:

हेडर	विवरण
`x-ratelimit-limit`	आपका दैनिक कोटा।
`x-ratelimit-remaining`	आज बची हुई रिक्वेस्ट।
`x-ratelimit-reset`	अगले रीसेट का Unix समय।

400/401/403 के साथ अस्वीकार की गई रिक्वेस्ट गिनी नहीं जातीं। कोटा पार होने पर रीसेट तक आपको 429 मिलता है। इसके अलावा, सभी यूज़र्स के बीच साझा 50 रिक्वेस्ट प्रति सेकंड की एक ग्लोबल लिमिट भी है।

कैशिंग

हर पेज (प्रोडक्ट + पैरामीटर) 24 घंटे तक कैश किया जाता है, इसलिए नए रिव्यू को दिखने में एक दिन तक लग सकता है। कैश किए गए रिस्पॉन्स भी आपके कोटा में गिने जाते हैं।

एरर

एरर स्टैंडर्ड HTTP स्टेटस कोड और JSON बॉडी का उपयोग करते हैं:

{ "error": { "message": "filter=image requires the MAX plan" } }

स्टेटस	मतलब	कोटा में गिना जाता है
`400`	अमान्य या अज्ञात पैरामीटर, या गलत फ़ॉर्मैट वाला प्रोडक्ट id।	नहीं
`401`	`x-api-key` हेडर मौजूद नहीं है।	नहीं
`403`	अमान्य API key, या कोई पैरामीटर या फ़िल्टर जो आपके प्लान में शामिल नहीं है।	नहीं
`404`	AliExpress पर उस id का कोई प्रोडक्ट नहीं है।	हाँ
`429`	दैनिक कोटा पार हो गया, या ग्लोबल रेट लिमिट पूरी हो गई।	—
`502`	AliExpress ने जवाब नहीं दिया। बाद में फिर कोशिश करें।	हाँ

OpenAPI

पूरा स्पेसिफ़िकेशन /openapi.json (OpenAPI 3.0) पर है। इसे Postman, Insomnia या किसी client generator में इम्पोर्ट करें।

API रेफ़रेंस

परिचय

ऑथेंटिकेशन

GET /v1/reviews/{productId}

Path पैरामीटर

Query पैरामीटर

उदाहरण रिक्वेस्ट

फ़िल्टर

भाषाएँ

रिस्पॉन्स

पेज फ़ील्ड

रिव्यू फ़ील्ड

पेजिनेशन

रेट लिमिट

कैशिंग

एरर

OpenAPI

GET `/v1/reviews/{productId}`