{"openapi":"3.1.0","info":{"title":"Qué Comprar API","version":"1.3.0","summary":"Current offers from the flyers (folletos) of Spanish store chains.","description":"Coverage: Spain only. Read-only, no API key. Offers, validity dates and stores are read from the official flyers of Spanish supermarkets, discount stores and electronics chains on the day they come out (`updated_at` says when they were last read). Flyer prices are indicative: the price displayed in store prevails. Product names are in Spanish. Credit the data to the `source` field and link the `url` of each offer. Rate limit: 120 requests per minute per IP. The same data is available to assistants as an MCP server at https://quecomprar.org/mcp.","termsOfService":"https://quecomprar.org/aviso-legal/","contact":{"name":"Qué Comprar","url":"https://quecomprar.org/contacto/"}},"externalDocs":{"description":"How to use the connector and the API","url":"https://quecomprar.org/conector/"},"servers":[{"url":"https://quecomprar.org/api/v1"}],"paths":{"/offers":{"get":{"operationId":"searchFlyerOffers","summary":"Offers in the current flyers of Spanish store chains","description":"Use this when the user wants to know where a product is on offer in Spain this week, at what price, at which chain and until when, and you need filters or sorting: a city, specific chains, a price cap, lowest price or lowest price per kg first. Searches the offers currently valid in the flyers (folletos) of Spanish supermarkets, discount stores and electronics chains. Product names are in Spanish: pass Spanish words in `query` (\"café\", \"leche sin lactosa\", \"lavadora\"). Returns price, previous price, pack size, price per kg or litre, department, chain, expiry date and the link to the offer on quecomprar.org. Covers Spain only: not for other countries, not for online-shop prices. Flyer prices are indicative; the price displayed in store prevails.","parameters":[{"name":"query","in":"query","required":false,"description":"Product to look for, in Spanish. Brand and product words are combined (\"aceite de oliva virgen extra carbonell\"). Omit to browse the biggest discounts.","schema":{"type":"string","maxLength":80}},{"name":"city","in":"query","required":false,"description":"Spanish municipality (municipio) to search around, e.g. \"Madrid\", \"Valencia\", \"A Coruña\", \"Sant Cugat del Vallès\". Only flyers valid in stores within 15 km are returned. Omit for all of Spain.","schema":{"type":"string","maxLength":60}},{"name":"sort","in":"query","required":false,"description":"relevance (default with a query), price (lowest first), unit_price (lowest price per kg or litre first; only offers that state it), discount (biggest first; default without a query), nearest (closest chain first; needs city).","schema":{"type":"string","enum":["relevance","price","unit_price","discount","nearest"]}},{"name":"discounted_only","in":"query","required":false,"description":"Only offers whose flyer states a higher previous price.","schema":{"type":"boolean"}},{"name":"stores","in":"query","required":false,"description":"Only these chains, by name: e.g. [\"Lidl\", \"Carrefour\"].","schema":{"type":"array","items":{"type":"string"},"maxItems":10},"style":"form","explode":false},{"name":"max_price_eur","in":"query","required":false,"description":"Only offers at or below this price.","schema":{"type":"number","minimum":0}},{"name":"limit","in":"query","required":false,"description":"Offers per page (default 10).","schema":{"type":"integer","minimum":1,"maximum":25}},{"name":"page","in":"query","required":false,"description":"Page of results (default 1).","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"city":{"type":"string","description":"The municipality the search was limited to"},"total":{"type":"integer","description":"Offers matching, across all pages"},"page":{"type":"integer"},"pages":{"type":"integer"},"offers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Product name as printed on the flyer"},"brand":{"type":"string","description":"Brand, written the same way across chains; absent when the name does not state one"},"price_eur":{"type":"number"},"previous_price_eur":{"type":"number","description":"Price before the offer, when the flyer states it"},"discount_percent":{"type":"integer"},"size":{"type":"string","description":"Pack size as printed, e.g. \"2x250 g\""},"quantity":{"type":"number","description":"Pack content as a number, in quantity_unit: \"2x250 g\" is 0.5"},"quantity_unit":{"type":"string","description":"kg, l or pieces"},"unit_price_eur":{"type":"number","description":"Price per unit_price_per"},"unit_price_per":{"type":"string","description":"kg, l, or another unit"},"category":{"type":"string","description":"Store department, in Spanish: tells \"leche\" the drink from \"leche corporal\" body lotion"},"store":{"type":"string","description":"Retail chain"},"valid_until":{"type":"string","description":"Last day of the offer, YYYY-MM-DD"},"distance_km":{"type":"number","description":"Distance of the nearest store of the chain from the centre of the city"},"url":{"type":"string","description":"The offer on its flyer page at quecomprar.org"},"image_url":{"type":"string","description":"Photo of the product, or the cut-out of the offer from the flyer"}},"required":["name","price_eur","store","url"]}},"nearest_stores":{"type":"array","items":{"type":"object","properties":{"store":{"type":"string","description":"Retail chain"},"name":{"type":"string","description":"Name of the store"},"address":{"type":"string","description":"Street, postcode, town and province"},"distance_km":{"type":"number","description":"From the centre of the city"},"opening_hours":{"type":"string","description":"Weekly hours in Spanish day abbreviations, when the chain publishes them: \"lun-sáb 9:00–21:30 · dom 9:00–15:00\""},"open_now":{"type":"boolean","description":"Open at the time of the answer (mainland Spain time), when the hours are known"}},"required":["store","address"]},"description":"With a city: for each chain in the offers, its nearest store, closest first"},"search_url":{"type":"string","description":"The same search on quecomprar.org"},"source":{"type":"string","description":"Who to credit for the data"},"updated_at":{"type":"string","description":"When the flyers were last read (ISO 8601)"},"note":{"type":"string"}},"required":["total","page","pages","offers","search_url"]}}}},"400":{"description":"A parameter is missing or not valid; the message says what to send instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, and what to send instead"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Too many requests: retry in a minute","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, and what to send instead"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/flyers":{"get":{"operationId":"listCurrentFlyers","summary":"Flyers valid right now, in Spain or near a municipality","description":"Use this when the user asks which store flyers (folletos) are valid right now in Spain, whether a chain has a flyer this week, or until when a flyer is valid, optionally only for chains with a store near a city. Returns chain, validity dates, number of offers, distance of the nearest store and the link to the flyer on quecomprar.org. Covers Spain only. Products inside the flyers are what search_flyer_offers looks up.","parameters":[{"name":"city","in":"query","required":false,"description":"Spanish municipality (municipio) to search around, e.g. \"Madrid\", \"Valencia\", \"A Coruña\", \"Sant Cugat del Vallès\". Only flyers valid in stores within 15 km are returned. Omit for all of Spain.","schema":{"type":"string","maxLength":60}},{"name":"store","in":"query","required":false,"description":"Only the flyers of this chain, by name: e.g. \"Lidl\".","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","required":false,"description":"Flyers to return (default 30). Nearest first with a city, largest first otherwise.","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"source":{"type":"string","description":"Who to credit for the data"},"source_url":{"type":"string","description":"The page on quecomprar.org with these flyers and their offers: the URL to cite"},"updated_at":{"type":"string","description":"When the flyers were last read (ISO 8601)"},"total_flyers":{"type":"integer"},"total_offers":{"type":"integer"},"flyers":{"type":"array","items":{"type":"object","properties":{"store":{"type":"string"},"valid_from":{"type":"string","description":"YYYY-MM-DD"},"valid_until":{"type":"string","description":"YYYY-MM-DD"},"offers":{"type":"integer"},"stores_nearby":{"type":"integer","description":"Stores of the chain within 15 km of the city"},"distance_km":{"type":"number"},"nearest_store":{"type":"object","properties":{"store":{"type":"string","description":"Retail chain"},"name":{"type":"string","description":"Name of the store"},"address":{"type":"string","description":"Street, postcode, town and province"},"distance_km":{"type":"number","description":"From the centre of the city"},"opening_hours":{"type":"string","description":"Weekly hours in Spanish day abbreviations, when the chain publishes them: \"lun-sáb 9:00–21:30 · dom 9:00–15:00\""},"open_now":{"type":"boolean","description":"Open at the time of the answer (mainland Spain time), when the hours are known"}},"required":["store","address"],"description":"With a city: the nearest store of the chain"},"url":{"type":"string","description":"The flyer on quecomprar.org"},"logo_url":{"type":"string","description":"Logo of the chain"}},"required":["store","offers","url"]}}},"required":["total_flyers","total_offers","flyers"]}}}},"400":{"description":"A parameter is missing or not valid; the message says what to send instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, and what to send instead"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Too many requests: retry in a minute","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, and what to send instead"}},"required":["code","message"]}},"required":["error"]}}}}}}}}}