{ "openapi": "3.0.1", "info": { "title": "AliExpress Scraper — Products, Reviews & Review Analytics", "description": "Scrape AliExpress by keyword or category: product details, price, discount, SKUs, images, store and shipping, plus unlimited customer reviews. Then get built-in review analytics — per-review sentiment and aspect themes, with per-product rating distribution, positive/negative rate and top themes.", "version": "0.0", "x-build-id": "YDtkKnczfabi5VaHb" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/brilliant_gum~aliexpress-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-brilliant_gum-aliexpress-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/brilliant_gum~aliexpress-scraper/runs": { "post": { "operationId": "runs-sync-brilliant_gum-aliexpress-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/brilliant_gum~aliexpress-scraper/run-sync": { "post": { "operationId": "run-sync-brilliant_gum-aliexpress-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Modes", "type": "array", "description": "What to scrape. 'search' runs each search term / search URL / category and returns one product record per result. 'product-details' fetches the full product record for each startUrls / productUrls / itemIds entry. 'reviews' paginates customer reviews for the resolved products. Modes can be combined (e.g. search + reviews, or product-details + reviews).", "items": { "type": "string", "enum": [ "search", "product-details", "reviews" ], "enumTitles": [ "Product search", "Product details", "Reviews" ] }, "default": [ "search" ] }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords to search on AliExpress (e.g. \"wireless earbuds\", \"phone case\"). Search mode only. Each term is paginated (60 products per page).", "items": { "type": "string" } }, "searchUrls": { "title": "Search / category URLs", "type": "array", "description": "Ready-made AliExpress search or category URLs (https://www.aliexpress.com/w/wholesale-...html or category pages). Used verbatim and paginated. Advanced alternative to searchTerms.", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "type": "array", "description": "AliExpress URLs to scrape. Product URLs (/item/.html) feed product-details/reviews; search or category URLs are paginated in search mode.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "productUrls": { "title": "Product URLs", "type": "array", "description": "Direct AliExpress product URLs as plain strings (https://www.aliexpress.com/item/.html). Used by product-details and reviews modes.", "items": { "type": "string" } }, "itemIds": { "title": "Item IDs", "type": "array", "description": "Bare numeric AliExpress product IDs (e.g. 1005006976494502). Used by product-details and reviews modes.", "items": { "type": "string" } }, "category": { "title": "Category", "enum": [ "all", "electronics", "phones-accessories", "computers-office", "consumer-electronics", "jewelry-watches", "home-garden", "furniture", "bags-shoes", "mens-clothing", "womens-clothing", "mother-kids", "sports-outdoors", "automotive", "toys-hobbies", "beauty-health", "tools-hardware", "home-appliances" ], "type": "string", "description": "Optional category to narrow keyword search. 'all' searches everything. Combined with searchTerms as a browse filter.", "default": "all" }, "maxItems": { "title": "Max products per query", "minimum": 0, "type": "integer", "description": "Maximum products per search term / search URL. 0 = all available (safety-capped at 3000). Does not limit reviews (see Max reviews).", "default": 0 }, "maxSearchPages": { "title": "Max search pages", "minimum": 0, "type": "integer", "description": "Maximum search result PAGES to fetch per query (60 products per page). 0 = until maxItems reached or no more results.", "default": 0 }, "sortBy": { "title": "Search sort", "enum": [ "default", "orders", "price_asc", "price_desc" ], "type": "string", "description": "Sort order for search results.", "default": "default" }, "minPrice": { "title": "Min price", "minimum": 0, "type": "integer", "description": "Keep only products at or above this price (in the result currency). Passed to AliExpress and applied to output." }, "maxPrice": { "title": "Max price", "minimum": 0, "type": "integer", "description": "Keep only products at or below this price (in the result currency)." }, "shipToCountry": { "title": "Ship-to country", "type": "string", "description": "Two-letter ISO ship-to country code (e.g. US, GB, DE, FR, BR). Controls shipping context and localized pricing. Region and site are handled automatically — a US ship-to still returns USD prices.", "default": "US" }, "currency": { "title": "Currency", "type": "string", "description": "Three-letter currency code for prices (e.g. USD, EUR, GBP).", "default": "USD" }, "language": { "title": "Language / locale", "type": "string", "description": "Language/locale for titles and text (e.g. en_US, de_DE, fr_FR).", "default": "en_US" }, "fetchProductDetails": { "title": "Fetch full product details", "type": "boolean", "description": "In search mode, enrich each result with the full product page (SKU variants, specs, store/seller, shipping, wishlist, full image gallery, per-SKU prices, video, stock, product type). Turn off for a faster/cheaper lightweight card (id, title, url, price, rating, orders, image, sponsored). Alias: enrichListingDetails.", "default": true }, "fetchDescription": { "title": "Fetch product description body", "type": "boolean", "description": "Also fetch and extract the full product description text (and its inline image URLs) from AliExpress's description document. This adds one extra request per product, so it is off by default. Requires product details (search enrichment or product-details mode).", "default": false }, "maxReviews": { "title": "Reviews: max per product", "minimum": 0, "type": "integer", "description": "Maximum reviews per product. 0 = all available (paginates AliExpress's reviews feed).", "default": 0 }, "reviewsSort": { "title": "Reviews: sort", "enum": [ "default", "latest" ], "type": "string", "description": "Review ordering.", "default": "default" }, "reviewsRating": { "title": "Reviews: star filter", "type": "array", "description": "Keep only reviews with these star ratings. Empty = all.", "items": { "type": "string", "enum": [ "5", "4", "3", "2", "1" ], "enumTitles": [ "5 stars", "4 stars", "3 stars", "2 stars", "1 star" ] } }, "reviewsFilter": { "title": "Reviews: type filter", "enum": [ "all", "image", "additional", "local" ], "type": "string", "description": "Which reviews to fetch from AliExpress. 'image' returns only reviews with photos; 'additional' only additional/follow-up reviews; 'local' only local-market reviews.", "default": "all" }, "reviewsFromDate": { "title": "Reviews: from date", "type": "string", "description": "Keep reviews on/after this date (YYYY-MM-DD) or relative like '30 days', '6 months'." }, "reviewsKeywords": { "title": "Reviews: must contain", "type": "array", "description": "Keep only reviews whose text contains any of these keywords.", "items": { "type": "string" } }, "includePersonalData": { "title": "Include reviewer profile data", "type": "boolean", "description": "Include the reviewer's public fields (name, country). Turn off to redact reviewer identity and keep only the anonymous review id.", "default": true }, "includeReviewInsights": { "title": "Review insights roll-up", "type": "boolean", "description": "Emit one 'review-insights' record per product: rating distribution, sentiment breakdown, top aspect themes and recent-negative trend (uses AliExpress's own star statistics).", "default": false }, "reviewSentiment": { "title": "Review sentiment", "type": "boolean", "description": "Add sentiment {score,label} to each review (consumer lexicon + rating prior, no external AI).", "default": true }, "themeExtraction": { "title": "Theme extraction", "type": "boolean", "description": "Tag each review with product aspect themes (quality, value, shipping, ease of use, durability, appearance, size, performance) and polarity.", "default": true }, "deduplicate": { "title": "Deduplicate", "type": "boolean", "description": "Drop records whose dedupKey was already produced (within run, and across runs if a key store is set).", "default": true }, "deduplicateKeyStore": { "title": "Cross-run dedup key store", "type": "string", "description": "Named key-value store to persist seen dedupKeys across scheduled runs. Empty = in-run dedup only." }, "monitoringMode": { "title": "Monitoring mode (new only)", "type": "boolean", "description": "Output only records not seen in the previous run (requires a dedup key store). Great for price/review alerting.", "default": false }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 30, "type": "integer", "description": "Parallel product targets. Keep moderate (3-8) for reliability.", "default": 5 }, "maxChallengeRetries": { "title": "Max challenge retries", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retry attempts per item on temporary failures. Full product detail is occasionally unavailable on a given run; higher values raise the full-detail success rate at the cost of speed.", "default": 8 }, "proxy": { "title": "Proxy", "type": "object", "description": "Proxies are included and configured automatically — leave the default in place.", "default": { "useApifyProxy": true } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }