# Alibaba Product

## Overview

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

## Description

Alibaba Product API. Fetch a full B2B product page by URL or product ID with optional locale subdomain. Browser rendering returns tiered pricing, seller profile and lead times.

## 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/alibaba/product' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Product 1601175379813 on portuguese.alibaba.com

```json
{
  "url": "https://portuguese.alibaba.com/product-detail/Custom-Neon-Light-Acrylic-Neon-Sign_1601175379813.html",
  "price": {
    "max": 17.58,
    "min": 13.16,
    "unit": "Peça",
    "display": "€ 13,16- 17,58",
    "quantity_prices": [
      {
        "price": 17.58,
        "display": "€ 17,58",
        "price_usd": 19.9,
        "max_quantity": 49,
        "min_quantity": 1
      },
      {
        "price": 16.7,
        "display": "€ 16,70",
        "price_usd": 18.9,
        "max_quantity": 99,
        "min_quantity": 50
      },
      {
        "price": 15.81,
        "display": "€ 15,81",
        "price_usd": 17.9,
        "max_quantity": 499,
        "min_quantity": 100
      },
      {
        "price": 13.16,
        "display": "€ 13,16",
        "price_usd": 14.9,
        "min_quantity": 500
      }
    ]
  },
  "title": "Letreiro Neon Personalizado em Acrílico, Letreiro LED Neon para Branding de Lojas, Letreiro Neon por Atacado, Letreiro Iluminado LED Personalizado",
  "trade": {
    "lead_time": [
      {
        "max_quantity": 50,
        "min_quantity": 1,
        "process_period_days": 3
      },
      {
        "max_quantity": 500,
        "min_quantity": 51,
        "process_period_days": 7
      },
      {
        "max_quantity": 1000,
        "min_quantity": 501,
        "process_period_days": 15
      }
    ],
    "sales_volume": "890 vendido(s)"
  },
  "images": [
    "https://sc04.alicdn.com/kf/Hb0b375797bc04466a0b0899d8c3c1349P.jpg",
    "https://sc04.alicdn.com/kf/H6ce47c97d3f64748833a0d49e35f20efK.jpg",
    "https://sc04.alicdn.com/kf/Hde96e67f4ee8446c93b4c05a0aeaec1bc.jpg",
    "https://sc04.alicdn.com/kf/Hd15d7d3495f14440b8e4e9285d39250aS.jpg",
    "https://sc04.alicdn.com/kf/H53b4d1aacb0344fbbe6b5e3b04099f1eg.jpg",
    "https://sc04.alicdn.com/kf/Hf018053ccf77428484059bf8f4ba267d7.jpg"
  ],
  "seller": {
    "years": "7",
    "country": "CN",
    "company_id": 247837230,
    "profile_url": "https://custombox.en.alibaba.com/pt_PT/company_profile.html",
    "company_name": "Shenzhen Boxin Electronics Co., Ltd.",
    "is_gold_supplier": true
  },
  "attributes": [
    {
      "name": "Fonte de luz",
      "value": "Tubo Do DIODO EMISSOR de, LEVOU Neon, Tiras de LED, Luz de néon"
    },
    {
      "name": "Fonte de alimentação",
      "value": "Dc dc dc, Plugue, Transformador"
    },
    {
      "name": "Garantia",
      "value": "2 Years, 2 Anos"
    },
    {
      "name": "Material",
      "value": "Acrílico + luz neon"
    },
    {
      "name": "Classificação IP",
      "value": "IP68"
    },
    {
      "name": "Tensão",
      "value": "DC12V/24V"
    }
  ],
  "product_id": 1601175379813,
  "locale_host": "portuguese.alibaba.com"
}
```

## Documentation

## Overview
The **Alibaba Product API** returns a full Alibaba product detail page (PDP) as structured JSON. Pass a **product URL** or **numeric product ID**, optionally with **`subdomain`**, and receive localized title, HD images, tiered pricing, seller profile, attributes and lead times.

Product pages are rendered in a headless browser and parsed from `window.detailData`. Costs **2 credits** per call (browser rendering). Target `*.alibaba.com` hosts must be whitelisted for rendering.

Pair with [Alibaba Search](https://www.piloterr.com/library/alibaba-search) to discover `listing_url` values first.

## Quickstart
```
GET https://api.piloterr.com/v2/alibaba/product?query=1601175379813
GET https://api.piloterr.com/v2/alibaba/product?query=1601175379813&subdomain=portuguese
GET https://api.piloterr.com/v2/alibaba/product?query=https://www.alibaba.com/product-detail/Custom-Neon-Light-Acrylic-Neon-Sign_1601175379813.html
```

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

{"query": "1601175379813", "subdomain": "portuguese", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Product URL or numeric product ID |
| `subdomain` | string | no | Locale (`portuguese`, `french`, `www`, … or `french.alibaba.com`) |
| `return_page_source` | boolean | no | Rendered HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example | Resolved URL |
|---|---|---|
| Numeric ID | `1601175379813` | `https://www.alibaba.com/product-detail/_1601175379813.html` |
| ID + subdomain | `query=1601175379813`, `subdomain=portuguese` | `https://portuguese.alibaba.com/product-detail/_1601175379813.html` |
| Full URL | `https://www.alibaba.com/product-detail/..._1601175379813.html` | Host kept as-is |
| URL + subdomain override | product URL on `www`, `subdomain=french` | Host replaced with `french.alibaba.com` |

When `query` is a localized URL (`https://french.alibaba.com/...`), the host is preserved. Invalid `subdomain` returns **`400`**.

## Supported locale subdomains
Same hosts as Search: `www`, `portuguese`, `french`, `spanish`, `german`, `italian`, `russian`, `japanese`, `korean`, `arabic`, `turkish`, `thai`, `vietnamese`, `indonesian`, `dutch`, `polish`, `hindi` (each as `{subdomain}.alibaba.com`).

## Response fields
| Field | Type | Description |
|---|---|---|
| `product_id` | number | Product ID |
| `title` | string | Localized product title |
| `url` | string | Canonical product URL (no query string) |
| `locale_host` | string | Host used for rendering (`portuguese.alibaba.com`, …) |
| `images` | string[] | HD image URLs |
| `price.min` / `price.max` | number \| null | Price range from `productRangePrices` or ladder |
| `price.display` | string \| null | Localized formatted price |
| `price.unit` | string | Unit label (`Peça`, `pièce`, …) |
| `price.quantity_prices` | object[] | Quantity tiers: `{ min_quantity, max_quantity?, price, price_usd?, display }` |
| `seller.company_name` | string | Legal company name |
| `seller.company_id` | number | Company ID |
| `seller.country` | string | Country code (`CN`, …) |
| `seller.years` | string | Years on Alibaba |
| `seller.is_gold_supplier` | boolean | Gold Supplier flag |
| `seller.profile_url` | string | Company profile URL |
| `attributes` | object[] | `{ name, value }` product specs (may include duplicates) |
| `trade.sales_volume` | string | Sold volume label (localized) |
| `trade.lead_time` | object[] | `{ min_quantity, max_quantity, process_period_days }` |

## Alibaba workflow
1. [Alibaba Search](https://www.piloterr.com/library/alibaba-search) to discover listings
2. [Alibaba Product](https://www.piloterr.com/library/alibaba-product) for full PDP data (this endpoint)

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query`, or invalid `subdomain` |
| `404` | Rendered page not parseable (`window.detailData` missing) |
| `500` | Rendering or parsing error |

## Notes
- Canonical `url` keeps the SEO slug (`.../product-detail/Custom-Neon-Light-Acrylic-Neon-Sign_1601175379813.html`), not the bare `_ID.html` shortcut used internally for bare IDs.
- `price.quantity_prices[].max_quantity` is omitted on the open-ended top tier (e.g. `min_quantity: 500`).
- `trade.lead_time[].max_quantity` may be omitted on the last tier when Alibaba leaves it open.
- `attributes` often contains duplicate `{ name, value }` pairs (basic + other property blocks); consumers should dedupe if needed.
- Requires `*.alibaba.com` hosts to be authorized for browser rendering.
- Quantity tiers come from `productLadderPrices`; simple ranges from `productRangePrices`.
- `attributes` may list the same spec twice (basic + other property blocks on Alibaba).
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Supplier due diligence**: Gold Supplier status, country, years on platform
- **MOQ and tier pricing**: extract `quantity_prices` for procurement models
- **Localized catalogs**: fetch French, Portuguese or German PDP copy from the same product ID
- **Lead time planning**: use `trade.lead_time` ranges for supply-chain estimates