{
  "openapi": "3.0.1",
  "info": {
    "title": "AliExpress Search Scraper & AliExpress Image Search API",
    "description": "Scrape AliExpress search results by keyword, search or category URL, or image: price, original and first-order price, exact orders, rating, store, shipping, delivery date and product id, in the country, currency and language you choose. No login. Export to CSV, JSON or Excel. Misses free.",
    "version": "0.1",
    "x-build-id": "8sQfhNpnkaIPCrgxR"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/hyperbach~aliexpress-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-hyperbach-aliexpress-search-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/hyperbach~aliexpress-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-hyperbach-aliexpress-search-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/hyperbach~aliexpress-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-hyperbach-aliexpress-search-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",
            "maxItems": 1000,
            "type": "array",
            "description": "Search words, one search per line, in any language (`wireless earbuds`, `usb-c cable`, `手机壳`). Each search is read page by page, 60 products a page, to the end of AliExpress's list (at most 60 pages). A search URL pasted here is read as a URL.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "searchUrls": {
            "title": "Search or category URLs",
            "maxItems": 1000,
            "type": "array",
            "description": "AliExpress search or category pages as you see them in a browser, with their filters: `https://www.aliexpress.com/w/wholesale-yoga-mat.html?SortType=total_tranpro_desc`, `https://www.aliexpress.com/category/5090301/mobile-phones.html`. Any AliExpress host works (.us, es., fr., m.). The URL's own sort, price range, switches, ship-from and page are kept; a filter name AliExpress ignores (pr, isFreeShip, choice, categoryId) is named on the search row. A product, store or campaign page gets a free row that says why.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "imageUrls": {
            "title": "Images (search by image)",
            "maxItems": 200,
            "type": "array",
            "description": "Public image links (an AliExpress product image or any other https link to a JPG, PNG or WebP up to 5 MB). Each image is searched with AliExpress's own image search: up to 150 positions, about 105 distinct products.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "categoryId": {
            "title": "Category id",
            "pattern": "^(\\d{1,15})?$",
            "type": "string",
            "description": "AliExpress's numeric category id (the number in /category/<id>/…, e.g. 5090301 for mobile phones). With keywords, every keyword is searched inside this category; alone, the category's own list is read.",
            "default": ""
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "default",
              "orders",
              "price_asc",
              "price_desc"
            ],
            "type": "string",
            "description": "The order AliExpress lists the products in. AliExpress has no rating and no newest order: use minRating to keep well-rated products.",
            "default": "default"
          },
          "moreOrderings": {
            "title": "Also read in these orders (new products only)",
            "type": "array",
            "description": "More orders to read each search in, to reach more of AliExpress's catalogue: `orders`, `price_asc`, `price_desc`, `default`. Only products not already delivered are added (one default list plus the orders list gave 64 % more distinct products in our tests). Empty = one order.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "minPrice": {
            "title": "Minimum price",
            "minimum": 0,
            "type": "number",
            "description": "In the currency of the view (the currency field, or the ship-to country's own). AliExpress filters by it and each product is checked again; empty = no minimum."
          },
          "maxPrice": {
            "title": "Maximum price",
            "minimum": 0,
            "type": "number",
            "description": "In the currency of the view; empty = no maximum."
          },
          "minRating": {
            "title": "Minimum rating (stars)",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "Keep products rated at least this (0-5). Products with no rating yet are left out when set. Checked on each product: AliExpress's own 4-star switch lets lower-rated products through."
          },
          "minOrders": {
            "title": "Minimum orders sold",
            "minimum": 0,
            "type": "integer",
            "description": "Keep products with at least this many orders (the exact count, not the rounded 10,000+). 0 = no minimum.",
            "default": 0
          },
          "minDiscount": {
            "title": "Minimum discount (%)",
            "minimum": 0,
            "maximum": 99,
            "type": "integer",
            "description": "Keep products whose shown price is at least this many percent below the original. 0 = no minimum.",
            "default": 0
          },
          "freeShippingOnly": {
            "title": "Free shipping only",
            "type": "boolean",
            "description": "AliExpress's own Free shipping filter.",
            "default": false
          },
          "choiceOnly": {
            "title": "Choice only",
            "type": "boolean",
            "description": "AliExpress's own Choice filter.",
            "default": false
          },
          "shipFrom": {
            "title": "Ships from (country)",
            "pattern": "^([A-Za-z]{2})?$",
            "type": "string",
            "description": "Two letters, e.g. US, ES, CN: AliExpress's ship-from filter, and each product's ships-from is checked again. Empty = any.",
            "default": ""
          },
          "excludeAds": {
            "title": "Leave out sponsored products",
            "type": "boolean",
            "description": "Leave out the products AliExpress marks as ads (about 1 in 11 on the best-match order).",
            "default": false
          },
          "excludeWords": {
            "title": "Leave out titles with these words",
            "type": "array",
            "description": "A product whose title holds any of these words (case does not matter) is left out.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "includeRelated": {
            "title": "Deliver AliExpress's suggestions when nothing matches",
            "type": "boolean",
            "description": "When no product matches the words, AliExpress shows other products instead. Off: nothing is delivered or charged and the search row says so. On: those products are delivered, marked match = related.",
            "default": false
          },
          "shipTo": {
            "title": "Ship-to country",
            "pattern": "^[A-Za-z]{2}$",
            "type": "string",
            "description": "Two letters (US, GB, DE, FR, BR, JP, AU …): the market whose prices, offers, delivery and catalogue you see. 66 countries were tested, each answering its own view. RU and KZ are served by aliexpress.ru, another site, and CN is not a ship-to country of the global site: a search asked for them gets a free row.",
            "default": "US"
          },
          "currency": {
            "title": "Currency",
            "pattern": "^([A-Za-z]{3})?$",
            "type": "string",
            "description": "Three letters (USD, EUR, GBP …). Empty = the ship-to country's own currency.",
            "default": ""
          },
          "language": {
            "title": "Language",
            "pattern": "^[a-z]{2}_[A-Z]{2}$",
            "type": "string",
            "description": "The language of titles and badges, as a locale: en_US, es_ES, fr_FR, de_DE, pt_BR, it_IT, ja_JP, ko_KR, ar_MA, ru_RU, nl_NL, pl_PL, tr_TR. The list of products follows the language too.",
            "default": "en_US"
          },
          "maxItemsPerSearch": {
            "title": "Max products per search",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "The most product rows of each keyword, URL or image; 0 = to the end of the list (up to 3,600 positions a list, 150 an image).",
            "default": 0
          },
          "maxItems": {
            "title": "Max products (whole run)",
            "minimum": 0,
            "maximum": 10000000,
            "type": "integer",
            "description": "The most charged rows of the whole run; 0 = no cap beyond your charge limit.",
            "default": 0
          },
          "proxyUrl": {
            "title": "Proxy URL",
            "type": "string",
            "description": "Your own proxy (scheme://user:pass@host:port) for every call instead of ours. Leave empty: the Actor brings its own connections at no cost to you."
          },
          "feedback": {
            "title": "Feedback to the maintainers",
            "maxLength": 2000,
            "type": "string",
            "description": "A note to the people who maintain this Actor: what you needed and did not get. For example a missing field, a wrong or empty result, or the Actor you switch from or to, and why. The run does not read it: the rows and the charges stay the same. A person reads every note."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}