Mercadona API

Overview

The Mercadona API returns product and price data from Mercadona’s online catalog: search by keyword, look up a product by id or barcode (EAN), walk the category tree and every brand, and pull discovery feeds like price drops, new arrivals, home-page campaigns and best sellers. Prices and assortment depend on the warehouse that serves each address, so every catalog endpoint accepts a Spanish postal code and answers for the warehouse that delivers there.

All 14 endpoints are GET requests that return JSON. Names and categories can be returned in Spanish, English or Catalan.

Authentication

All requests require a valid RapidAPI key. Include the following headers with every request:

You can obtain an API key by subscribing to the Mercadona API on RapidAPI .

Base URL

1

https://mercadona-api.p.rapidapi.com

Endpoints

Products

Catalog

Discovery

Warehouses

Warehouses and Postal Codes

Mercadona’s prices and range depend on the warehouse that serves each address. On every warehouse-scoped endpoint you can pass either:

Every response tells you which warehouse answered in data.resolved_filters.warehouse, with the input you sent, the resolved code and its source (postal_code, param or default).

Hubs

The other 267 warehouses are physical stores with 4-digit numeric codes (e.g. 4701). Store codes are served live, so popularity_score is null on their rows and brand, ean or category_path may be null. Any warehouse value that is not a hub or a 4-digit code returns HTTP 400.

Response Format

Every successful call returns the same envelope:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "status": true,
  "request_id": "c08dbdb1-1857-be2a-9933-3c76643e",
  "cached_at": null,
  "data": {
    "resolved_filters": {
      "warehouse": { "input": "28001", "resolved": "mad3", "source": "postal_code" }
    },
    "language": "es"
  },
  "request_params": { "q": "leche", "postal_code": "28001" }
}

List endpoints return their rows in data.results[] (/search, /brands, /brand-products) or data.items[] (all the others), with total, page, per_page, total_pages and has_next_page.

Errors

When the thing you asked for doesn’t exist, you get HTTP 200 with status: false and an error code you can act on:

1
2
3
4
5
6
7
8

{
  "status": false,
  "request_id": "51cec14a-674b-1fb6-d6d7-af41ea3b",
  "cached_at": null,
  "error": { "code": "ean_not_found", "message": "No product with EAN 0000000000000 in the catalog; ...", "warehouse": null },
  "data": null,
  "request_params": { "ean": "0000000000000" }
}

Invalid input returns HTTP 400, and error is a plain string:

1

{ "status": false, "request_id": "c52553ca-846a-5c27-e2e4-70de3665", "error": "Invalid parameter 'q': Field required" }

Pagination

List endpoints take page (1-indexed) and per_page (max 20). /search returns at most the 100 best matches for a query, which is Mercadona’s own limit. For complete listings use /category-products or /brand-products .

Languages

Pass language=es (default), en or ca to translate product names and category names. Prices and barcodes don’t change. Searches match product names in the chosen language, so search milk with language=en and llet with language=ca.

Caching

Responses are cached for 10 to 15 minutes depending on the endpoint (product details for up to 1 hour). Pass fresh=true to bypass the cache and fetch live data.

Rate Limits

Rate limits depend on your RapidAPI subscription plan. Check your plan details on the RapidAPI listing for specific limits.