# AliExpress Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/aliexpress/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/aliexpress-search |

## Description

AliExpress Search API: search by keyword or wholesale URL and get product listings with prices, ratings, sold counts, and pagination as JSON via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/aliexpress/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Wholesale search 'meta' on aliexpress.com

```json
{
  "results": [
    {
      "price": 36.99,
      "title": "Lunettes Intelligentes IA Meta AI Sans Fil à Changement de Couleur de Haute Qualité, Film Intelligent, Étanchéité IP65, Vidéo 2K, Traduction en Temps Réel",
      "currency": "EUR",
      "condition": "new",
      "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/S4a87e08500774848bba251a21308e471l.jpg",
      "product_id": "1005012335698677",
      "sold_count": 1,
      "listing_url": "https://www.aliexpress.com/item/1005012335698677.html"
    },
    {
      "price": 654.92,
      "title": "Oculus Quest 3 d'origine, 8 Go de RAM + 512 Go de stockage, écran 4K+ Infinite Display, résolution 2064x2208, batterie 5060 mAh, autonomie de 2,2 heures",
      "rating": 4.8,
      "currency": "EUR",
      "condition": "new",
      "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/Sc8f0a4c26b164cd08ded129e317f5a5aL.png",
      "product_id": "1005011541924400",
      "sold_count": 48,
      "listing_url": "https://www.aliexpress.com/item/1005011541924400.html"
    },
    {
      "price": 8.39,
      "title": "HIBLOKS Ray-Ban Meta Wayfarer lunettes chargeur de câble de charge rapide pour RW4006/RW4008/RW4012/RW4010/RW4014 Portable sûr Type C",
      "rating": 4.5,
      "currency": "EUR",
      "condition": "new",
      "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/S51d4975962144f30af5853775400fa69P.jpg",
      "product_id": "1005008808856805",
      "sold_count": 800,
      "listing_url": "https://www.aliexpress.com/item/1005008808856805.html"
    }
  ],
  "pagination": {
    "next": true,
    "page": 1,
    "per_page": 60,
    "total_pages": 94,
    "total_results": 5624
  }
}
```

## Documentation

## Overview
The **AliExpress Search API** returns product listings from AliExpress search and wholesale result pages. Pass a **keyword** (e.g. `meta`) or a **full search URL** and receive structured JSON with titles, prices, ratings, order counts, and pagination.

Keywords are resolved to wholesale search pages automatically. AliExpress search pages are JavaScript single-page applications. Piloterr uses **browser rendering** to load the page and extract listing data.

Use each result's `listing_url` with **AliExpress Product** for full PDP details and seller identity (`seller_id`, `seller_name`).

## Quickstart
```
GET https://api.piloterr.com/v2/aliexpress/search?query=meta
```

Or pass a full wholesale URL:
```
GET https://api.piloterr.com/v2/aliexpress/search?query=https://www.aliexpress.com/w/wholesale-meta.html
```

Via POST:
```
POST https://api.piloterr.com/v2/aliexpress/search
Content-Type: application/json

{"query": "meta", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search keyword or full AliExpress search URL |
| `return_page_source` | boolean | no | Return raw HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example |
|---|---|
| Keyword | `meta` → `wholesale-meta.html` |
| Wholesale URL | `https://www.aliexpress.com/w/wholesale-meta.html?spm=...` |
| Paginated URL | `https://www.aliexpress.com/w/wholesale-meta.html?page=2` |
| Other patterns | URLs containing `/w/`, `/wholesale`, `searchText=`, or `/af/` |

There is no separate `page` parameter: include `?page=N` in the URL to paginate.

## Response: each listing (`results[]`)
| Field | Type | Always present | Description |
|---|---|---|---|
| `product_id` | string | yes | AliExpress product ID |
| `title` | string | yes | Product title |
| `listing_url` | string | yes | Canonical URL: `https://www.aliexpress.com/item/{id}.html` |
| `image_url` | string | yes | Absolute thumbnail URL |
| `price` | number | yes | Sale price |
| `currency` | string | yes | ISO 4217 code (`EUR`, `USD`, …) |
| `condition` | string | yes | Always `"new"` |
| `rating` | number | no | Star rating, 1 decimal (e.g. `4.8`) |
| `sold_count` | integer | no | Units sold when displayed on the card |
| `seller_name` | string | no | Seller name when available on the card |
| `seller_id` | string | no | Seller store ID when available on the card |
| `brand` | string | no | Brand name when available |
| `review_count` | integer | no | Review count when available |

Seller identity is always available on the **AliExpress Product** endpoint.

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page (from URL, default `1`) |
| `per_page` | integer | Page size (typically `60`) |
| `total_results` | integer | Estimated total matching products |
| `total_pages` | integer | Total pages available |
| `next` | boolean | `true` if a next page exists |

## Workflow
1. **Search**: discover listings by keyword or search URL (this endpoint)
2. **Product**: fetch full PDP JSON from any `listing_url`

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Search page not parseable or no results |
| `500` | Rendering or parsing error |

## Notes
- Currency codes are normalized to ISO 4217 (`EUR`, not `€`).
- Ratings are floats rounded to 1 decimal place when present.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Dropshipping research**: find trending products and prices by keyword
- **Search rank tracking**: monitor listing visibility across keywords and pages
- **Catalog discovery**: harvest `product_id` and `listing_url` values at scale
- **Product enrichment**: chain Search → Product for seller and delivery data