Mercadona Search API searches public grocery products in Spain. Each item has the name, brand, size, EUR price, unit price, promo price, availability, image, categories and EAN.
Send query or a public category id. lang is es, en or ca; wh is a soaked hub code or a 5-digit store; sort is relevance for text search, or price_asc and price_desc with a category (the full list is sorted before paging); page is 1-based. Send query or category, never both. Prices are in EUR. Rating and review count are null because the platform publishes no reviews. Ids are strings and round-trip unchanged. Costs 1 credit per request; empty results and failed requests are free.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
6 optional filters available.
string
Optional
Search text, 1 to 120 characters, for example leche.
coffee shops
string
Optional
Category id from the categories route, for example 112. Required unless query is sent.
example
string
Optional
es, en or ca (default es).
example
string
Optional
Soaked hub code vlc1, mad1, mad2, mad3, bcn1, svq1 or alc1, or a 5-digit store such as 46001 (default vlc1).
example
string
Optional
relevance for text search; price_asc or price_desc with a category, sorting the full list before paging.
relevance
integer
Optional
1-based page number, default 1.
1
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"lang": "es",
"page": 1,
"sort": "relevance",
"count": 2,
"items": [
{
"id": "17153",
"name": "Leche entera",
"size": "1 L",
"unit": "L",
"brand": "Mercadona",
"image": "https://prod-mercadona.imgix.net/product.jpg",
"price": 0.95,
"rating": null,
"currency": "EUR",
"position": 1,
"sale_price": 0.95,
"unit_price": 0.95,
"availability": {
"status": "available"
},
"review_count": null,
"regular_price": 1.1
}
],
"query": "leche",
"category": null,
"warehouse": "vlc1",
"has_next_page": true
},
"meta": {
"credits": 1,
"billable": true,
"endpoint_family": "search"
},
"success": true
}
Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A required parameter or a value is invalid. This response is not billable.
{
"errors": {
"query": [
"A query or a category is required, e.g. query=leche."
]
},
"message": "The request validation failed"
}Upstream Unavailable
The source could not be reached after several tries. This response is not billable.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "search"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "Mercadona could not be reached. Please retry shortly."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.