MercaEx

Unofficial Elixir client for Mercadona's internal API.

Note: Mercadona does not provide an official public API. This library reverse-engineers the endpoints used by tienda.mercadona.es for educational and personal use. The API may change without notice and break this library at any time.

Installation

Add merca_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:merca_ex, "~> 0.1.0"}
  ]
end

Usage

List Categories

{:ok, categories} = MercaEx.categories()

Enum.each(categories, fn cat ->
  IO.puts("#{cat.id}: #{cat.name}")
  Enum.each(cat.subcategories, fn sub ->
    IO.puts("  #{sub.id}: #{sub.name}")
  end)
end)

Get Products by Category

{:ok, products} = MercaEx.products(113)

Enum.each(products, fn product ->
  IO.puts("#{product.name} - #{product.price}€")
end)

Get Product Details

{:ok, product} = MercaEx.product("12345")

IO.puts("""
Name: #{product.name}
Price: #{product.price}€
EAN: #{product.ean}
Description: #{product.description}
""")

Search Products

{:ok, results} = MercaEx.search("leche")

# With options
{:ok, results} = MercaEx.search("leche", warehouse: "mad1", limit: 10)

Data Types

Category

%MercaEx.Category{
  id: 112,
  name: "Aceite, especias y salsas",
  subcategories: [
    %MercaEx.Category{id: 113, name: "Aceite de oliva", subcategories: []}
  ]
}

Product

%MercaEx.Product{
  id: "12345",
  name: "Aceite de oliva virgen extra",
  price: 5.99,
  reference_price: 5.99,
  reference_format: "1 L",
  ean: "8480000123456",
  photo_url: "https://...",
  description: "Aceite de primera calidad"
}

Configuration

For testing, you can configure a mock HTTP client:

# config/test.exs
config :merca_ex, :http_client, MercaEx.HTTPClientMock

How It Works

This library interacts with two undocumented APIs:

REST API (Categories & Products)

The main Mercadona web store exposes a REST API:

• Base URL: https://tienda.mercadona.es/api
• GET /categories/ - List all categories
• GET /categories/{id}/ - Products in a category
• GET /products/{id}/ - Product details

Search API (Algolia)

Mercadona uses Algolia for product search. The credentials are public (embedded in the web frontend JavaScript) and read-only:

App ID: 7UZJKL1DJ0
API Key: 9d8f2e39e90df472b4f2e559a116fe17 (read-only)
Index: products_prod_{warehouse}_es

Available Warehouses

Prices and product availability vary by warehouse/region:

Note: Not all regions have dedicated warehouse codes. Users in regions like Galicia (A Coruña, Vigo, etc.) should use mad1 as it has the most complete catalog.

Prior Art

This library was inspired by and builds upon the reverse-engineering work of others:

• mercapy - Python client (MIT License)
• mercadona-cli - CLI tool with API documentation
• Mercadona API Gist - Algolia endpoint details

Disclaimer

This is an unofficial library. Mercadona S.A. does not provide a public API.

• This library is not affiliated with, endorsed by, or connected to Mercadona S.A.
• The API endpoints were discovered by inspecting network traffic from tienda.mercadona.es
• The API may change or break at any time without notice
• Use responsibly and respect Mercadona's servers (rate limiting, caching, etc.)
• Intended for personal/educational use

License

MIT License. See LICENSE for details.