{
  "openapi": "3.1.0",
  "info": {
    "title": "OneFindMe — AliExpress search in any language",
    "version": "1.0.0",
    "description": "Search AliExpress with the shopper's own words in any language (Hebrew, Arabic, German, Spanish, Japanese, English and more). Returns real listings with price, rating, order count, store and a link, priced for the delivery country. Links are affiliate links: OneFindMe may earn a commission at no extra cost to the buyer. The same search is available as an MCP server at https://onefindme.com/mcp (registry name com.onefindme/search).",
    "contact": { "name": "OneFindMe", "url": "https://onefindme.com/about/", "email": "hello@onefindme.com" }
  },
  "servers": [{ "url": "https://onefindme.com" }],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search AliExpress products in any language",
        "description": "Pass what the shopper is looking for, in their own words and language. The service turns it into the search AliExpress understands and returns matching listings.",
        "parameters": [
          { "name": "query", "in": "query", "required": true, "description": "What the shopper wants, in any language, e.g. \"מעיל חם לפעוט\" or \"wireless earbuds for running\".", "schema": { "type": "string", "maxLength": 200 } },
          { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 delivery country (US, GB, DE, IL, SA...). Sets currency and shipping. Default US.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } },
          { "name": "language", "in": "query", "required": false, "description": "ISO 639-1 language of the query (en, he, ar, de...). Default: detected from the text.", "schema": { "type": "string" } },
          { "name": "max_results", "in": "query", "required": false, "description": "Number of products, 1-20. Default 8.", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } },
          { "name": "min_price", "in": "query", "required": false, "description": "Minimum price in the country's currency.", "schema": { "type": "number" } },
          { "name": "max_price", "in": "query", "required": false, "description": "Maximum price in the country's currency.", "schema": { "type": "number" } },
          { "name": "free_shipping", "in": "query", "required": false, "description": "Only products with free shipping.", "schema": { "type": "boolean" } }
        ],
        "responses": {
          "200": {
            "description": "Matching AliExpress listings.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } }
          },
          "400": { "description": "Missing query." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResult": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "marketplace_query": { "type": ["string", "null"], "description": "The English search the engine actually ran on AliExpress." },
          "country": { "type": "string" },
          "currency": { "type": "string" },
          "language": { "type": "string" },
          "more": { "type": "string", "description": "Link to the full results on onefindme.com." },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": { "type": "string" },
                "price": { "type": ["number", "null"] },
                "original_price": { "type": ["number", "null"] },
                "discount_percent": { "type": ["number", "null"] },
                "currency": { "type": "string" },
                "rating": { "type": ["number", "null"], "description": "Out of 5." },
                "orders": { "type": "integer" },
                "store": { "type": ["string", "null"] },
                "image": { "type": ["string", "null"] },
                "url": { "type": "string", "description": "Affiliate link to the AliExpress listing." }
              }
            }
          }
        }
      }
    }
  }
}