# Idealo Search

## Overview

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

## Description

Search Idealo Spain, France, and Germany. Keyword or search URL. Prices, shipping, ratings, and pagination via WebUnlocker (3 credits).

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

## Example Response

### Search maison on idealo.es

```json
{
  "results": [
    {
      "id": "200139376",
      "url": "https://www.idealo.es/precios/200139376/maison-margiela-replica-jazz-club-eau-de-toilette.html",
      "image": "https://cdn.idealo.com/folder/Product/200139/3/200139376/s11_produktbild_mittelgross/maison-margiela-replica-jazz-club-eau-de-toilette.jpg",
      "price": 25.5,
      "title": "Maison Margiela Replica Jazz Club Eau de Toilette",
      "rating": 4.5,
      "currency": "EUR",
      "shipping": 3.95,
      "shop_name": "notino.es",
      "category_id": "16252",
      "offer_count": 26,
      "review_count": 158,
      "characteristics": [
        "Eau de Toilette unisex",
        "cuero",
        "2013"
      ]
    },
    {
      "id": "201140705",
      "url": "https://www.idealo.es/precios/201140705/maison-margiela-replica-by-the-fireplace-eau-de-toilette.html",
      "image": "https://cdn.idealo.com/folder/Product/201140/7/201140705/s11_produktbild_mittelgross/maison-margiela-replica-by-the-fireplace-eau-de-toilette.jpg",
      "price": 22.79,
      "title": "Maison Margiela Replica By the Fireplace Eau de Toilette",
      "rating": 4.5,
      "currency": "EUR",
      "shipping": 4.95,
      "shop_name": "deloox.es",
      "category_id": "16252",
      "offer_count": 20,
      "review_count": 11,
      "characteristics": [
        "Eau de Toilette unisex",
        "amaderado",
        "2015",
        "Perfumista Marie Salamagne"
      ]
    }
  ],
  "pagination": {
    "next": "https://www.idealo.es/resultados.html?q=maison&page=2",
    "page": 1,
    "per_page": 60,
    "total_pages": 23,
    "total_results": 1370
  }
}
```

### Search asics on idealo.fr

```json
{
  "results": [
    {
      "id": "209538024",
      "url": "https://www.idealo.fr/prix/209538024/asics-superblast-3-1013a177.html",
      "image": "https://cdn.idealo.com/folder/Product/209538/0/209538024/s4_produktbild_mittelgross/asics-superblast-3-1013a177.jpg",
      "price": 169.99,
      "title": "Asics Superblast 3 (1013A177)",
      "rating": 5,
      "currency": "EUR",
      "shipping": 0,
      "shop_name": "noirfonce.fr",
      "category_id": "22875",
      "offer_count": 379,
      "review_count": 2,
      "characteristics": [
        "Chaussures running amorti",
        "Unisexe",
        "Mesh",
        "Entraînement",
        "Supinateur",
        "Drop 8 mm"
      ]
    },
    {
      "id": "211349009",
      "url": "https://www.idealo.fr/prix/211349009/asics-novablast-6.html",
      "image": "https://cdn.idealo.com/folder/Product/211349/0/211349009/s4_produktbild_mittelgross/asics-novablast-6.jpg",
      "price": 126.95,
      "title": "Asics Novablast 6",
      "rating": 5,
      "currency": "EUR",
      "shipping": 0,
      "shop_name": "Running-Point.fr",
      "category_id": "22875",
      "offer_count": 1259,
      "review_count": null,
      "characteristics": [
        "Chaussures running légères",
        "Homme",
        "Textile",
        "Entraînement",
        "Foulée universelle",
        "Drop 8 mm",
        "Homme"
      ]
    }
  ],
  "pagination": {
    "next": "https://www.idealo.fr/prechcat.html?q=asics&page=2",
    "page": 1,
    "per_page": 36,
    "total_pages": 150,
    "total_results": 5394
  }
}
```

### Search asics on idealo.de

```json
{
  "results": [
    {
      "id": "202763575",
      "url": "https://www.idealo.de/preisvergleich/OffersOfProduct/202763575_-gel-nyc-1201a789-asics.html",
      "image": "https://cdn.idealo.com/folder/Product/202763/5/202763575/s1_produktbild_mittelgross/asics-gel-nyc-1201a789.jpg",
      "price": 95,
      "title": "Asics Gel-NYC (1201A789)",
      "rating": 4.5,
      "currency": "EUR",
      "shipping": 4.99,
      "shop_name": "footlocker.de",
      "category_id": "18817",
      "offer_count": 733,
      "review_count": 27,
      "characteristics": [
        "Low-Top-Sneaker",
        "Asics GEL-NYC",
        "Mesh",
        "Herren"
      ]
    },
    {
      "id": "208714682",
      "url": "https://www.idealo.de/preisvergleich/OffersOfProduct/208714682_-gel-nimbus-28-asics.html",
      "image": "https://cdn.idealo.com/folder/Product/208714/6/208714682/s1_produktbild_mittelgross/asics-gel-nimbus-28.jpg",
      "price": 120,
      "title": "Asics Gel-Nimbus 28",
      "rating": 5,
      "currency": "EUR",
      "shipping": 0,
      "shop_name": "nencinisport.it/de",
      "category_id": "22875",
      "offer_count": 2086,
      "review_count": 5,
      "characteristics": [
        "Dämpfungsschuhe",
        "Herren",
        "Textil",
        "Einsatzbereich im Stadion",
        "Neutral",
        "Sprengung 8 mm"
      ]
    }
  ],
  "pagination": {
    "next": "https://www.idealo.de/preisvergleich/MainSearchProductCategory.html?q=asics&page=2",
    "page": 1,
    "per_page": 36,
    "total_pages": 209,
    "total_results": 7524
  }
}
```

## Documentation

## Overview
Search Idealo price-comparison listings on **Spain** (`idealo.es`), **France** (`idealo.fr`), and **Germany** (`idealo.de`). Pass a **keyword** plus `country`, or a **full search URL** in `query`. WebUnlocker. **3 credits** per call.

Each result is a product card: id, title, product URL, lowest price (EUR), shipping fee, offer count, image, rating (0-5), review count, lead shop, and short characteristics. Pagination is `{ page, per_page, total_results, total_pages, next }` where `next` is the next search URL (or `null`).

Only `es`, `fr`, and `de` are supported. Other Idealo TLDs return `400`.

## Quickstart
```
GET https://api.piloterr.com/v2/idealo/search?query=maison&country=es
GET https://api.piloterr.com/v2/idealo/search?query=https://www.idealo.fr/prechcat.html?q=asics
GET https://api.piloterr.com/v2/idealo/search?query=asics&country=de&page=2
GET https://api.piloterr.com/v2/idealo/search?query=https://www.idealo.es/resultados.html?q=maison&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword (`maison`, `asics`) or a full Idealo search URL |
| `country` | string | no | `es` (default for keywords), `fr`, or `de`. Ignored when `query` is already a URL |
| `page` | integer | no | Page number. `page=2` appends `?page=2` to the search URL |

## Regions
| `country` | Host | Search path |
|---|---|---|
| `es` | `https://www.idealo.es` | `/resultados.html?q=` |
| `fr` | `https://www.idealo.fr` | `/prechcat.html?q=` |
| `de` | `https://www.idealo.de` | `/preisvergleich/MainSearchProductCategory.html?q=` |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results[]` | array | Product cards (sponsored marketplace rows are omitted) |
| `results[].id` | string | Idealo product id |
| `results[].title` | string | Product title |
| `results[].url` | string | Product page (`/precios/`, `/prix/`, or `/OffersOfProduct/`) |
| `results[].price` | number | Lowest listed price |
| `results[].currency` | string | `EUR` |
| `results[].shipping` | number | Shipping fee of the lead offer (`0` if free, `null` if unknown) |
| `results[].offer_count` | integer | Number of shops on Idealo for this product |
| `results[].image` | string | Card image |
| `results[].rating` | number | Score on a 0-5 scale (`null` if none) |
| `results[].review_count` | integer | User reviews (`null` if none) |
| `results[].shop_name` | string | Lead shop |
| `results[].characteristics` | array | Short attributes from the card |
| `results[].category_id` | string | Idealo category id |
| `pagination.page` | integer | Current page (1-based) |
| `pagination.per_page` | integer | Results on this page (36 or 60) |
| `pagination.total_results` | integer | Product count for the query |
| `pagination.total_pages` | integer | Page count |
| `pagination.next` | string | Next search URL, or `null` |

## Notes
- WebUnlocker. **3 credits** per call.
- Keyword + empty `country` targets Spain (`idealo.es`).
- A full search URL in `query` wins. Paginate with `page` or `?page=` on that URL. Use `pagination.next`.
- France uses `/prechcat.html`, not `/resultats.html`.
- `shipping` is the delivery fee, not price + shipping.
- Idealo stores ratings on a 0-100 scale internally. The API returns 0-5 (`90` becomes `4.5`).
- `offer_count` is the marketplace total. Use [Idealo Product](https://www.piloterr.com/library/idealo-product) for the visible offer list.
- Pass `results[].url` or `results[].id` to Idealo Product.

## Error codes
| Code | Meaning |
|---|---|
| `400` | Empty query, unsupported country, or a non es/fr/de Idealo URL |
| `404` | Search page not found or no products |
| `500` | Unlock or parse failed |

## Related endpoints
- [Idealo Product](https://www.piloterr.com/library/idealo-product)

## Main use cases
- Compare lowest prices for a SKU across Spain, France, and Germany
- Watch offer count and lead shop on a keyword
- Feed repricing jobs from Idealo search pages
- Paginate category-like keyword results without hosting a scraper