{
  "openapi": "3.0.1",
  "info": {
    "title": "1688 Global Scraper & API: Wholesale & Arbitrage 🌐",
    "description": "⚡ Fast & Cheap ($1.50/1k): Scrape 1688 Global English search, Amazon & TikTok best-seller rankings, MOQ & SKU prices. Filter AliTrading suppliers by CE/FCC/RoHS certifications, 24h/48h dropshipping, Super Factory, unit weights & multi-currency margins. Zero login, MCP & AI ready.",
    "version": "1.0",
    "x-build-id": "QLYCVHciG6hWABVtk"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/unitbytes~1688-global-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-unitbytes-1688-global-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/unitbytes~1688-global-scraper/runs": {
      "post": {
        "operationId": "runs-sync-unitbytes-1688-global-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/unitbytes~1688-global-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-unitbytes-1688-global-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": {
          "mode": {
            "title": "Scrape Mode",
            "enum": [
              "auto",
              "search",
              "ranking",
              "direct_offer"
            ],
            "type": "string",
            "description": "Select 'Auto-Detect' to automatically classify keywords, 1688 Global search URLs, ranking URLs, or numeric offer IDs. Choose 'Global Trending & Best-Seller Rankings' to extract cross-border leaderboards for China 1688, Japan Amazon/TikTok, or Southeast Asia TikTok Shop.",
            "default": "auto"
          },
          "queries": {
            "title": "Search Queries, Ranking URLs, or Search URLs",
            "type": "array",
            "description": "Enter English or multilingual product keywords (e.g. 'Shoes', 'Digital, Computer', 'wireless earbuds'), 1688 Global Ranking URLs ('https://air.1688.com/kapp/1688-global/sales/ranking?...'), 1688 Global Search URLs ('https://air.1688.com/kapp/1688-global/sales/search?keywords=Shoes'), or numeric 1688 Offer IDs.",
            "items": {
              "type": "string"
            }
          },
          "keyword": {
            "title": "Search Keyword (Single)",
            "type": "string",
            "description": "Optional single search keyword, 1688 Global ranking URL, search URL, or numeric 1688 offer ID."
          },
          "offerIds": {
            "title": "Direct Offer IDs",
            "type": "array",
            "description": "Optional list of numeric 1688 wholesale offer IDs (e.g. ['851610724109', '685176373959']) to extract full B2B product details, tiered wholesale pricing, unit weights, and SKU matrices directly without searching.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs (Ranking, Search, or Product URLs)",
            "type": "array",
            "description": "Paste any 1688 Global Ranking URLs ('air.1688.com/kapp/1688-global/sales/ranking?...'), Global Search URLs ('air.1688.com/kapp/1688-global/sales/search?keywords=...'), or Product Offer URLs ('detail.1688.com/offer/...') directly from your browser.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "maxItems": {
            "title": "Max Items",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Maximum number of wholesale products to extract per query or ranking feed (1 to 5,000).",
            "default": 30
          },
          "detailLevel": {
            "title": "Detail Level",
            "enum": [
              "full",
              "summary"
            ],
            "type": "string",
            "description": "Choose 'Full B2B & SKU Mode' (recommended) to enrich each listing with complete SKU variant matrices, tiered MOQ pricing, live stock counts, unit weight (kg), and factory verification flags, or 'Summary Mode' for fast search and ranking card discovery.",
            "default": "full"
          },
          "currency": {
            "title": "Display Currency",
            "enum": [
              "USD",
              "CNY",
              "EUR",
              "GBP",
              "JPY",
              "AUD",
              "CAD",
              "SGD",
              "MYR",
              "THB",
              "VND",
              "IDR",
              "PHP",
              "KRW",
              "HKD"
            ],
            "type": "string",
            "description": "Target currency for global wholesale pricing (CNY factory price is always returned alongside your selected local currency).",
            "default": "USD"
          },
          "sortBy": {
            "title": "Sort By (Search Mode)",
            "enum": [
              "normal",
              "va_sales360",
              "price_asc",
              "price_desc",
              "sales",
              "booked",
              "priceAsc",
              "priceDesc"
            ],
            "type": "string",
            "description": "Sorting order for 1688 Global keyword searches.",
            "default": "normal"
          },
          "hotSelect": {
            "title": "Hot Select Badge Filter",
            "enum": [
              "",
              "global_trade_verified",
              "global_trade_choice",
              "super_factory",
              "certified_merchant",
              "precise_weight_dimensions"
            ],
            "type": "string",
            "description": "Filter search results by 1688 Global Trade verification, Super Factory status, Certified Merchant status, or calibrated weight & dimensions for FBA freight.",
            "default": ""
          },
          "shippingFilter": {
            "title": "Shipping & Dropshipping Filter",
            "enum": [
              "",
              "dropshipping",
              "shipping_24h",
              "shipping_48h"
            ],
            "type": "string",
            "description": "Filter by 1-piece cross-border Dropshipping support or guaranteed 24-hour / 48-hour dispatch SLA.",
            "default": ""
          },
          "sellerTenure": {
            "title": "Seller Tenure (Years on 1688)",
            "enum": [
              "",
              "over_5_years",
              "over_7_years",
              "over_10_years"
            ],
            "type": "string",
            "description": "Filter for established manufacturers and wholesalers by verified operating history on 1688.",
            "default": ""
          },
          "localisationService": {
            "title": "Localisation & Packaging Services",
            "enum": [
              "",
              "shipping_mark",
              "local_packaging",
              "local_manuals"
            ],
            "type": "string",
            "description": "Filter for export-ready factories offering custom carton shipping marks, foreign-language retail packaging, or multilingual user manuals.",
            "default": ""
          },
          "certification": {
            "title": "Product Qualification / Export Certification",
            "enum": [
              "",
              "CE",
              "RoHS",
              "FCC",
              "MSDS",
              "UL",
              "CPC",
              "TUV_PCoC",
              "TUV",
              "UKCA",
              "CB",
              "KC",
              "FSC"
            ],
            "type": "string",
            "description": "Filter for products holding verified international compliance certificates (CE, RoHS, FCC, MSDS, UL, CPC, TÜV PCoC, UKCA, CB, KC, FSC). To combine multiple certifications at once, use 'Multiple Certifications' below.",
            "default": ""
          },
          "certifications": {
            "title": "Multiple Certifications (Optional)",
            "type": "array",
            "description": "Optional list of multiple certification codes to combine in a single search (e.g. ['CE', 'RoHS', 'FCC']).",
            "items": {
              "type": "string"
            }
          },
          "maxMoq": {
            "title": "Maximum Starting MOQ Filter",
            "minimum": 1,
            "type": "integer",
            "description": "Filter products whose minimum order quantity is at or below this threshold (e.g. 1, 2, 10, 50)."
          },
          "priceMin": {
            "title": "Min Price",
            "type": "string",
            "description": "Minimum unit wholesale price in your selected currency (e.g. '1.5' or '10')."
          },
          "priceMax": {
            "title": "Max Price",
            "type": "string",
            "description": "Maximum unit wholesale price in your selected currency (e.g. '50' or '200')."
          },
          "rankingType": {
            "title": "Ranking Tab",
            "enum": [
              "TRENDING",
              "Most_Popular",
              "New_Arrivals"
            ],
            "type": "string",
            "description": "Select which 1688 Global ranking leaderboard to extract.",
            "default": "TRENDING"
          },
          "rankingMarket": {
            "title": "Target Country & Downstream Platform",
            "enum": [
              "CN:cbu",
              "JP:amazon",
              "JP:tiktok",
              "ID:tiktok",
              "VN:tiktok",
              "MY:tiktok",
              "TH:tiktok",
              "PH:tiktok",
              "SG:tiktok"
            ],
            "type": "string",
            "description": "Select the target country and e-commerce platform for the ranking leaderboard. Amazon Japan and TikTok Shop markets include downstream retail prices ('platformRetailPriceUsd') and automatic gross arbitrage margin calculations ('grossMarginUsd', 'grossMarginPct').",
            "default": "CN:cbu"
          },
          "rankingCategory": {
            "title": "Ranking Category",
            "enum": [
              "",
              "auto",
              "54:1",
              "67:1",
              "1044181:2",
              "18:1",
              "1042954:1",
              "10166:1",
              "311:1",
              "7:1",
              "1038378:1",
              "1813:1",
              "97:1",
              "6:1",
              "58:1",
              "122916001:1",
              "122916002:1",
              "96:1",
              "59:1",
              "68:1",
              "3210981:1",
              "605248:1",
              "601152:1",
              "601450:1"
            ],
            "type": "string",
            "description": "Select a category for the ranking feed, or leave on 'Auto-Select Default Category' ('' or 'auto'). You can also specify any Level 1/2/3 category ID in 'Custom Category ID' below.",
            "default": ""
          },
          "customCateId": {
            "title": "Custom Category ID (cateId)",
            "type": "string",
            "description": "Optional numeric 1688 category ID (e.g. '1044181' for Crafts or '1038378' for Shoes). Overrides the Ranking Category dropdown above."
          },
          "customCateLevel": {
            "title": "Custom Category Level (1, 2, or 3)",
            "minimum": 1,
            "maximum": 3,
            "type": "integer",
            "description": "Category hierarchy level (1, 2, or 3) when using a Custom Category ID."
          },
          "resumptionToken": {
            "title": "Resumption Token",
            "type": "string",
            "description": "Optional encrypted resumption token from a previous run to continue pagination with zero duplicate items."
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Apify Proxy configuration. Apify Residential proxy is recommended for reliable global extraction.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}