> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce Search API (COMMERCE_SERP)

> Recherchez sur Amazon, Walmart, eBay, AliExpress, Google Shopping, Sephora, Coupang, Olive Young, Rakuten, Flipkart, Zalando et d'autres, une boutique par tâche, et recevez des produits classés avec prix, note et nombre d'avis dans un même format.

Recherchez les produits d'une boutique et recevez la liste classée en JSON via l'API de tâches asynchrones. Choisissez la boutique avec `site` ; toutes les boutiques renvoient les mêmes champs produit. Une recherche terminée coûte **3 crédits**.

## Requête

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_SERP", "payload": { "site": "amazon", "query": "wireless earbuds", "limit": 20 } }'
```

Soumettez la tâche, puis interrogez `GET /v1/async/task/{id}` ou recevez son webhook. Voir [Tâches asynchrones](/fr/concepts/async-tasks.md).

## Paramètres

* `site` : obligatoire. La boutique à interroger, parmi celles du tableau ci-dessous.
* `query` : terme de recherche obligatoire, de 1 à 500 caractères.
* `country` : facultatif. Par défaut, le pays de la boutique. Tout autre pays est refusé avec `422 REGION_UNSUPPORTED`.
* `limit` : entier facultatif de 1 à 40, avec 20 par défaut.

| `site` | Boutique | `country` |
| - | - | - |
| `amazon` | amazon.com | `US` |
| `walmart` | walmart.com | `US` |
| `target` | target.com | `US` |
| `ebay` | ebay.com | `US` |
| `aliexpress` | aliexpress.com | `US` |
| `google_shopping` | shopping.google.com | `US` |
| `sephora` | sephora.com | `US` |
| `ulta` | ulta.com | `US` |
| `coupang` | coupang.com | `KR` |
| `oliveyoung` | oliveyoung.co.kr | `KR` |
| `11st` | 11st.co.kr | `KR` |
| `lotteon` | lotteon.com | `KR` |
| `musinsa` | musinsa.com | `KR` |
| `kurly` | kurly.com | `KR` |
| `rakuten` | rakuten.co.jp | `JP` |
| `yahoo_shopping` | shopping.yahoo.co.jp | `JP` |
| `qoo10` | qoo10.jp | `JP` |
| `flipkart` | flipkart.com | `IN` |
| `myntra` | myntra.com | `IN` |
| `nykaa` | nykaa.com | `IN` |
| `zalando` | zalando.de | `DE` |

## Exemple de réponse

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "query": "wireless earbuds",
  "country": "US",
  "returnedCount": 1,
  "products": [
    {
      "rank": 1,
      "productId": "B0CHWRXH8B",
      "title": "Wireless Earbuds, Bluetooth 5.3 Headphones",
      "url": "https://www.amazon.com/dp/B0CHWRXH8B",
      "price": 24.99,
      "currency": "USD",
      "rating": 4.6,
      "reviewCount": 19406
    }
  ]
}
```

## Champs du résultat

* `site`, `query` et `country` reprennent la requête. `returnedCount` est le nombre d’éléments de `products`.
* Chaque produit contient `rank`, `productId`, `title` et `url`. `productId` est l’identifiant produit propre à la boutique, comme l’ASIN sur Amazon, le numéro d’objet sur eBay ou `shop:item` sur Rakuten. `rank` suit l’ordre par défaut de la boutique. Sauf sur Coupang, il ignore les annonces que la boutique marque comme sponsorisées.
* `price`, `rating`, `reviewCount`, `imageUrl` et `brand` apparaissent quand la page de résultats les affiche. `price` est un nombre dans la `currency` (ISO 4217) du produit : une même recherche Amazon peut afficher plusieurs devises. Quand les formats ont des prix différents, `price` est le plus bas. Les prix Target sont ceux de sa boutique en ligne par défaut. Les prix AliExpress sont les prix de vente affichés à un acheteur non connecté aux États-Unis.
* `rating` utilise une échelle de cinq étoiles. Kurly et Zalando n’affichent pas de note, AliExpress affiche les étoiles sans le nombre d’évaluations, et les nombres abrégés comme 999+ sont omis. `brand` provient de Target, Sephora, Ulta, Olive Young, Lotte ON, Musinsa, Yahoo! Shopping, Qoo10, Flipkart, Myntra, Nykaa et Zalando, qui affichent la marque à part du titre.
* Sur `google_shopping`, `productId` est l’identifiant produit de Google, ou l’identifiant de l’offre quand Google n’a pas regroupé l’annonce en produit. La page de Google ne renvoie vers aucune page produit ni page marchand : `url` est donc la page de résultats Google Shopping où le produit est classé, suivie de `#product={productId}&title={title}`. Transmettez cette `url` à [Commerce Product](/fr/engines/commerce-product.md) pour lire les boutiques, les caractéristiques et la description du produit. `seller` est la boutique que Google affiche en premier, et `reviewCount` n’apparaît que lorsque Google affiche le nombre exact (moins de 1 000).
* Chaque recherche renvoie les produits de la première page de résultats de la boutique. Cette page affiche jusqu’à 30 produits sur Yahoo! Shopping, 32 sur Myntra et 24 sur Zalando. Elle compte 40 emplacements sur Flipkart et 20 sur Nykaa, annonces sponsorisées comprises.
* Quand une boutique envoie la recherche vers une autre page, les produits viennent de cette page : Ulta envoie certaines marques vers leur page de marque, Target envoie certaines recherches vers une recherche associée, et Nykaa affiche la page de catégorie pour les recherches qui nomment une catégorie.
* Une recherche sans aucun produit se termine en tâche échouée. La facturation se fait par recherche terminée.

## Voir aussi

* [Commerce Product](/fr/engines/commerce-product.md)
* [Vue d’ensemble des moteurs](/fr/engines/overview.md)
* [Crédits et limites](/fr/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.