{
  "openapi": "3.0.1",
  "info": {
    "title": "1688.com Products Scraper",
    "description": "Scrape 1688.com wholesale products by keyword, image, region or offer ID: tiered prices, MOQ, sales, supplier ratings, factory profile. Export to JSON, CSV or Excel.",
    "version": "0.0",
    "x-build-id": "O0N20LzjCqRIJRWb5"
  },
  "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/<id>.html`, `https://m.1688.com/offer/<id>.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"
            }
          },
          "imageUrls": {
            "title": "Search by image (URLs)",
            "maxItems": 100,
            "uniqueItems": true,
            "type": "array",
            "description": "Find the same or similar products from a photo: image URLs (https://...) from any website, one search per image (times each supplier region below). Each result is the same product row as a keyword search, with the image in `searchImageUrl`. **Max products per search** counts for each image. To search by image only, empty **Search keyword** (the form pre-fills one). A photo larger than about 560 KB is refused. 1688 applies the price range, supplier region, price sort and supplier label to an image search, and ignores the best-selling sort, business type, dropshipping, free shipping, 48 hours and one-per-supplier filters (refused when you search by image only, skipped for the images when you also give keywords); the minimum order filter is applied by the Actor.",
            "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/<id>.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
          },
          "newArrival": {
            "title": "New products only (新品)",
            "type": "boolean",
            "description": "Only the products 1688 lists as new arrivals (its \"new products\" filter). Applies to keyword searches and pasted search URLs; not to searches by picture.",
            "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."
          },
          "translateTo": {
            "title": "Translate texts to",
            "enum": [
              "EN-US",
              "EN-GB",
              "DE",
              "ES",
              "FR",
              "IT",
              "JA",
              "KO",
              "PT-BR",
              "PT-PT",
              "NL",
              "PL",
              "RU",
              "TR",
              "AR",
              "ID",
              "UK",
              "SV",
              "DA",
              "NB",
              "FI",
              "CS",
              "EL",
              "HU",
              "RO",
              "BG",
              "SK",
              "SL",
              "ET",
              "LV",
              "LT"
            ],
            "type": "string",
            "description": "Add a translation of the title, the selling points and the attributes of each product, in this language (`titleTranslated`, `sellingPointsTranslated`, `attributesTranslated`, `translatedTo`); the original Chinese stays in `title`, `sellingPoints` and `attributes`. Needs your own DeepL API key below: the translation is done and billed by DeepL on YOUR account (their free plan is enough for a few thousand products). One extra request to DeepL per product (the texts of one product go together; a text met again is not sent again); the first 10 selling points and the first 15 attributes are translated; attributes need **Product page** (`extractDetails`). If DeepL refuses or does not answer, the product is still delivered, with the translated columns empty and a warning in the log. Empty = no translation."
          },
          "deeplApiKey": {
            "title": "DeepL API key",
            "type": "string",
            "description": "Your DeepL API key (DeepL account > API keys; a key ending in `:fx` is the free plan). Only used by **Translate texts to**; stored encrypted, never written in the log or in the results."
          },
          "excludeKeywords": {
            "title": "Exclude keywords",
            "maxItems": 50,
            "uniqueItems": true,
            "type": "array",
            "description": "Drop the products whose title contains one of these WHOLE words (case and accents ignored): `art` drops \"Art deco\" but keeps \"Smart watch\". Several words in one entry (`hand made`) must appear together, in that order. Chinese, Japanese, Korean, Thai, Lao, Khmer and Burmese words (`二手`) are found anywhere in the title (no spaces there).",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}