{
  "openapi": "3.0.1",
  "info": {
    "title": "1688.com Wholesale Scraper: Products & Suppliers",
    "description": "Scrape 1688.com, China's largest wholesale marketplace, without a login. Search by keyword, link, category or photo, find cheaper look-alikes, look up suppliers and track price changes. Get tiered prices, MOQ, stock, sales, images, SKU variants, reviews and factory data. Pay only for results.",
    "version": "0.1",
    "x-build-id": "uVd28OZmdyk7yGNHC"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/theshark~china-1688-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-theshark-china-1688-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/theshark~china-1688-scraper/runs": {
      "post": {
        "operationId": "runs-sync-theshark-china-1688-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/theshark~china-1688-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-theshark-china-1688-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": {
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "Search keywords, Chinese or English, for example 手机壳 or phone case. Each keyword is searched separately.",
            "items": {
              "type": "string"
            }
          },
          "offerIds": {
            "title": "Offer IDs or URLs",
            "type": "array",
            "description": "1688 product IDs or product links (detail.1688.com/offer/<id>.html). These products are scraped first, with full product pages, and then the other sources are processed.",
            "items": {
              "type": "string"
            }
          },
          "searchUrls": {
            "title": "1688 search URLs",
            "type": "array",
            "description": "Links to 1688 search results (s.1688.com/selloffer/offer_search.htm?..., m.1688.com/offer_search/...). The keyword and the filters from the link are used; they win over the filters below. Each link is searched separately.",
            "items": {
              "type": "string"
            }
          },
          "categoryId": {
            "title": "Category ID",
            "type": "string",
            "description": "1688 category ID of level 1 or 2 (for example 1813 for toys, 181309 for a sub-category). With keywords or links it works as a filter; alone it is searched by itself. Leaf categories need a keyword."
          },
          "imageUrls": {
            "title": "Image URLs (search by photo)",
            "type": "array",
            "description": "Links to photos to search by: 1688 finds visually similar products. Links on alicdn.com (1688 product images) are used directly; any other image is downloaded, resized and uploaded to 1688 (JPEG, PNG, GIF and WEBP work). Each image is searched separately, up to about 700 products per image. Every row has similarityScore: smaller is closer (for example, below 0.1 is almost the same photo).",
            "items": {
              "type": "string"
            }
          },
          "similarToOfferIds": {
            "title": "Find look-alikes of offers (IDs or URLs)",
            "type": "array",
            "description": "1688 product IDs or links. For each one, the scraper takes its main image and finds visually the same or very close products from other sellers, cheapest first (up to about 700 per offer), then scrapes them as normal products. The offer itself is not included. Every row has similarityScore: smaller is closer. Only products with similarityScore up to 0.2 are kept (about the same photo or the same kind of product); change this with Max similarityScore.",
            "items": {
              "type": "string"
            }
          },
          "maxSimilarityScore": {
            "title": "Max similarityScore (look-alikes)",
            "minimum": 0,
            "type": "number",
            "description": "Only for 'Find look-alikes of offers'. Products with a higher similarityScore are skipped. Smaller means closer: up to 0.1 is almost the same photo, 0.1-0.2 is the same kind of product, above 0.3 are often different models. Leave empty for the default 0.2, which suits most goods; fashion and other visual categories may need a higher value (for example 0.3)."
          },
          "suppliers": {
            "title": "Suppliers (shop links, shop IDs or company names)",
            "type": "array",
            "description": "Get a profile row for each supplier (rowType \"supplier\"): company name, registration, shop header and ratings, factory card, shop metrics and the IDs of the shop's hot offers. Accepted: a shop link (https://shop....1688.com/ or https://<name>.1688.com/, any page of the shop), m.1688.com/winport/b2b-....html, winport.m.1688.com/...?memberId=b2b-..., a shop ID (b2b-...) or the exact company name. A product link is not a supplier: put it in Offer IDs. One supplier profile found is billed as one supplier event; not found suppliers and errors are free. No contacts (phones, emails, WeChat, QQ, names) are collected. With 'Include supplier intelligence' the paid supplierIntelligence block is added when it has data.",
            "items": {
              "type": "string"
            }
          },
          "maxProductsPerSupplier": {
            "title": "Max products per supplier",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "How many products to scrape for each supplier. 0 (default) means only the supplier profile. Products come from a search by the exact company name, the factory card list (factories only) and the shop's hot and new offers. This is not the full catalog: 1688 closes it, and about 180-260 products per seller can be found. Each product is scraped as a normal product (full card, billed as a product) and carries the supplier in source. With 'Open product pages' off, products found by the company-name search come as cheaper search cards, but products without a search card (factory card list, hot and new offers) are still scraped from their product page and billed as a product.",
            "default": 0
          },
          "maxResults": {
            "title": "Max results per keyword",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Maximum number of products per keyword, URL, category, photo or look-alike offer. One 1688 request gives about 300 products. Above that, extra requests are made (split by price range and sort order), so the run takes longer and the extra results are less relevant.",
            "default": 100
          },
          "scrapeProductPages": {
            "title": "Open product pages",
            "type": "boolean",
            "description": "On (default): every product is scraped from its own page, with the full set of fields. Off: products found by search are taken straight from the search results, which is much faster and cheaper (billed as the cheaper product-card event). Such rows have only the search-card fields (title, price tiers, image, seller, sales, trade scores). Products given in offerIds always use product pages, and so do supplier products that have no search card (factory card list, hot and new offers): they are billed as a product. Reviews, supplier intelligence and same items are not collected in this mode. A Verified merchant type is then only 1688's own search filter (products are not checked on their pages).",
            "default": true
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "relevance",
              "bestSelling",
              "priceAsc",
              "priceDesc"
            ],
            "type": "string",
            "description": "How search results are ordered.",
            "default": "relevance"
          },
          "priceMin": {
            "title": "Minimum price (CNY)",
            "minimum": 0,
            "type": "number",
            "description": "Only products priced at or above this value, in yuan. Leave empty for no filter."
          },
          "priceMax": {
            "title": "Maximum price (CNY)",
            "minimum": 0,
            "type": "number",
            "description": "Only products priced at or below this value, in yuan. Leave empty for no filter."
          },
          "minOrderQuantityFrom": {
            "title": "Min minimum order quantity",
            "minimum": 0,
            "type": "integer",
            "description": "Only products whose minimum order quantity (MOQ) is at least this value. Leave empty for no filter."
          },
          "minOrderQuantity": {
            "title": "Max minimum order quantity",
            "minimum": 0,
            "type": "integer",
            "description": "Only products whose minimum order quantity (MOQ) is at most this value. Leave empty for no filter."
          },
          "merchantType": {
            "title": "Merchant type",
            "enum": [
              "any",
              "verifiedMerchant"
            ],
            "type": "string",
            "description": "Limit results to a type of supplier.",
            "default": "any"
          },
          "province": {
            "title": "Province",
            "type": "string",
            "description": "Filter by supplier province, in Chinese characters (for example 广东). Several provinces can be separated by commas (for example 江苏,浙江). Optional."
          },
          "city": {
            "title": "City",
            "type": "string",
            "description": "Filter by supplier city, in Chinese characters (for example 深圳). Optional."
          },
          "dropshipping": {
            "title": "Dropshipping (一件代发)",
            "type": "boolean",
            "description": "Only suppliers that ship single items directly to your customer.",
            "default": false
          },
          "freeShipping": {
            "title": "Free shipping (包邮)",
            "type": "boolean",
            "description": "Only products with free shipping. Cannot be combined with 'Dropshipping with free shipping'; the first one is used.",
            "default": false
          },
          "dropshipFreeShipping": {
            "title": "Dropshipping with free shipping (1件代发包邮)",
            "type": "boolean",
            "description": "Only products that ship single items with free shipping.",
            "default": false
          },
          "sevenDayReturn": {
            "title": "7-day return (7天无理由)",
            "type": "boolean",
            "description": "Only products with a 7-day no-reason return. Cannot be combined with 'Fast invoice'; the first one is used.",
            "default": false
          },
          "fastInvoice": {
            "title": "Fast invoice (极速开票)",
            "type": "boolean",
            "description": "Only suppliers that issue invoices quickly.",
            "default": false
          },
          "officialLogistics": {
            "title": "Official logistics (官方物流)",
            "type": "boolean",
            "description": "Only products shipped with 1688 official logistics.",
            "default": false
          },
          "verifiedFactory": {
            "title": "Verified factory (真实工厂认证)",
            "type": "boolean",
            "description": "Only suppliers with a verified factory. Cannot be combined with 'Big brand OEM' or the 'Verified merchant' type; the first one is used.",
            "default": false
          },
          "bigBrandOem": {
            "title": "Big brand OEM (大牌代工)",
            "type": "boolean",
            "description": "Only suppliers that make products for big brands.",
            "default": false
          },
          "excludeKeywords": {
            "title": "Exclude keywords",
            "type": "array",
            "description": "Skip products whose title contains any of these words.",
            "items": {
              "type": "string"
            }
          },
          "includeSkuDetails": {
            "title": "Include SKU details",
            "type": "boolean",
            "description": "Add the full variant matrix: each variant with its options, price, stock and sales.",
            "default": false
          },
          "includeDescriptionHtml": {
            "title": "Include description HTML",
            "type": "boolean",
            "description": "Add the full product description as HTML. Description text and images are always included.",
            "default": false
          },
          "includeReviews": {
            "title": "Reviews per product",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "How many latest reviews to attach to each product (0 to 100). 1688 shows anonymous visitors only part of a product's reviews, so some products get fewer. Buyer names, avatars and profiles are never collected. Charged per review delivered.",
            "default": 0
          },
          "includeSupplierIntelligence": {
            "title": "Include supplier intelligence",
            "type": "boolean",
            "description": "Add a supplierIntelligence block: factory card for verified factories (videos, rankings, equipment list, production lines, OEM minimums, production capacity, factory address and coordinates), product certificates (including CE/FCC/RoHS), customization (services with prices, printing price list, lead times by quantity), dropshipping metrics and the product's ranking on 1688. Up to 6 extra requests per product. Charged as an extra event only when at least part of this data is found. Always included for free: founding year, company registration with address, supplier profile (staff, area, equipment, verification), shop metrics (stars, quality and fulfilment rates, followers, years on 1688) and the seller chat link.",
            "default": false
          },
          "includeSameItems": {
            "title": "Include same items from other sellers",
            "type": "boolean",
            "description": "Add a sameItems list to each product: up to 8 offers of the same item from other sellers (title, price, sales text, image and link; no seller details). Billed as a same-items event only when the list is not empty. Needs product pages, so it is off when scrapeProductPages is false.",
            "default": false
          },
          "monitorName": {
            "title": "Monitor name",
            "type": "string",
            "description": "Turn on change monitoring (free). The name of your monitor: the previous state of every product is kept in your account's key-value store china-1688-monitor-<name> (the name is lower-cased; use Latin letters and digits, other characters are dropped and different names made only of them share one store). Every product row gets monitor.status: NEW (not seen before), CHANGED (monitor.changes lists price, stock, sold count, title or status that differ), UNCHANGED, or GONE (a product from offerIds that was OK last time is not found now). The stored state is updated at the end of the run. Leave empty to switch monitoring off. If the store cannot be opened, the run goes on without monitoring and a warning is logged."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}