{
    "openapi": "3.0.3",
    "info": {
        "title": "Taobao API",
        "description": "Taobao API provides access to up-to-date product data from the Chinese marketplace, including prices, descriptions, images, specifications, variants, seller information, and other details. It is suitable for integrating Taobao with online stores, marketplaces, and other e-commerce services.\n\n## Authentication\n\nPass your API key in the `X-Api-Key` header.\n\nIf a secret is enabled for the key, every request must also be signed with two headers:\n\n- `X-Api-Timestamp` — current Unix timestamp in seconds;\n- `X-Api-Sign` — `HMAC-SHA256(X-Api-Key + secret + X-Api-Timestamp + path_with_query, secret)` as lowercase hex, where `path_with_query` is the URL-encoded request path with the query string, e.g. `/v1/api/{uuid}/items?page=1`.",
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "https://gw.setalabs.com/v1/api/4ed0194f-bcae-45c2-995a-a42e22108b5c"
        }
    ],
    "security": [
        {
            "ApiKeyAuth": []
        }
    ],
    "paths": {
        "/catalog": {
            "get": {
                "operationId": "getCatalog",
                "summary": "Get Taobao Category Tree",
                "description": "Returns the complete hierarchy of Taobao product categories, including parent categories and subcategories.",
                "parameters": [
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "The language in which the API response data will be returned.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "en"
                    },
                    {
                        "$ref": "#/components/parameters/XApiTimestamp"
                    },
                    {
                        "$ref": "#/components/parameters/XApiSign"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                }
            }
        },
        "/langs": {
            "get": {
                "operationId": "getLangs",
                "summary": "Get Supported Languages",
                "description": "Returns the list of languages supported by the Taobao API. Use a language code from this list as the language parameter to specify the response language.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/XApiTimestamp"
                    },
                    {
                        "$ref": "#/components/parameters/XApiSign"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                }
            }
        },
        "/product/{id}": {
            "get": {
                "operationId": "getProductById",
                "summary": "Get Taobao Product Details",
                "description": "Returns detailed information about a Taobao product by its ID, including seller information, SKU variants and attributes, and the product description.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "The language in which the API response data will be returned.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "en"
                    },
                    {
                        "$ref": "#/components/parameters/XApiTimestamp"
                    },
                    {
                        "$ref": "#/components/parameters/XApiSign"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                }
            }
        },
        "/reviews/{id}": {
            "get": {
                "operationId": "getReviewsById",
                "summary": "Get Product Reviews",
                "description": "Returns customer reviews for a Taobao or Tmall product by its ID.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "The language in which the API response data will be returned.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "en"
                    },
                    {
                        "$ref": "#/components/parameters/XApiTimestamp"
                    },
                    {
                        "$ref": "#/components/parameters/XApiSign"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                }
            }
        },
        "/search": {
            "get": {
                "operationId": "getSearch",
                "summary": "Search Taobao Products",
                "description": "Searches for products on Taobao and returns matching results based on the specified search parameters.",
                "parameters": [
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "description": "Filters products by category ID.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "text",
                        "in": "query",
                        "required": false,
                        "description": "Search query used to find matching products.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "vendor_name",
                        "in": "query",
                        "required": false,
                        "description": "Filters products by seller name.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "price_min",
                        "in": "query",
                        "required": false,
                        "description": "Minimum product price.",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "price_max",
                        "in": "query",
                        "required": false,
                        "description": "Maximum product price.",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "volume_min",
                        "in": "query",
                        "required": false,
                        "description": "Minimum product sales volume.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "volume_max",
                        "in": "query",
                        "required": false,
                        "description": "Maximum product sales volume.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "description": "Sort order for the search results. Available values: default, price, -price, total_price, -total_price, volume, -volume, vendor_rating, -vendor_rating, updated_time, -updated_time. Prefix a value with - to sort in descending order.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": true,
                        "description": "Page number of the search results to retrieve.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": true,
                        "description": "Number of products to return per page.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 24
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "The language in which the API response data will be returned.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "en"
                    },
                    {
                        "$ref": "#/components/parameters/XApiTimestamp"
                    },
                    {
                        "$ref": "#/components/parameters/XApiSign"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                }
            }
        },
        "/search_img": {
            "get": {
                "operationId": "getSearchImg",
                "summary": "Search Products by Image",
                "description": "Searches for visually similar products on Taobao and Tmall using the provided image.",
                "parameters": [
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "The language in which the API response data will be returned.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "en"
                    },
                    {
                        "name": "image_url",
                        "in": "query",
                        "required": true,
                        "description": "URL of the image used to find visually similar products.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": true,
                        "description": "Page number of the search results to retrieve.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": true,
                        "description": "integer (query) Number of requested elements from the entire list.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 24
                    },
                    {
                        "$ref": "#/components/parameters/XApiTimestamp"
                    },
                    {
                        "$ref": "#/components/parameters/XApiSign"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                }
            }
        },
        "/seller/{id}": {
            "get": {
                "operationId": "getSellerById",
                "summary": "Get Taobao Seller Details",
                "description": "Returns detailed information about a Taobao seller by their ID.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "The language in which the API response data will be returned.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "en"
                    },
                    {
                        "$ref": "#/components/parameters/XApiTimestamp"
                    },
                    {
                        "$ref": "#/components/parameters/XApiSign"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Api-Key",
                "description": "Your API key."
            }
        },
        "parameters": {
            "XApiTimestamp": {
                "name": "X-Api-Timestamp",
                "in": "header",
                "required": false,
                "description": "Unix timestamp of the request in seconds. Required when a secret is enabled for the key.",
                "schema": {
                    "type": "string"
                }
            },
            "XApiSign": {
                "name": "X-Api-Sign",
                "in": "header",
                "required": false,
                "description": "Request signature (HMAC-SHA256, lowercase hex). Required when a secret is enabled for the key.",
                "schema": {
                    "type": "string"
                }
            }
        }
    }
}