# AliExpress Search API Documentation

<p><strong>AliExpress Search API Documentation</strong> Search AliExpress products by keyword: for each result the product id, title, web url, image and gallery, price, original price, discount percent, rating, sold count and text, selling points, promotion and a sponsored flag. Narrow results with a sort order, a price range, a ship-from country and filters. The facets list in the response holds every filter you can use, with the exact value to pass in the filters parameter. sort_options lists the sort values. No category tree exists, so use the facets to narrow a search. Prices are numbers in the currency of the result. Currency and language follow the market of the request, so they can differ between calls. Failed requests are never charged. A valid search without hits is a successful response with an empty results list.</p>

- **Documentation:** [https://scrappa.co/docs/aliexpress-api/aliexpress_search](https://scrappa.co/docs/aliexpress-api/aliexpress_search)
- **API group:** AliExpress API
- **Endpoint:** `GET https://scrappa.co/api/aliexpress/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search keywords, e.g. phone case. |
| `page` | integer | No | Page number from 1 to 60. Defaults to 1. |
| `sort` | string | No | Sort order: default, orders, price_asc or price_desc. Defaults to default. |
| `min_price` | number | No | Lowest price, e.g. 5. Uses the currency of the results. |
| `max_price` | number | No | Highest price, e.g. 20. Must not be lower than min_price. |
| `ship_from` | string | No | Two-letter country code of the warehouse, e.g. US. |
| `filters` | string | No | Comma separated filter values taken from the facets of a previous response, e.g. filterCode:freeshipping or 11745-4352280. |

## Example response

```json
{
    "data": {
        "page": 1,
        "sort": "default",
        "query": "phone case",
        "facets": [
            {
                "type": "switch",
                "multi": true,
                "title": "Deals & discounts",
                "options": [
                    {
                        "label": "Free shipping",
                        "value": "filterCode:freeshipping",
                        "selected": false
                    }
                ]
            },
            {
                "type": "switch",
                "multi": true,
                "title": "Delivery & service",
                "options": [
                    {
                        "label": "Choice",
                        "value": "filterCode:choice_atm",
                        "selected": false
                    }
                ]
            }
        ],
        "results": [
            {
                "url": "https://www.aliexpress.com/item/1005012594256426.html",
                "price": {
                    "amount": 53.86,
                    "currency": "UAH",
                    "formatted": "53,86 \u0433\u0440\u043d."
                },
                "title": "INS Korean Polka Dots Dopamine Soft TPU Phone Case for iPhone 18 17 16 15 14 13 12 Pro Max 16E 17E 18 Pro Silicone Cream Cover",
                "rating": 4.9,
                "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/S34be593b88f0488ca16b517948db9201i.jpg",
                "promotion": null,
                "sold_text": "3,000+ sold",
                "image_urls": [
                    "https://ae-pic-a1.aliexpress-media.com/kf/S34be593b88f0488ca16b517948db9201i.jpg",
                    "https://ae-pic-a1.aliexpress-media.com/kf/Se0a49749fe624caf9f121c76afd9aa6c7.jpg"
                ],
                "product_id": "1005012594256426",
                "sold_count": 3990,
                "is_sponsored": false,
                "original_price": {
                    "amount": 179.71,
                    "currency": "UAH",
                    "formatted": "179,71 \u0433\u0440\u043d."
                },
                "selling_points": [
                    "New shoppers save \u0433\u0440\u043d.125.85",
                    "Extra 2% off with coins"
                ],
                "discount_percent": 70
            },
            {
                "url": "https://www.aliexpress.com/item/1005010439419248.html",
                "price": {
                    "amount": 98.3,
                    "currency": "UAH",
                    "formatted": "98,30 \u0433\u0440\u043d."
                },
                "title": "Magnetic Original Clear Case For iPhone 17 16 15 14 Plus 13 12 Mini 11 Pro Max 16E 17E Funda For Magsafe Transparent Cover",
                "rating": 4.9,
                "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/S28f397c19b0040ecac9bc4a3f73a9f123.jpg",
                "promotion": "\u0433\u0440\u043d.150 off on 3 items",
                "sold_text": "50,000+ sold",
                "image_urls": [
                    "https://ae-pic-a1.aliexpress-media.com/kf/S28f397c19b0040ecac9bc4a3f73a9f123.jpg",
                    "https://ae-pic-a1.aliexpress-media.com/kf/S7ba02a66503a44e981b6b60d8ab6ccccB.jpg"
                ],
                "product_id": "1005010439419248",
                "sold_count": 61612,
                "is_sponsored": false,
                "original_price": {
                    "amount": 278.95,
                    "currency": "UAH",
                    "formatted": "278,95 \u0433\u0440\u043d."
                },
                "selling_points": [],
                "discount_percent": 64
            }
        ],
        "has_more": true,
        "page_size": 60,
        "sort_options": [
            {
                "label": "Best matches",
                "value": "default"
            },
            {
                "label": "Popular",
                "value": "orders"
            }
        ],
        "total_results": 130348
    },
    "meta": {
        "billable": true,
        "endpoint_family": "search"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. This response is not billable. |
| 503 | Service Unavailable | AliExpress could not be reached. Retry after a short pause. This response is not billable. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)