# Decathlon Search

## Overview

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

## Description

Search a Decathlon shop with a keyword or a search URL. Choose the country with region, or let a full link pick the shop, then page through titles, prices, and product links.

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

## Example Response

### Quechua bottle on decathlon.fr

```json
{
  "results": [
    {
      "sku": "c98m8612536",
      "url": "https://www.decathlon.fr/p/gourde-alu-1l-avec-bouchon-instantane-composee-a-100percent-dalu-recycle-bleu/330041/c98m8612536",
      "name": "Gourde alu 1L avec bouchon instantané, composée à 100% d’alu recyclé, bleu",
      "price": 9.99,
      "rating": 4.6,
      "region": "fr",
      "currency": "EUR",
      "image_url": "https://contents.mediadecathlon.com/p2579584/k$6ca4ddf66bdc61cefd58225cb14ae926/picture.jpg?format=auto&f=3000x0",
      "product_id": "330041",
      "color_count": 3,
      "review_count": 4700,
      "price_display": "9,99 €"
    }
  ],
  "pagination": {
    "next": "https://www.decathlon.fr/search?Ntt=gourde&from=40&size=40",
    "page": 1,
    "per_page": 40,
    "total_pages": 25,
    "total_results": 5274
  }
}
```

### Van Rysel bike on decathlon.com

```json
{
  "results": [
    {
      "url": "https://www.decathlon.com/products/van-rysel-xcr-triathlon-ultegra-di2?variant=42685025550398&_pos=1&_sid=f66afe510&_ss=r",
      "name": "Van Rysel XCR TRIATHLON ULTEGRA DI2",
      "price": 8499,
      "region": "us",
      "currency": "USD",
      "image_url": "https://www.decathlon.com/cdn/shop/files/default_2b2f6fb1-86fa-4f0b-b3ab-57a43be1de4c.jpg?v=1775491210&width=3840",
      "product_id": "8058089242686",
      "variant_id": "42685025550398",
      "price_display": "$8,499.00"
    }
  ],
  "pagination": {
    "next": "https://www.decathlon.com/search?q=bike&page=2",
    "page": 1,
    "per_page": 24,
    "total_pages": 8,
    "total_results": 177
  }
}
```

## Documentation

## Overview
Search Decathlon country shops. France and the other Decathlon country pages are read with the website crawler. The US shop is Shopify: its search page is HTML from the same crawler.

`query` is a keyword or a search or category link. `region` chooses the shop. The default is `fr`. A full link picks the shop. If `region` names another shop, the call returns 400.

The US shop (`us`, www.decathlon.com) is Shopify. Search is the Shopify results page. A product is read from the Shopify product JSON, not from the French Decathlon template. `gb` means `uk`. `be` is the French shop on decathlon.be. `be-nl` is the Dutch shop. `ch` is the French shop on decathlon.ch.

## Quickstart
```
GET https://api.piloterr.com/v2/decathlon/search?query=gourde
GET https://api.piloterr.com/v2/decathlon/search?query=gourde&region=fr&page=2
GET https://api.piloterr.com/v2/decathlon/search?query=https://www.decathlon.fr/search?Ntt=gourde
GET https://api.piloterr.com/v2/decathlon/search?query=tent&region=uk
GET https://api.piloterr.com/v2/decathlon/search?query=bike&region=us
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or Decathlon search link. Placeholder: `gourde`. A product link returns 400. |
| `region` | string | no | Country shop. Default `fr`. Placeholder: `fr`. |
| `page` | integer | no | Page number from 1. European shops use `from` and `size` (40). The US shop uses `page` (24). |
| `return_page_source` | boolean | no | When true, the response is the raw HTML in `result`. |

## Regions
| `region` | Shop | Currency | Page |
|---|---|---|---|
| `fr` | www.decathlon.fr | EUR | Decathlon |
| `es` | www.decathlon.es/es | EUR | Decathlon |
| `it` | www.decathlon.it | EUR | Decathlon |
| `pt` | www.decathlon.pt | EUR | Decathlon |
| `nl` | www.decathlon.nl | EUR | Decathlon |
| `be` | www.decathlon.be/fr | EUR | Decathlon |
| `be-nl` | www.decathlon.be/nl | EUR | Decathlon |
| `uk` | www.decathlon.co.uk | GBP | Decathlon |
| `ch` | www.decathlon.ch/fr | CHF | Decathlon |
| `us` | www.decathlon.com | USD | Shopify |

The US shop (`us`, www.decathlon.com) is Shopify. Search is the Shopify results page. A product is read from the Shopify product JSON, not from the French Decathlon template. `gb` means `uk`. `be` is the French shop on decathlon.be. `be-nl` is the Dutch shop. `ch` is the French shop on decathlon.ch.

## Response fields
Each item in `results` is one card. `price` is a number. `price_display` is that amount in the shop currency, with cents. France uses euros (`9,99 €`). The US shop uses dollars (`$8,499.00`). `pagination.next` is the next page URL, or null.

France, `gourde`, first card: `price` 9.99 and `price_display` `9,99 €`.
United States, `bike`, first card: `price` 8499 and `price_display` `$8,499.00`.

## Main use cases
- Monitor sports-gear prices in France, the UK, and the US shop
- Build an assortment from a category or search URL
- Compare the same keyword across euro, pound, and dollar shops

## Error codes
| Code | Meaning |
|---|---|
| 400 | Empty query, unknown shop, another website, a product link, or region conflicting with the URL |
| 404 | No product cards in the HTML |
| 500 | The fetch failed |

## Related
[Decathlon Product](https://www.piloterr.com/library/decathlon-product) reads one product URL.