Idealo Product Search & Merchant Offers API

Submit exactly one free-text search phrase. In the body field, enter JSON text such as {"country":"de","values":["iphone 16"]}. country must be de or at, and values must be an array containing one string. Direct gateway clients send this JSON text as the string value of the public body parameter, not as separate country and values parameters. Germany was live-verified; Austria is declared by the request schema but was not tested. The observed creation response was {"error":false,"job_id":"..."}. It accepted the lookup; it did not contain product data or establish that a match exists. Use get-job with the returned job_id and wait for a terminal status. The completed German iphone 16 search returned 36 found listing rows. Each results row carried query, status and result; listing fields included id, name, url, image_urls, description, review_rating, review_count, category_ids, price_min, offers_count, country and fetched_at. Several metadata fields and price_avg/price_max were null. Counts and prices describe that observation, not a fixed result size. The first listing, 204736899, had offers_count=512 but offers=[]. Keyword discovery does not supply individual merchant offers. Review candidate variants, then submit selected country-and-ID pairs to search-by-id. The separately enriched listing 204771161 was the 128GB black variant, not the first listing. A nonsense phrase was also accepted as a job and later completed with one not_found row, result:null and summary.found=0. Do not turn a missing product into a zero price.

Submit one Idealo numeric listing ID with its country. Enter JSON text in body, for example {"country":"de","values":["204771161"]}; direct gateway clients provide that text as the string value of body. country accepts de or at, with Germany verified and Austria untested. values must contain exactly one ID string. Choose an ID from a matching-country listing; the documented validation rejects 0 and IDs with a leading zero when creating the job. No shop account, price update or offer submission is involved. The verified creation response contained error:false and job_id. Retrieve that job through get-job. The observed terminal result for 204771161 had status:completed, operation:search-by-id, done=1, total=1 and summary.found=1. Its found row echoed query and result.id=204771161, with name Apple iPhone 16, price_min, price_avg, price_max, offers_count, image_urls, country and fetched_at. Brand, description and review fields were null in this result. The result contained 20 offers. Observed offer fields included title, sellerId, shop_name, shop_url, shop_type, marketplace_name, shop_review_rating, shop_review_count, position, condition, currency, price, shipping, total, voucher, availability_code and availability_text. free_return and direct_sale could be null; classification and confidence were also present in this sample. Prices were in EUR. Some standalone shops used the string N/A for marketplace_name. Use delivered total alongside availability and condition rather than item price alone. The earlier search summary for this ID counted 82 offers, so the 20 returned rows do not establish complete merchant coverage.

Look up one GTIN, EAN, UPC or JAN barcode containing 8–14 digits. Preserve it as a string, including any leading zeros. Enter JSON text in body, such as {"country":"de","values":["4008400401621"]}; direct gateway clients send this text as the string value of body. The JSON object requires country de or at and values with exactly one barcode string. Only Germany was live-verified. The observed creation response contained error:false and job_id. After retrieval through get-job, the completed German lookup for EAN 4008400401621 returned one found Ferrero Nutella result, id 4375366, with the matching ean, country:de, fetched_at, image_urls, category_ids, price_min, price_avg, price_max, offers_count and nine detailed EUR offers. Each supplied offer included its title, shop_name, price, shipping, total, condition and availability, with classification:product_page_match and confidence:high; the product had page_type:product. Some product metadata, including brand and description, was null. Validate both product identity and quantity before comparing prices. This EAN identifies Nutella 450g, yet one returned offer was a 15 x 450g multipack with the same product_page_match/high labels. Those labels alone do not establish a single-unit or exact-variant match. Matching on other page types is documented but was not observed, and no universal classification accuracy or complete merchant coverage is established. Store the returned ean, listing id, country and timestamp with any approved catalog match.

Submit a known Idealo product link rather than a keyword or barcode. Enter a JSON object as text in body with country and exactly one URL string in values; direct gateway clients provide that text as the string value of body. country accepts de or at, and the product URL must belong to the same country. The placeholder uses the German listing URL observed in keyword results, not an invented product link. Do not send category pages, arbitrary shop URLs or a list of links. The documented creation contract returns a job_id for retrieval through get-job. The route is intended to retrieve product and merchant-offer data for the addressed listing, but no successful live URL-lookup response was supplied. Its acceptance behavior and exact result fields therefore remain unverified; the detailed fields observed on ID and barcode jobs must not be presented as a verified response from this route. Test this particular route with a current, country-matched product link before relying on it. Keep the submitted link with the eventual per-result status and validate any returned identity.

Pass the fresh job_id returned by a keyword, ID, barcode or URL lookup. No durable example job ID is provided: results are retained for one hour after completion. The documented lifecycle is pending followed by completed or failed, with results empty while pending. Poll at a spaced interval, for example starting around five seconds, and apply backoff, a deadline and a total-call budget. A lookup needs at least one creation call and one retrieval call; extra polls add network calls without guaranteeing earlier completion. Observed completed responses contained error, job_id, status, source, operation, country, created_at, done, total, summary and results. summary included found, not_found, error and classifications. Each result row carried query, status and result. For ID and barcode lookups the found result included product identity, price summaries, offers and fetched_at. Keyword lookup instead returned listing summaries with offers=[]. A single-term job had done=1 and total=1 but 36 found result rows, so these counters do not measure the number of distinct listings. Top-level error:false and status:completed do not mean a product was found. The verified nonsense-term job completed with done=1, total=1, summary.found=0, summary.not_found=1, summary.error=0 and one row with status:not_found and result:null. Item errors and failed jobs are separate documented outcomes; inspect both job status and every result status. When an item supplies errorCode, correct invalid_query rather than blindly retrying it, and bound any retry policy for other codes. Collect and store usable snapshots with the requested country, query, operation and product fetched_at before the job expires. created_at describes job creation, not the product observation time. Nullable fields are not zero, false or empty strings. This endpoint retrieves temporary job output; it does not provide a historical-price archive. An unknown or expired ID has a documented Job not found response, but that error branch was not live-tested.

Make a parameter-free service-liveness request. The documented successful response is {"ok":true}. This endpoint was not included in the supplied live observations, so its response and current availability remain unverified. A successful ping only indicates service reachability. It does not create a product lookup, return listings, verify an EAN match, prove that merchant collection works or establish price freshness. Keep reachability alerts separate from lookup-job failures and legitimate not_found outcomes. Use a product workflow that creates a job and inspects its terminal result when you need collection-level assurance; ping is not a substitute.