Blog / API guides

Idealo API: Compare Product Prices Across Shops as JSON

22 Oct 2026Perceptlayer9 min read

To get idealo price comparison data as JSON, call GET /v1/idealo/search with a query to find products, then pass a product's id as product_id to GET /v1/idealo/offers for that product's offers. Each call costs 1 credit, and failed calls cost nothing. This guide walks through both calls, the parameters, a real search response and a cost estimate for a price monitor.

What does the idealo API return?

The Idealo API on Perceptlayer exposes 13 endpoints on the price comparison site idealo.de, all returning JSON and all costing 1 credit per successful call. They cover keyword search, products, offers, reviews, shop profiles, categories, deals and trending items. Data is collected from publicly available sources and returned as found at the time of the call.

The endpoints fall into three groups, and most workflows touch only the first two.

The site sits in the Marketplaces area of the catalogue, alongside other shopping sources. If you also need Google's view of the same products, see the Google Shopping API guide.

How do you authenticate and make the first call?

You need a Perceptlayer API key (they start with sk_live_), sent in the X-API-Key header. Get a free API key by verifying an email address: that gives you 1,000 free credits every month, no credit card. Where a client can't set headers, the api_key query parameter works instead; see the authentication docs.

Search is the natural first call. query is optional on this endpoint, but a keyword is what makes the result useful:

curl "https://api.perceptlayer.com/v1/idealo/search?query=air+fryer" \
  -H "X-API-Key: $API_KEY"

Every successful response carries X-Credits-Used and X-Credits-Remaining headers, so you can watch the balance from the response itself. More on requests and responses is in the requests docs.

Which parameters does the search endpoint take?

GET /v1/idealo/search takes eight optional parameters and no required ones. A query of up to 200 characters searches by keyword, category_id narrows to one category, and price_min and price_max bound the price. sort and item_states[] accept fixed values, listed below, and page moves through results.

The docs for this endpoint don't state defaults or page sizes, so check the response's pagination block instead of assuming. To get category IDs, call /v1/idealo/categories, which takes no parameters. For type-ahead input, /v1/idealo/autocomplete takes a required query (up to 100 characters) and an optional limit.

What does a search response look like?

A search response is a JSON object with a results array of products, plus facets, pagination and the category. Each product carries its id, title, a numeric price, a currency, an offer_count and a cheapest_offer object. The excerpt below is a recorded response for query=air fryer, trimmed with ….

{
  "success": true,
  "query": "air fryer",
  "category_id": "3513",
  "sort": "RELEVANCE_DESC",
  "results": [
    {
      "id": "203597427",
      "type": "PRODUCT",
      "title": "Ninja AF500",
      "subheading": "Heißluftfritteuse",
      "category_id": "3513",
      "url": "https://www.idealo.de/preisvergleich/OffersOfProduct/203597427_-af500-ninja.html",
      "price": 162.9,
      "price_formatted": "162,90 €",
      "currency": "EUR",
      "offer_count": 80,
      "rating": {
        "user_review_count": 453,
        "score_percent": 100,
        "test_rating": "2,0"
      },
      "cheapest_offer": {
        "offer_key": "7abc0f760d8206c9f1c6127689df9ed0",
        "shop_id": "301558",
        "shop_name": "alza.de",
        "shipping_costs": "4,99 €",
        "shipping_is_free": false
      },
      …
    },
    …
  ],
  "pagination": {
    "page": 1,
    "page_size": 36,
    "total_pages": 112,
    "has_more": true,
    "total_results": 4805,
    …
  },
  "category": {
    "id": "3513",
    "title": "Fritteusen"
  },
  …
}

A few details matter when you parse it. The category title and facet names (Hersteller, Produkttyp) are in German, because the source is the German site. price is a number and price_formatted is a display string with a decimal comma, so use price for any calculation. And shipping_costs is a string, not a number, so parse it before adding it to a total.

Note that search matched this query to category 3513 (Fritteusen) on its own, and reports it in the response. This is the first thing to check if results look off.

How do you get the offers for a product?

Pass the id from a search result as product_id to GET /v1/idealo/offers to get the offers for that product. The offer_count in the search result (80 for the Ninja AF500 in the recorded response) gives you a number to compare against what comes back, since the endpoint also takes page and all.

curl "https://api.perceptlayer.com/v1/idealo/offers?product_id=203597427&include_shop_ratings=true" \
  -H "X-API-Key: $API_KEY"

We haven't recorded an offers response for this guide, so there's no excerpt here. Run the call in the playground on the Idealo offers page with your own key to see the exact fields, and print the keys before you write a parser. That's a better habit than trusting any guide, including this one.

Worked example: from keyword to saved offers

This Python script searches for a keyword, sorts by price, takes the three cheapest products, and fetches the offers for each. It prints what the search response already tells you (title, lowest price, offer count, cheapest shop) and saves each raw offers response to a JSON file for inspection. It needs only requests.

import json
import os
import requests

BASE = "https://api.perceptlayer.com/v1/idealo"
HEADERS = {"X-API-Key": os.environ["API_KEY"]}


def get(path, **params):
    r = requests.get(f"{BASE}/{path}", headers=HEADERS, params=params, timeout=30)
    r.raise_for_status()
    return r.json()


search = get("search", query="air fryer", sort="PRICE_ASC")
offers_by_product = {}

for product in search["results"][:3]:
    cheapest = product.get("cheapest_offer", {})
    print(
        product["title"],
        product["price"],
        product["currency"],
        f'{product["offer_count"]} offers',
        cheapest.get("shop_name"),
    )
    offers_by_product[product["id"]] = get("offers", product_id=product["id"])

for product_id, offers in offers_by_product.items():
    print(product_id, list(offers.keys()))
    with open(f"offers_{product_id}.json", "w") as f:
        json.dump(offers, f, ensure_ascii=False, indent=2)

That is 1 search call plus 3 offers calls: 4 calls × 1 credit = 4 credits, assuming one offers call per product. The final loop prints the top-level keys of each offers response and saves the full body, so you can pick the fields you need before writing real parsing code; the price table is the next step, built from those fields. The search results here are the cheapest matches, not the best matches: use sort=RELEVANCE_DESC (the default in the recorded response) for relevance. Handle failures with the patterns in handling API errors in Python, and read the errors docs for the full list of codes.

What else can you look up for a product?

Once you have a product_id, four more endpoints take it, each at 1 credit. product, reviews (with an optional page) and international-prices take a product_id, and products accepts a list of IDs through ids[] for batch lookups. We haven't recorded responses for these, so check their fields in the playground. Shops have their own pair: shop takes a shop_id, and shop-products takes a shop_id plus a category_id.

Each search result also carries a url field with the product's idealo.de address (for example this Ninja AF500 page), which is handy for spot-checking a result by eye. The shop_id in cheapest_offer (here 301558 for alza.de) is the value the shop endpoints expect. That links the two halves of the data: from a product to the shops selling it, and from a shop back to its catalogue. For discovery without a keyword, brand-products lists products by brand or brand_id, and deals takes a required category_id with an optional deal_type of bargain or short_term.

How much does it cost to monitor prices?

Every Idealo endpoint costs 1 credit per successful call, so cost is the number of calls. The figures below are minimums: they assume one offers call per product. The endpoint also takes page and all, and each extra call you make with them is another credit. Failed calls cost nothing and return X-Credits-Used: 0. A price monitor that refreshes offers for a fixed watchlist spends at least one credit per product per refresh, plus a one-time search or products call to discover the IDs.

The free tier's 1,000 monthly credits cover the last row, or the weekly watchlist if every product needs only one call. The daily watchlist (at least 6,000 credits) is a purchase: credits come in prepaid packs starting at 10,000, last 12 months, and have no subscription. See pricing for what credits cost and the credits docs for how they're debited.

If you don't need hourly data, cache responses between runs; the caching guide shows how TTLs turn into saved credits. For paged results, use the pagination guide. For a full scheduler built on a similar source, read building a price tracking agent in Python.

When is the idealo API the wrong tool?

This endpoint set fits one job: you want to compare offers for one product, starting from search results that already show the cheapest shop and its shipping cost. The recorded response is in euros with German-language fields, so that's the market it was recorded against. It's the wrong tool when you need a contractual feed from the shop itself, since Perceptlayer returns publicly available data as found. Check your use case against the site's own terms before building on the data.

The product_id is an idealo ID, so it only works with the idealo endpoints. If you compare idealo prices against another store, plan on matching items yourself; the post on deduplicating listings across sources covers matching without shared IDs. For a US-style product search, the Walmart product search guide is the closer fit, and Mercado Libre covers Latin America.

Two practical limits apply to any live data. Prices change between calls, and a response is what the page showed at that moment. Requests also have no idempotency key, so if a client timeout loses a reply, the call may have succeeded and been billed.

Can an AI agent call the idealo endpoints?

Yes. The Perceptlayer MCP server at https://api.perceptlayer.com/mcp exposes search_endpoints, get_endpoint and call_endpoint. The first two only look up the catalogue and cost nothing; call_endpoint runs an endpoint such as /v1/idealo/search and spends its credits on success only. An agent can then answer "who sells this cheapest?" from live data.

To add it in Claude Code:

claude mcp add --transport http perceptlayer https://api.perceptlayer.com/mcp --header "Authorization: Bearer $API_KEY"

The AI agents docs cover the other clients. Keep in mind that a search response is large (facets, price buckets, related queries), so trim what you hand a model; trimming API responses for LLM context shows how.

Next step: open the playground on the Idealo API page, run a search for a product you care about, then paste its id into the offers endpoint.

price comparisonidealoeuropeecommerceoffers