idealo

Search idealo catalog and display results in a carousel. IMPORTANT: Search results include comprehensive filter information to enable refinement:

"availableCategories" (category IDs and names) "availableManufacturers" (brand IDs and names) "availableFilters" (attribute filters like color, material grouped by type

• NOT sizes)

"sizeAttributes" (size-specific filters like shoe sizes, clothing sizes) "suggestedFilters" (recommended filters to apply based on search) Use these IDs from the search response to refine subsequent searches - no separate lookups needed!

CRITICAL-CONSTRAINT: Search filters (includeSearchFilters) and Size filters (includeSizeFilters) can ONLY be used together with at least one category ID (includeCategories). Never use includeSearchFilters or includeSizeFilters without includeCategories! This will cause an error. WRONG (will fail with error): {"query": "oled tv", "filters": {"includeSearchFilters": ["123"]}} // Missing includeCategories! {"query": "shoes", "filters": {"includeSizeFilters": ["456"]}} // Missing includeCategories!

CORRECT (two-step workflow): Step 1: Search without attribute filters to discover category IDs {"query": "oled tv"} → response includes availableCategories like [{"categoryId": "789", "categoryName": "4K-Fernseher"}] Step 2: Refine with BOTH category AND attribute filters {"query": "oled tv", "filters": {"includeCategories": ["789"], "includeSearchFilters": ["123"]}}

Be strict if you put search filter you should not include it into query anymore. e.g. if user says "blue gaming headset home console" you should set category filter to "gaming headset" and search filter to "blue" and search filter to "home console", so the query only contains "headset". This also applies when the user starts with an abstract intent (e.g. “Xmas presents for my kids”): do NOT search the full abstract sentence as-is; translate it into a concrete product-like query (e.g. "lego", "puzzle", "kinderbuch") and if you later apply category/attribute filters from IDs, keep those concepts out of the query string.

Examples:

First search for "headset" → get availableCategories with IDs like "789": "Gaming Headsets" → get availableFilters with IDs like "123456": "Color: Black" → refine with includeCategories: ["789"], includeSearchFilters: ["123456"].

First search for "stiefel" (boots) → get availableCategories with IDs like "123": "Stiefel" → get sizeAttributes with IDs (attributeKeyValue) like "456_789": "39" → refine with includeCategories: ["123"], includeSizeFilters: ["456_789"].

First search for "macbook" → get availableManufacturers with IDs like "456": "Apple" → get availableCategories with IDs like "7890": "Laptops" → get availableFilters with IDs like "123456": "Color: Himmelblau" → refine with includeManufacturers: ["456"], includeCategories: ["7890"], includeSearchFilters: ["123456"].

First search for "laptops" → get availableCategories with IDs like "12345": "Notebooks" → refine with includeCategories: ["12345"].

If the user query is abstract / intent-based and not a clear product/category (e.g. "Xmas presents for my kids", "gift for my dad", "things for a new apartment", "present for a 10 year old"), use real-world knowledge to decide the MOST likely concrete shopping category/product keyword the user means, and search idealo using that concrete keyword so the user sees products immediately; because this is a guess, also offer a few alternative likely categories for follow-up. → Example: user: "Xmas presents for my kids"

Search right away with a concrete guess: {"query": "lego"} (show carousel)

Offer alternatives (user can pick next): "children books", "puzzles", "board games", "arts & crafts" → Example: user: "gift for a 10 year old who likes building stuff"

Search: {"query": "lego technic"} (or "construction set")

Offer alternatives: "robot kits", "science kits", "puzzles" → Example: user: "present for new apartment"

Search: {"query": "kitchen gadgets"} (or "coffee machine" depending on phrasing)

Offer alternatives: "lamps", "home decor", "vacuum cleaner", "bedding" → Example: user: "romantic gift for my partner"

Search: {"query": "jewelry"} (or "perfume" depending on phrasing)

Offer alternatives: "watches", "candles", "smart photo frame" → Example: user: "Xmas presents for my kids under 30€"

Search: {"query": "lego", "filters": {"maxPrice": 30}}

Offer alternatives: "puzzles", "board games", "craft kits" If the user chooses an alternative category, run a new idealo search using that alternative’s concrete keyword/category, then use the returned IDs (availableCategories / availableFilters / sizeAttributes) for refinement as usual (and remember: includeSearchFilters/includeSizeFilters only together with includeCategories).