# idealo Search API Documentation

Search idealo.de by keyword or browse a category. Each product card carries the lowest price, offer count, cheapest shop with shipping, rating, test score and energy label. The response lists every facet group with its values and hit counts, the price range, related searches and totals. Send a facet ID back in filters to narrow the result. Without category_id the category is the one idealo's own search picks for the keyword; a keyword that idealo routes to no category returns an empty result. Send category_id without query to browse a category. Sorting by price with a keyword orders the products of the requested page only (sort_scope is page); browse sorts the whole category. Each card has a type: PRODUCT cards come first, OFFER cards (single shop offers) follow on later pages; the price sort with a keyword keeps products only. Counts change during the day.

- **Documentation:** [https://scrappa.co/docs/idealo-api/idealo_search](https://scrappa.co/docs/idealo-api/idealo_search)
- **API group:** idealo API
- **Endpoint:** `GET https://scrappa.co/api/idealo/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | No | Search text. Alias: q. Required unless category_id is set. |
| `category_id` | string | No | idealo category ID from the categories or autocomplete endpoint, for example 19116 for smartphones. |
| `page` | integer | No | 1-based page number. A page holds 36 products. Maximum 112. Defaults to 1. |
| `sort` | string | No | RELEVANCE_DESC (default), PRICE_ASC, PRICE_DESC, DISCOUNT_DESC or CREATION_DATE_DESC. |
| `filters` | array | No | Facet IDs from a previous response, comma separated or as filters[]. Filters from different groups narrow the result. |
| `item_states` | array | No | BARGAIN, SHORT_TERM_BARGAIN, EXCLUDE_USED or FAST_DELIVERABLE, comma separated. |
| `price_min` | number | No | Lowest product price in euros. |
| `price_max` | number | No | Highest product price in euros. |

## Example response

```json
{
    "meta": {
        "duration_ms": 1500,
        "upstream_calls": 2
    },
    "sort": "RELEVANCE_DESC",
    "query": "smartphone",
    "facets": [
        {
            "id": "manufacturer",
            "name": "Hersteller",
            "filters": [
                {
                    "id": "1820730",
                    "hits": 1377,
                    "name": "Samsung",
                    "position": 80
                }
            ]
        }
    ],
    "results": [
        {
            "id": "209770533",
            "url": "https://www.idealo.de/preisvergleich/OffersOfProduct/209770533_-galaxy-a57-samsung.html",
            "type": "PRODUCT",
            "price": 327.9,
            "title": "Samsung Galaxy A57",
            "rating": {
                "test_rating": "2,0",
                "score_percent": 90,
                "user_review_count": 72
            },
            "currency": "EUR",
            "image_url": "https://cdn.idealo.com/folder/Product/209770/5/209770533/s1_produktbild_mittelgross/samsung-galaxy-a57.jpg",
            "subheading": "5G Handy",
            "category_id": "19116",
            "offer_count": 555,
            "is_sponsored": false,
            "is_bestseller": false,
            "cheapest_offer": {
                "shop_id": "338630",
                "offer_key": "7ffeb4fd636feef0ce8a1219f9f5ae09",
                "shop_name": "smartport.de (Marktplatzh\u00e4ndler)",
                "shipping_costs": "0,00 \u20ac"
            },
            "characteristics": [
                "5G Handy",
                "6,7 Zoll",
                "5.000 mAh"
            ],
            "price_formatted": "327,90 \u20ac",
            "has_pros_and_cons": true
        }
    ],
    "success": true,
    "category": {
        "id": "19116",
        "title": "Handys & Smartphones"
    },
    "pagination": {
        "page": 1,
        "has_more": true,
        "page_size": 36,
        "total_pages": 112,
        "total_offers": 51082,
        "total_results": 58941,
        "total_products": 7859
    },
    "category_id": "19116",
    "related_queries": [
        "samsung a56"
    ]
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | Returned when a required parameter is missing or a value is out of range. No credits are charged. |
| 404 | Not Found | Returned when idealo does not know the product, shop or page. No credits are charged. |
| 503 | Service Unavailable | Returned when idealo could not be read after several attempts. Failed requests are not charged. Try again. |
| 502 | Unexpected Response | Returned when idealo answers with a page this API cannot read. Failed requests are not charged. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)