# AliExpress Product

## Overview

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

## Description

AliExpress Product API: scrape live `/item/` product pages from a full URL. Get title, images, seller identity, pricing, specs, delivery, and FAQs 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/product' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Air purifier PDP on aliexpress.com

```json
{
  "faqs": [],
  "info": {
    "link": "https://www.aliexpress.com/item/1005009517624640.html",
    "name": "Purificateur d'air désodorisant 24 heures, utilisation continue, lumière LED à couleur changeante, Purification complète de l'air, dépoussiérage",
    "rate": 5,
    "media": [
      "https://ae-pic-a1.aliexpress-media.com/kf/Se1f79370af2b4634bbfa9e1beadf9046C.jpeg_960x960q75.jpeg_.avif",
      "https://ae-pic-a1.aliexpress-media.com/kf/Sf9d5548be5f64e4c8ea0840d1685dfe0a.jpeg_960x960q75.jpeg_.avif",
      "https://ae-pic-a1.aliexpress-media.com/kf/S77e4c39b5540420ead87e47d010bb089M.jpeg_960x960q75.jpeg_.avif",
      "https://ae-pic-a1.aliexpress-media.com/kf/S2f998e36cac0433e86b8d36d16228b42Q.jpeg_960x960q75.jpeg_.avif",
      "https://ae-pic-a1.aliexpress-media.com/kf/Sae6e2b87c9014dbaa35c24ac5ff2df3c3.jpeg_960x960q75.jpeg_.avif",
      "https://ae-pic-a1.aliexpress-media.com/kf/S4af2669e607b42d0b85641c3160b8e19U.jpeg_960x960q75.jpeg_.avif"
    ],
    "reviews": 1,
    "seller_id": "1104914437",
    "product_id": 1005009517624640,
    "sold_count": 3,
    "seller_name": "Shop1104914437 Store",
    "available_count": 999
  },
  "pricing": {
    "price": 13.19,
    "discount": "No discount",
    "original_price": "No discount",
    "price_currency": "EUR"
  },
  "delivery": {
    "pickup_method": "Pick-up points",
    "shipping_cost": 20.42,
    "estimated_delivery": "juillet 08 - 15",
    "shipping_cost_currency": "EUR"
  },
  "specifications": [
    {
      "name": "Produit chimique à haute préoccupation",
      "value": "Aucun"
    },
    {
      "name": "Nom de marque",
      "value": "Docreate"
    },
    {
      "name": "Origine",
      "value": "CN (Origine)"
    },
    {
      "name": "Product Name",
      "value": "10W Air Revitaliser with Colour Changing  Light Refreshes Cleanses"
    },
    {
      "name": "Material",
      "value": "ABS"
    },
    {
      "name": "Size",
      "value": "18X17CM"
    }
  ]
}
```

## Documentation

## Overview
The **AliExpress Product API** retrieves full product detail page (PDP) data from an AliExpress `/item/` URL. Pass a product page URL and receive structured JSON with title, images, seller identity, pricing, specifications, delivery estimates, and FAQs.

AliExpress product pages are JavaScript single-page applications. Piloterr uses **browser rendering** to load the PDP and extract parsed fields. Pair with **AliExpress Search** to discover product URLs, then fetch full details here.

## Quickstart
```
GET https://api.piloterr.com/v2/aliexpress/product?query=https://www.aliexpress.com/item/1005009517624640.html
```

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

{"query": "https://www.aliexpress.com/item/1005009517624640.html", "return_page_source": false}
```

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

## Accepted URLs
```
https://www.aliexpress.com/item/1005009517624640.html
```

```
https://es.aliexpress.com/item/1005012069266068.html?spm=...
```

- Locale subdomains supported (`es.`, `fr.`, …)
- Tracking query params preserved in `info.link`
- Page fetched via canonical `/item/` URL (without query params)

## Rejected URLs (400)
- Bundle / SSR links (`productIds=...`, `/ssr/BundleDeals2`)
- URLs without `/item/{id}`
- Non-AliExpress domains

## Response: `info`
| Field | Type | Always present | Description |
|---|---|---|---|
| `product_id` | integer | yes | AliExpress numeric product ID |
| `name` | string | yes | Product title (missing → 404) |
| `link` | string | yes | Input URL with query params preserved |
| `media` | string[] | yes | Image URLs (960×960 when available) |
| `rate` | number \| null | yes | Star rating, 1 decimal; `null` if absent |
| `reviews` | integer \| null | yes | Review count; `null` if absent |
| `sold_count` | integer | yes | Units sold (`0` if not displayed) |
| `available_count` | integer | yes | Available stock (`0` if not displayed) |
| `seller_name` | string \| null | yes | Seller name from `/store/{id}` link |
| `seller_id` | string \| null | yes | Seller store ID |

## Response: `pricing`
| Field | Type | Always present | Description |
|---|---|---|---|
| `price` | number | yes | Current sale price (missing → 404) |
| `price_currency` | string \| null | yes | ISO 4217 code (`EUR`, `USD`, …) |
| `original_price` | number \| string | yes | Strikethrough price or `"No discount"` |
| `discount` | string | yes | Discount label or `"No discount"` |

## Response: `delivery`
Object or `null` if the delivery block is absent on the page.

| Field | Type | Description |
|---|---|---|
| `pickup_method` | string | e.g. `"Pick-up points"` |
| `shipping_cost` | number | Shipping cost when displayed |
| `shipping_cost_currency` | string | ISO 4217 code |
| `estimated_delivery` | string | Estimated delivery window |

## Response: `specifications` / `faqs`
| Key | Type | Structure |
|---|---|---|
| `specifications` | array | `{ "name": string, "value": string }[]` |
| `faqs` | array | `{ "question": string, "answer": string }[]` |

## Workflow
1. **Search**: discover listings and `listing_url` values
2. **Product**: fetch full PDP JSON (this endpoint)

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing parameter or invalid / rejected URL |
| `404` | Resource not found or not parseable |
| `500` | Rendering or parsing error |

A product page with no title or price returns **404**, not an empty 200 response.

## Notes
- Currency symbols are normalized to ISO 4217 (`€` → `EUR`).
- Ratings are floats rounded to 1 decimal place.
- Seller identity is included inline (`seller_name`, `seller_id`).
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Dropshipping validation**: verify live price, stock, seller, and shipping
- **Competitive monitoring**: track PDP changes across locales
- **Catalog enrichment**: populate databases with specs, images, and delivery data
- **Seller intelligence**: link product listings to store IDs