{ "openapi": "3.0.1", "info": { "title": "1688.com Products Scraper", "description": "Scrape 1688.com wholesale products by keyword, region or offer ID: tiered prices, MOQ, sales, supplier ratings, factory profile. Export to JSON, CSV or Excel.", "version": "0.0", "x-build-id": "Z6oGqFsc3X67H0MUN" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nice_dev~1688-products-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nice_dev-1688-products-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/nice_dev~1688-products-scraper/runs": { "post": { "operationId": "runs-sync-nice_dev-1688-products-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/nice_dev~1688-products-scraper/run-sync": { "post": { "operationId": "run-sync-nice_dev-1688-products-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", "properties": { "startUrls": { "title": "Start URLs", "maxItems": 1000, "type": "array", "description": "1688 search URLs (`https://s.1688.com/selloffer/offer_search.htm?keywords=...`, the keyword and supported filters are read from the URL, pagination is automatic) or product URLs (`https://detail.1688.com/offer/.html`, `https://m.1688.com/offer/.html`). A product URL is read from its product page, so the **Full product page** price applies, as for Offer IDs. When this list is not empty, the search fields below are ignored. The sort order and the supplier filters of the form (supplier label, business type, dropshipping, free shipping, 48 hours, one per supplier) are added to a search URL that does not already carry them; a filter already in the URL wins. The other filters, caps and monitoring apply to every product. Max 1 000 URLs.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "query": { "title": "Search keyword", "maxLength": 200, "type": "string", "description": "Product to search, in Chinese (best results, e.g. `手机壳`) or English (e.g. `phone case`)." }, "searchQueries": { "title": "More search keywords", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Several keywords in one run: one search per keyword (times each supplier region below). Added to **Search keyword**; products found by several searches are saved once.", "default": [], "items": { "type": "string" } }, "offerIds": { "title": "Offer IDs", "maxItems": 1000, "uniqueItems": true, "type": "array", "description": "1688 product IDs to read directly (the number in `detail.1688.com/offer/.html`). Each ID opens its product page, so the **Full product page** price applies. Can be combined with keywords; to read only these IDs, empty **Search keyword** (the form pre-fills one).", "default": [], "items": { "type": "string" } }, "location": { "title": "Supplier region", "maxLength": 50, "type": "string", "description": "Supplier province or city, in Chinese, as on 1688 (e.g. `广东` Guangdong, `浙江` Zhejiang, `深圳` Shenzhen, `东莞` Dongguan). A city is searched inside its province. Empty = all of China." }, "locations": { "title": "More supplier regions", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Several provinces or cities in one run: every keyword is searched in every region (3 keywords × 4 regions = 12 searches, max 500). Added to **Supplier region**.", "default": [], "items": { "type": "string" } }, "maxItems": { "title": "Max products", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of products to save for the whole run (after deduplication and filters). 0 = no limit. 1688 shows at most 2 000 products per search: above that, the Actor splits the search into price bands by itself.", "default": 100 }, "maxItemsPerQuery": { "title": "Max products per search", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Cap for EACH search (keyword × region, or search URL), so that the first search cannot use up the whole **Max products** budget. 0 = no per-search cap.", "default": 0 }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "bestSelling", "priceAsc", "priceDesc" ], "type": "string", "description": "Order of the 1688 results.", "default": "relevance" }, "priceMin": { "title": "Min unit price (CNY)", "minimum": 0, "maximum": 10000000, "type": "number", "description": "Only products whose unit price is at least this, in Chinese yuan. Empty = no minimum." }, "priceMax": { "title": "Max unit price (CNY)", "minimum": 0, "maximum": 10000000, "type": "number", "description": "Only products whose unit price is at most this, in Chinese yuan. Empty = no maximum." }, "minOrderQuantity": { "title": "Max minimum order (MOQ)", "minimum": 1, "maximum": 100000000, "type": "integer", "description": "Only products whose minimum order quantity is at most this many units (find suppliers that sell small quantities). Empty = no limit." }, "merchantType": { "title": "Supplier tier", "enum": [ "any", "superFactory", "verifiedMerchant", "sourceFlagship" ], "type": "string", "description": "1688 supplier label.", "default": "any" }, "businessType": { "title": "Business type", "enum": [ "any", "manufacturer", "wholesaler", "agent", "service" ], "type": "string", "description": "Kind of company that sells the product.", "default": "any" }, "dropshipOnly": { "title": "Dropshipping only (一件代发)", "type": "boolean", "description": "Only products the supplier ships one by one to your customers.", "default": false }, "freeShippingOnly": { "title": "Free shipping only (包邮)", "type": "boolean", "description": "Only products with free shipping inside China.", "default": false }, "ships48hOnly": { "title": "Ships within 48 h only", "type": "boolean", "description": "Only products the supplier promises to ship within 48 hours.", "default": false }, "onePerSupplier": { "title": "One product per supplier", "type": "boolean", "description": "Keep 1688's best match per supplier: more different suppliers in the same number of results. Above 2,000 products a search is read in price ranges: one product per supplier in each range.", "default": false }, "extractDetails": { "title": "Full product page (paid add-on)", "type": "boolean", "description": "Open each product page for the full photo gallery, video, all attributes (material, size, model...), stock, MOQ, shipping origin and delivery promise, after-sales services and description link. Charged per product read this way (see Pricing). Off = search-result fields only.", "default": false }, "includeSupplierDetails": { "title": "Factory profile (paid add-on)", "type": "boolean", "description": "Add the supplier's factory profile: founding date, staff, production equipment, certifications, ranking badges, chat response rate and repeat-buyer rate. Read once per supplier and charged per supplier profile (see Pricing).", "default": false }, "includeMarketStats": { "title": "Market statistics per search (paid add-on)", "type": "boolean", "description": "Adds one sheet of figures per search: products and suppliers, lowest, median, highest and average price, median minimum order, share of factories, share of verified suppliers, top 10 provinces, units sold and share of paid ads. One sheet per search, price ranges merged. Worked out from the products this run delivers (with Only new products, the new ones only). Find it in Storage → Key-value store → `MARKET_STATS`, or in the Output tab. Charged per sheet delivered (see Pricing).", "default": false }, "includeReviews": { "title": "Include buyer reviews", "type": "boolean", "description": "Add each product's buyer reviews to its row (`reviews`): stars, text, date, variant and quantity bought, photos, buyer nickname, level and province, plus a summary of the ratings (`reviewSummary`: positive rate, grade, counts by type, top tags). The reviews are inside the product row, not rows of their own. Charged per review delivered (event `review`).", "default": false }, "maxReviewsPerProduct": { "title": "Max reviews per product", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Reviews kept per product, in 1688's default order. Read 10 at a time.", "default": 20 }, "reviewFilter": { "title": "Reviews to keep", "enum": [ "all", "photos", "good", "medium", "bad" ], "type": "string", "description": "1688's own review filter: every review, only those with photos, or only the good, medium or bad ones (the buyer's rating).", "default": "all" }, "reviewMinRating": { "title": "Reviews: min stars", "minimum": 1, "maximum": 5, "type": "integer", "description": "Keep only the reviews with at least this many stars (1-5). Empty = all." }, "reviewMaxRating": { "title": "Reviews: max stars", "minimum": 1, "maximum": 5, "type": "integer", "description": "Keep only the reviews with at most this many stars, e.g. 2 for the complaints. Empty = all." }, "reviewKeyword": { "title": "Reviews: word to find", "maxLength": 100, "type": "string", "description": "Keep only the reviews whose text contains this word or phrase (case and accents ignored), e.g. `质量` or `broke`. 1688 cannot filter reviews by text, so the Actor reads more pages to find enough of them. Empty = all." }, "reviewPostedAfter": { "title": "Reviews: posted after", "type": "string", "description": "Keep only the reviews written on or after this date: `2026-03-01`, or a period before now such as `30 days`, `3 months`. Reviews without a readable date are dropped. Empty = all." }, "excludeKeywords": { "title": "Exclude keywords", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Drop the products whose title contains one of these words (case and accents ignored).", "default": [], "items": { "type": "string" } }, "minRating": { "title": "Min supplier service score", "minimum": 0, "maximum": 5, "type": "number", "description": "Only suppliers whose overall 1688 service score (0-5) is at least this. Products of a search without a score are dropped; a product pasted by ID or URL is not checked (the score comes from the search results)." }, "verifiedOnly": { "title": "Audited factories only", "type": "boolean", "description": "Only suppliers whose factory was inspected on site (深度验厂 / 实地验厂). Read from the search results: a product pasted by ID or URL is not checked.", "default": false }, "excludeAds": { "title": "Exclude sponsored results", "type": "boolean", "description": "Drop the paid placements 1688 mixes into the results (they are kept and flagged `isAd` otherwise).", "default": false }, "onlyNew": { "title": "Only new products", "type": "boolean", "description": "Skip the products that a previous run (same **Memory key**) already delivered: they are not saved and not charged, and their page is not even opened. First run = everything is new.", "default": false }, "stateKey": { "title": "Memory key", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "maxLength": 64, "type": "string", "description": "Name of the memory used by **Only new products**. Give each schedule / task its own key (e.g. `phone-cases-guangdong`) so that they do not share their memory. Letters, digits, `-` and `_`.", "default": "default" }, "resetState": { "title": "Reset the memory", "type": "boolean", "description": "Forget everything remembered under this **Memory key** before the run: this run returns (and charges) every product again. Untick it afterwards.", "default": false }, "includePriceChanges": { "title": "Also products whose price changed (paid option)", "type": "boolean", "description": "Also return a product you already received when its price went up or down since your last run, with the previous price, the change in % and the price history. The price followed is the first price step shown on the search card. Needs **Only new products** and the same **Memory key** every run. You pay for each product that comes back. Products pasted by ID or URL are not followed.", "default": false }, "minPriceChangePercent": { "title": "Minimum price change (%)", "minimum": 0, "maximum": 1000, "type": "number", "description": "A product comes back only if its price moved by at least this many % since the last time you received it. 0 = every change.", "default": 3 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy or your own proxies. Keep the default: it is included in the price. The residential Apify proxy is not available in this Actor.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum number of requests processed in parallel.", "default": 8 }, "maxRequestsPerMinute": { "title": "Max requests per minute", "minimum": 10, "maximum": 2000, "type": "integer", "description": "Most requests to the site in any 60 seconds, all of them counted: results pages, product pages and supplier profiles. A budget, not an even pace: up to this many can leave at once when the minute starts (spread them with the minimum delay below). Lower it if the log shows many refused requests.", "default": 120 }, "minRequestIntervalMs": { "title": "Min delay between requests", "minimum": 0, "maximum": 60000, "type": "integer", "description": "Smallest gap between two requests, in milliseconds. Unlike the per-minute rate, this spreads the requests evenly instead of letting them go out in a burst. 0 = no gap.", "default": 0 }, "maxRequestRetries": { "title": "Max request retries", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retries per request before it is marked as failed. Behind a proxy, a request the site turns away is also retried on a new proxy session up to 10 times without using up these retries.", "default": 5 }, "debugLog": { "title": "Debug log", "type": "boolean", "description": "Include debug messages in the run log.", "default": false } } }, "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 } } } } } } } } } }