Category Tree

Returns Mercadona’s category tree. The tree is the same for every warehouse, so this endpoint takes no warehouse or postal_code. With the default depth=2 you get the 26 level-0 categories and their 152 level-1 subcategories. With depth=3 each level-1 category also lists its level-2 groups. Use the ids from this tree as category_id in Category Products , Search , Brands and the discovery endpoints.

HTTP Request

GET /categories

Parameters

Parameter	Type	Required	Default	Description
`depth`	enum	No	`2`	`2`: 26 level-0 categories with their 152 level-1 categories. `3`: also the level-2 groups inside each level-1 category. If level-2 groups are not available yet, the answer comes back at depth 2 and `depth_available` says so
`fresh`	boolean	No	`false`	Bypass the 15-minute cache and fetch fresh data
`language`	enum	No	`es`	`es`, `en` or `ca`. Translates category names

Response

Example for depth=3&language=en (arrays trimmed to 2 items):

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
{
  "status": true,
  "request_id": "9efca449-bdf5-5df7-71bb-50bacace",
  "cached_at": null,
  "data": {
    "items": [
      {
        "category_id": 12,
        "name": "Oils, spices & sauces",
        "order": 7,
        "level": 0,
        "categories": [
          {
            "category_id": 112,
            "name": "Oil, vinegar & salt",
            "order": 7,
            "level": 1,
            "categories": [
              {
                "category_id": 420,
                "name": "Olive oil",
                "order": null,
                "level": 2,
                "categories": []
              },
              {
                "category_id": 421,
                "name": "Others oils",
                "order": null,
                "level": 2,
                "categories": []
              }
            ]
          },
          {
            "category_id": 115,
            "name": "Spices",
            "order": 7,
            "level": 1,
            "categories": [
              {
                "category_id": 425,
                "name": "Herbs",
                "order": null,
                "level": 2,
                "categories": []
              },
              {
                "category_id": 430,
                "name": "Seasoning",
                "order": null,
                "level": 2,
                "categories": []
              }
            ]
          }
        ]
      },
      {
        "category_id": 18,
        "name": "Water & soft drinks",
        "order": 8,
        "level": 0,
        "categories": [
          {
            "category_id": 156,
            "name": "Water",
            "order": 8,
            "level": 1,
            "categories": [
              {
                "category_id": 525,
                "name": "Still water",
                "order": null,
                "level": 2,
                "categories": []
              },
              {
                "category_id": 528,
                "name": "Sparkling water",
                "order": null,
                "level": 2,
                "categories": []
              }
            ]
          },
          {
            "category_id": 163,
            "name": "Isotonic & energy drinks",
            "order": 8,
            "level": 1,
            "categories": [
              {
                "category_id": 540,
                "name": "Energy",
                "order": null,
                "level": 2,
                "categories": []
              },
              {
                "category_id": 548,
                "name": "Isotonic",
                "order": null,
                "level": 2,
                "categories": []
              }
            ]
          }
        ]
      }
    ],
    "total": 26,
    "depth": 3,
    "depth_available": 3,
    "language": "en"
  },
  "request_params": {
    "depth": "3",
    "language": "en"
  }
}

Response Fields

Field	Type	Description
`status`	boolean	`true` when the request succeeded
`request_id`	string	Unique request identifier
`cached_at`	string \| null	ISO timestamp when served from cache, `null` when fetched for this request
`data`	object	Response payload
`data.items[]`	array	Level-0 categories
`data.items[].category_id`	integer	Level-0 category id
`data.items[].name`	string	Category name, translated with `language`
`data.items[].order`	integer	Display order
`data.items[].level`	integer	Always `0` at this level
`data.items[].categories[]`	array	Level-1 categories inside this category
`data.items[].categories[].category_id`	integer	Level-1 category id. Pass it to `/category-products`
`data.items[].categories[].name`	string	Category name
`data.items[].categories[].order`	integer	Display order
`data.items[].categories[].level`	integer	Always `1` at this level
`data.items[].categories[].categories[]`	array	Level-2 groups. Only filled with `depth=3`
`data.items[].categories[].categories[].category_id`	integer	Level-2 group id
`data.items[].categories[].categories[].name`	string	Group name
`data.items[].categories[].categories[].order`	null	Always `null` on level 2
`data.items[].categories[].categories[].level`	integer	Always `2` at this level
`data.items[].categories[].categories[].categories[]`	array	Always empty: level 2 is the deepest level
`data.total`	integer	Number of level-0 categories (26)
`data.depth`	integer	Depth returned
`data.depth_available`	integer	Deepest level currently available: `3` when level-2 groups are loaded, otherwise `2`
`data.language`	string	Language used for names
`request_params`	object	Query parameters you sent, echoed back as strings

Error Responses

Invalid parameter values return HTTP 400. error is a plain string naming the parameter:

1
2
3
4
5
{
  "status": false,
  "request_id": "...",
  "error": "Invalid parameter 'depth': ..."
}

Status Code	Cause	Description
400	Invalid parameter value	`depth` accepts `2` or `3`; `language` accepts `es`, `en` or `ca`

Asking for depth=3 when level-2 groups are not available is not an error. You get HTTP 200 with the depth-2 tree, and data.depth_available is 2.

Code Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import requests

url = "https://mercadona-api.p.rapidapi.com/categories"

params = {
    "depth": 3,
    "language": "en"
}

headers = {
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "mercadona-api.p.rapidapi.com"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()["data"]

print(f"{data['total']} top-level categories (depth available: {data['depth_available']})")
for top in data["items"]:
    for sub in top["categories"]:
        groups = ", ".join(g["name"] for g in sub["categories"])
        print(f"{top['name']} > {sub['name']} ({sub['category_id']}): {groups}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
const url = "https://mercadona-api.p.rapidapi.com/categories";

const params = new URLSearchParams({
  depth: "3",
  language: "en"
});

const response = await fetch(`${url}?${params}`, {
  headers: {
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "mercadona-api.p.rapidapi.com"
  }
});

const { data } = await response.json();
console.log(`${data.total} top-level categories`);
for (const top of data.items) {
  for (const sub of top.categories) {
    console.log(`${top.name} > ${sub.name} (${sub.category_id})`);
  }
}

1
2
3
4
5
curl -G "https://mercadona-api.p.rapidapi.com/categories" \
  --data-urlencode "depth=3" \
  --data-urlencode "language=en" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "X-RapidAPI-Host: mercadona-api.p.rapidapi.com"

Category Products : list every product in a level-1 category or level-2 group from this tree
Product Search : narrow a keyword search with category_id
Brands : list the brands that have products in a category
Product Details : full product sheet for any product you find while walking the tree