Idealo APIIdealo.it ↗
Search idealo.it for products and shop offers across Italian retailers. Get titles, prices, URLs, and result counts via a single search endpoint.
What is the Idealo API?
The Idealo.it API exposes 1 endpoint — search_products — that returns up to 60 result tiles per page from Italy's leading price-comparison site. Each response includes product titles, comparison URLs, lowest prices, offer counts per product, and site-reported totals for both catalogue products and individual shop offers, giving you a structured view of the Italian retail market for any free-text query.
curl -X GET 'https://api.parse.bot/scraper/55dacbf8-63ad-4565-8f31-2b7c9aaf89d9/search_products?query=cuffie+bluetooth' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace idealo-it-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: idealo.it product search — bounded, re-runnable."""
from parse_apis.idealo_it_api import Idealo, SortOrder, InvalidInput
client = Idealo()
# Browse cheapest bluetooth headphones; limit= caps total items fetched.
for product in client.products.search(query="cuffie bluetooth", sort=SortOrder.PRICE_ASC, limit=5):
print(product.title, product.price, product.price_formatted)
# Grab the top result by popularity and inspect its fields.
top = client.products.search(query="cuffie bluetooth", limit=1).first()
if top is not None:
print(top.title, "| offers:", top.offer_count, "| bestseller:", top.is_bestseller)
if top.test_rating is not None:
print(" test rating:", top.test_rating)
# Use the scalar wrapper to read page-level metadata the paginator discards.
page = client.products.search_page(query="cuffie bluetooth")
print("total products:", page.total_products, "| total offers:", page.total_offers, "| has_more:", page.has_more)
# Typed error handling — invalid sort values raise InvalidInput.
try:
client.products.search_page(query="cuffie bluetooth", sort="bad_sort")
except InvalidInput as e:
print("caught invalid input:", e.message)
print("exercised: products.search / products.search_page / InvalidInput")
Searches idealo.it for a free-text query and returns one page of the result list exactly as the site ranks it. Each page holds up to 60 result tiles of two kinds: 'product' tiles (an idealo catalogue product with its comparison-page url, lowest price marked price_is_from=true, offer_count and ratings) and 'offer' tiles (a single shop listing with shop_name, delivery and shipping text, no comparison page). Fields that do not apply to a tile kind are null. One upstream page fetch per call. Pagination is caller-driven via page (1-based, default 1); the site exposes at most 67 pages per query, so total_results (the site's own count of matching products plus offers) can far exceed what is reachable; has_more is true while another page is reachable. A query the site has no results for returns an empty items list with total_results 0. Prices are in EUR as shown on the Italian site.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based result page; valid range 1 to 67. A page beyond the site's reachable range for that query returns an empty items list. |
| sort | string | Result ordering, mirroring the site's sort menu. Omitted = the site's popularity ranking. |
| queryrequired | string | Free-text search term, e.g. a product type or model name. |
{
"type": "object",
"fields": {
"page": "page number served",
"sort": "sort order applied",
"items": "array of result tiles in site order; each has type ('product'|'offer'), id (product id or offer hash), title, url (product comparison page, null for offers), image_url, details (product spec summary, null for offers), test_rating (e.g. '9/10', null if none), review_count, offer_count (products only), price (EUR number), price_formatted, price_is_from (true when price is the lowest of several offers), shop_name/delivery_text/shipping_text (offers only), discount_badge, is_bestseller",
"query": "echo of the search term used",
"has_more": "true when a further page can be requested",
"page_size": "maximum tiles per page (60)",
"total_offers": "site-reported count of matching single shop offers",
"total_results": "site-reported count of matching results (products + offers)",
"total_products": "site-reported count of matching catalogue products"
},
"sample": {
"data": {
"page": 1,
"sort": "price_asc",
"items": [
{
"id": "91a75c02909648729583b6de8386d006",
"url": null,
"type": "offer",
"price": 0.5,
"title": "Cuffie Bluetooth,aruariauau-Auricolari Bluetooth g22-093",
"details": null,
"image_url": "https://cdn.idealo.com/offer/it/cuffie-bluetooth-aruariauau-auricolari-bluetooth-g22-093-168t14091a75c02909648729583b6de8386d00682c22a0f.jpg",
"shop_name": "amazon-marketplace.it",
"offer_count": null,
"test_rating": null,
"review_count": null,
"delivery_text": "Disponibilità: solo 1",
"is_bestseller": false,
"price_is_from": false,
"shipping_text": "spedizione gratuita",
"discount_badge": null,
"price_formatted": "€ 0,50 IVA compresa"
},
{
"id": "214029986",
"url": "https://www.idealo.it/confronta-prezzi/214029986/apple-airpods-5.html",
"type": "product",
"price": 129.9,
"title": "Apple AirPods 5",
"details": "Cuffie Bluetooth, Open-Ear, Senza cavo , Apple Siri, Bluetooth 5.3, Controllo attivo del rumore",
"image_url": "https://cdn.idealo.com/folder/Product/214029/9/214029986/s10_produktbild_mittelgross/apple-airpods-5.jpg",
"shop_name": null,
"offer_count": 37,
"test_rating": "9/10",
"review_count": 2,
"delivery_text": null,
"is_bestseller": false,
"price_is_from": true,
"shipping_text": null,
"discount_badge": null,
"price_formatted": "a partire da € 129,90"
}
],
"query": "cuffie bluetooth",
"has_more": true,
"page_size": 60,
"total_offers": 139386,
"total_results": 164217,
"total_products": 24831
},
"status": "success"
}
}About the Idealo API
What the API Returns
The search_products endpoint accepts a free-text query and returns one page of idealo.it search results in the same order the site applies. Each page holds up to 60 tiles (page_size: 60), and the has_more flag tells you whether additional pages exist. Response-level fields include total_results, total_products, and total_offers — the site's own reported counts — so you can gauge result depth before paginating further.
Result Tile Structure
Each item in the items array carries a type field of either 'product' or 'offer'. Product tiles represent idealo catalogue entries with an aggregated comparison page (url), a title, a product id, and a lowest-price figure flagged with price_is_from: true. Offer tiles represent individual shop listings with their own identifiers and direct URLs. This distinction lets you separate aggregated product comparisons from raw retailer listings in a single response.
Sorting and Pagination
The optional sort parameter mirrors the sort options available on idealo.it's search interface (e.g. price ascending, popularity). Omitting it returns results in the site's default popularity ranking. Pagination uses a 1-based page integer with a valid range of 1–67; requesting a page beyond what the site returns for a given query produces an empty result set rather than an error. The query field is always echoed back in the response for easy request tracking.
The Idealo API is a managed, monitored endpoint for Idealo.it — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when Idealo.it changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official Idealo.it API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track lowest prices across Italian shops for a specific product model using
total_offersand price fields. - Build a product catalogue for the Italian market by paginating
search_productswith targeted queries. - Monitor which retailer listings appear for a brand query by filtering
itemswheretypeis'offer'. - Compare result counts (
total_productsvstotal_offers) across categories to estimate market competition. - Identify canonical idealo product pages for affiliate linking using the
urlfield ontype: 'product'tiles. - Sort search results by price to surface the cheapest options in a given category using the
sortparameter. - Feed product titles and comparison URLs into a price-alert service that watches specific Italian retailers.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does idealo.it have an official developer API?+
How does the API distinguish between a catalogue product and a single shop listing?+
items array includes a type field. A value of 'product' means an idealo catalogue entry aggregating multiple shops, with a lowest-price figure marked price_is_from: true. A value of 'offer' means a single retailer listing with its own identifier and URL.Is historical or time-series price data available through this API?+
search_products endpoint. You can fork this API on Parse and revise it to add an endpoint that fetches price history from individual product pages.Can I retrieve detailed product specifications or user reviews from idealo.it?+
search_products endpoint returns tile-level data: title, URL, price, and offer counts. Detailed specs, editorial descriptions, and user reviews that appear on idealo product pages are not included. You can fork this API on Parse and revise it to add a product-detail endpoint covering those fields.What happens when I request a page number beyond the site's available range for a query?+
page range is 1–67, but the actual number of available pages depends on the query. Requesting a page beyond the site's reachable range for that query returns an empty result set — items will be an empty array and has_more will be false. No error is thrown.