{
  "openapi": "3.0.1",
  "info": {
    "title": "1688 Product Listings Scraper",
    "description": "Search 1688.com B2B wholesale listings by keyword or URL: title, CNY price range, MOQ, supplier, location, 诚信通 TrustPass years, 实力商家/工厂 flags, 回头率 repurchase rate, sold count. Filters for price, MOQ, years, repurchase, factory. PPE, MCP-ready.",
    "version": "1.0",
    "x-build-id": "OA4KJ2sgqSrACdhO0"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~1688-product-listings-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-1688-product-listings-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/khadinakbar~1688-product-listings-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-1688-product-listings-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/khadinakbar~1688-product-listings-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-1688-product-listings-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": {
          "searchQuery": {
            "title": "Search keyword",
            "type": "string",
            "description": "Free-text keyword to search 1688.com products. Chinese keywords match best (e.g. '无线耳机', '数据线'), but English also works (e.g. 'wireless earbuds'). The Actor opens the 1688 search-results page and collects every product card across pages. Leave empty if you instead provide startUrls. NOT a single offer URL — this Actor searches and returns many products, it does not scrape one detail.1688.com/offer page."
          },
          "startUrls": {
            "title": "Start URLs (search/category pages)",
            "type": "array",
            "description": "Optional list of 1688 search or category URLs to scrape directly (e.g. https://s.1688.com/selloffer/offer_search.htm?keywords=led+strip). Use instead of, or together with, searchQuery. Single product-detail pages (detail.1688.com/offer/<id>.html) and non-1688 URLs are ignored — this Actor only scrapes search/category result pages. Paste plain URL strings.",
            "items": {
              "type": "string"
            }
          },
          "maxResults": {
            "title": "Max products",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of product records to return. The Actor auto-paginates until this cap is reached, then stops, so it doubles as your cost ceiling (each product is one billable event). Defaults to 100. Set higher for bulk sourcing research.",
            "default": 100
          },
          "sortBy": {
            "title": "Sort results by",
            "enum": [
              "relevance",
              "monthlySales",
              "priceAsc",
              "priceDesc",
              "newest"
            ],
            "type": "string",
            "description": "Order in which 1688 returns the search results. 'relevance' is 1688's default 综合 ranking; 'monthlySales' surfaces best-selling offers; 'priceAsc'/'priceDesc' sort by price; 'newest' shows recently listed items. Applies to keyword searches; for startUrls the URL's own sort is respected. 1688 sort params shift occasionally — an unknown value silently falls back to relevance.",
            "default": "relevance"
          },
          "minPrice": {
            "title": "Minimum unit price (CNY)",
            "minimum": 0,
            "type": "integer",
            "description": "Only return products whose unit price (minimum of the price range) is at or above this value in CNY (Chinese yuan ¥). Applied as a 1688 URL filter and as a safety re-check on the parsed price. Leave empty for no minimum."
          },
          "maxPrice": {
            "title": "Maximum unit price (CNY)",
            "minimum": 0,
            "type": "integer",
            "description": "Only return products whose unit price (maximum of the price range) is at or below this value in CNY (¥). Applied as a 1688 URL filter and as a safety re-check on the parsed price. Leave empty for no maximum."
          },
          "minMoq": {
            "title": "Minimum MOQ to allow (lower bound)",
            "minimum": 1,
            "type": "integer",
            "description": "Server-side MOQ floor passed to the 1688 search URL. Combine with maxMoq to bracket a target 起批量 (minimum-order) window. Leave empty for no MOQ lower bound."
          },
          "maxMoq": {
            "title": "Maximum MOQ to allow (upper bound)",
            "minimum": 1,
            "type": "integer",
            "description": "Drop products whose minimum order quantity (起批量) is above this value (e.g. 2 keeps only products you can order in twos). Useful for small-volume / sample sourcing. Applied client-side after extraction; products with unknown MOQ are dropped when this bound is set. Leave empty for no upper bound."
          },
          "minSupplierYears": {
            "title": "Minimum 诚信通 (TrustPass) years",
            "minimum": 0,
            "type": "integer",
            "description": "Drop products from suppliers with fewer than this many years on 1688's 诚信通 (TrustPass) program (e.g. 3 keeps suppliers with 3+ years). Useful to skip brand-new sellers. Products with unknown years are dropped when this bound is set. Filtered products are not billed. Leave empty to keep all."
          },
          "minRepurchaseRate": {
            "title": "Minimum repurchase rate 回头率 (%)",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "Drop products whose supplier 回头率 (repurchase rate — the share of buyers who order again) is below this percentage, or unknown. A high 回头率 is 1688's strongest buyer-satisfaction signal. Example: 20 keeps suppliers with a 20%+ repurchase rate. Filtered products are not billed. Leave empty to keep all."
          },
          "minSold": {
            "title": "Minimum sold count",
            "minimum": 0,
            "type": "integer",
            "description": "Drop products with fewer than this many recorded sales/transactions (成交), or with unknown sold count. Useful to surface proven, high-volume listings. Filtered products are not billed. Leave empty to keep all."
          },
          "trustPassOnly": {
            "title": "诚信通 TrustPass suppliers only",
            "type": "boolean",
            "description": "When enabled, keep only products from 诚信通 (TrustPass) members — 1688's paid, identity-verified supplier tier (the practical equivalent of Alibaba's Verified Supplier). Filtered products are not billed. Default false.",
            "default": false
          },
          "powerfulMerchantOnly": {
            "title": "实力商家 powerful-merchant only",
            "type": "boolean",
            "description": "When enabled, keep only products from 实力商家 (powerful / strong merchants) — 1688's badge for high-capability, well-rated suppliers. Filtered products are not billed. Default false.",
            "default": false
          },
          "factoryOnly": {
            "title": "工厂 factory / manufacturer only",
            "type": "boolean",
            "description": "When enabled, keep only products from factories / manufacturers (工厂 / 超级工厂), skipping pure trading companies — useful for sourcing direct from the maker. Filtered products are not billed. Default false.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. Residential proxies — ideally China exit IPs — are strongly recommended: 1688's Baxia anti-bot blocks most datacenter IPs and may redirect overseas IPs to global.1688.com. The Actor automatically prefers Apify residential when your account has it and gracefully falls back to Apify datacenter when it does not — so the default works on any plan. Override only for a specific proxy requirement.",
            "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}