# Alibaba Search

## Overview

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

## Description

Alibaba Search API. Query B2B product listings by keyword or search URL across 17 locale subdomains. Request mode returns prices, MOQ, seller data and pagination.

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

## Example Response

### Search 'neon' with subdomain=portuguese (page 1)

```json
{
  "results": [
    {
      "title": "Mais Vendido: Letreiro Luminoso de LED Personalizado com Logo para Negócios, Lojas, Interiores, Festas e Decoração de Casa – Letreiro Neon de LED em Acrílico Direto da Fábrica",
      "category": "Luzes de Néon",
      "image_url": "https://s.alicdn.com/@sc04/kf/Hdf89e9011f0f46b18ba7e388551bded5e.png_300x300.png",
      "min_order": "1 Peça",
      "price_max": 30,
      "price_min": 9.9,
      "seller_id": "247085343",
      "price_text": "US $9.90-$30.00",
      "product_id": "1601525671361",
      "sold_count": 21,
      "listing_url": "https://www.alibaba.com/product-detail/Hot-Selling-Custom-LED-Logo-Light_1601525671361.html?s=p",
      "seller_name": "Fujian Puchuang Information Technology Co., Ltd."
    },
    {
      "title": "Letreiros de Neon Personalizados, Luzes LED RGB Dimmáveis para Decoração de Parede, Quarto, Casamento, Aniversário, Bar, Logotipo da Empresa, Nome",
      "category": "Luzes de Néon",
      "image_url": "https://s.alicdn.com/@sc04/kf/Hc55da60b1b834209928da3bf1f3ee87a2.jpg_300x300.jpg",
      "min_order": "1 Peça",
      "price_max": 22.5,
      "price_min": 18.5,
      "seller_id": "242268971",
      "price_text": "US $18.50-$22.50",
      "product_id": "1600583937291",
      "sold_count": 303,
      "listing_url": "https://www.alibaba.com/product-detail/Custom-Neon-Signs-Personalized-Dimmable-LED_1600583937291.html?s=p",
      "seller_name": "Evermore Enterprise (Zhejiang) Ltd."
    },
    {
      "title": "Neon LED Strip 12V LED Strip Multicolor Neon Light Outdoor LED Strip Lights Decoração de luzes impermeáveis Flex Neon",
      "category": "Luzes de Néon",
      "image_url": "https://s.alicdn.com/@sc04/kf/H72f8a620855b4f5da867b2248bb8fd1ed.png_300x300.png",
      "min_order": "10 Metros",
      "price_min": 0.35,
      "seller_id": "274667237",
      "price_text": "US $0.35",
      "product_id": "1601062675641",
      "sold_count": 1063,
      "listing_url": "https://www.alibaba.com/product-detail/Neon-LED-Strip-12V-LED-Strip_1601062675641.html",
      "seller_name": "Shenzhen Chengjie Lighting Co., Ltd."
    }
  ],
  "pagination": {
    "next": true,
    "page": 1,
    "per_page": 20,
    "total_pages": 2398,
    "total_results": 47955
  }
}
```

## Documentation

## Overview
The **Alibaba Search API** queries Alibaba B2B product listings by keyword or search URL. Pass a **keyword**, a **`/trade/search` URL** or a **`/search/page` URL**, optionally with **`subdomain`** and **`page`**, and receive structured JSON with prices, MOQ, seller identity, ratings and pagination.

Search hits the Alibaba **`open-s`** JSON API (`open-s.alibaba.com`) directly. No browser rendering is required. Costs **1 credit** per call.

Use each result `listing_url` or `product_id` with [Alibaba Product](https://www.piloterr.com/library/alibaba-product) for localized PDP data, quantity tiers and lead times.

## Quickstart
```
GET https://api.piloterr.com/v2/alibaba/search?query=neon
GET https://api.piloterr.com/v2/alibaba/search?query=neon&subdomain=french&page=1
GET https://api.piloterr.com/v2/alibaba/search?query=https://portuguese.alibaba.com/search/page?SearchText=neon&pro=true
```

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

{"query": "neon", "subdomain": "french", "page": 1, "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or full Alibaba search URL |
| `subdomain` | string | no | Locale for keyword searches (`french`, `portuguese`, `www`, …) |
| `page` | integer | no | 1-based page number (default: `1`, 20 results per page) |
| `return_page_source` | boolean | no | Raw open-s JSON as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example | Locale |
|---|---|---|
| Keyword | `neon` | `www` (English) unless `subdomain` is set |
| Keyword + subdomain | `query=neon`, `subdomain=french` | French search (`language=fr`) |
| Trade search URL | `https://www.alibaba.com/trade/search?SearchText=neon` | From URL host |
| Search page URL | `https://portuguese.alibaba.com/search/page?SearchText=neon&pro=true` | From URL host |

When `query` is a full URL, **`subdomain` is ignored**. Invalid `subdomain` values return **`400`**.

## Supported locale subdomains
| Subdomain | Host | Search API language |
|---|---|---|
| `www` | `www.alibaba.com` | English (default) |
| `portuguese` | `portuguese.alibaba.com` | `pt` |
| `french` | `french.alibaba.com` | `fr` |
| `spanish` | `spanish.alibaba.com` | `es` |
| `german` | `german.alibaba.com` | `de` |
| `italian` | `italian.alibaba.com` | `it` |
| `russian` | `russian.alibaba.com` | `ru` |
| `japanese` | `japanese.alibaba.com` | `ja` |
| `korean` | `korean.alibaba.com` | `ko` |
| `arabic` | `arabic.alibaba.com` | `ar` |
| `turkish` | `turkish.alibaba.com` | `tr` |
| `thai` | `thai.alibaba.com` | `th` |
| `vietnamese` | `vietnamese.alibaba.com` | `vi` |
| `indonesian` | `indonesian.alibaba.com` | `id` |
| `dutch` | `dutch.alibaba.com` | `nl` |
| `polish` | `polish.alibaba.com` | `pl` |
| `hindi` | `hindi.alibaba.com` | `hi` |

## Response: each listing (`results[]`)
| Field | Type | Always present | Description |
|---|---|---|---|
| `product_id` | string | yes | Alibaba product ID |
| `title` | string | Product title (HTML cleaned, `puretitle` preferred) |
| `listing_url` | string | Canonical product detail URL |
| `image_url` | string | Main thumbnail (absolute URL) |
| `price_text` | string | no | Display range (`US $14.90-$19.90`); omitted on incomplete cards |
| `price_min` | number | no | Minimum numeric price when parsed from the card |
| `price_max` | number | no | Maximum numeric price (omitted on single-price cards or when not parsed) |
| `min_order` | string | no | MOQ label (`1 piece`, `10 meters`, …) |
| `category` | string | no | Leaf category name; often null on locale SERPs |
| `seller_name` | string | Supplier company name |
| `seller_id` | string | Supplier company ID |
| `rating` | number | no | Product or supplier rating when shown on the card |
| `review_count` | integer | no | Review count when shown on the card |
| `sold_count` | integer | no | Units sold when shown on the card |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Page size (20) |
| `total_results` | integer | Estimated total matches |
| `total_pages` | integer | Total pages |
| `next` | boolean | More pages available |

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

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query`, or invalid `subdomain` |
| `404` | Search API returned no parseable results |
| `500` | Upstream or parsing error |

## Notes
- `rating` and `review_count` are optional and rarely returned on open-s SERP cards.
- `sold_count` is optional; omit when Alibaba does not expose it on the card.
- `price_text`, `price_min`, and `min_order` may be omitted on incomplete open-s SERP cards (especially some locale subdomains).
- `price_max` may be omitted even when `price_text` shows a range, or for single-price listings (`price_min` only).
- `category` is optional; often null on locale SERPs. When present, `min_order` and `category` follow the search locale (`1 Peça`, `Luzes de Néon`, …).
- `listing_url` may point to `www.alibaba.com` even when searching a locale subdomain.
- The `/search/page` HTML shell has no SSR listings; Piloterr calls the **`open-s`** API instead.
- Titles may contain HTML entities; the parser prefers `puretitle` when available.
- Costs **1 credit** per call (request / crawler mode).

## Main use cases
- **B2B sourcing**: discover suppliers and MOQ by keyword across locales
- **Price benchmarking**: track `price_min` / `price_max` ranges by category
- **Catalog discovery**: harvest `product_id` and `listing_url` at scale before PDP enrichment
- **Cross-border research**: run the same keyword on `french`, `portuguese`, `german`, … subdomains