Category predictor

Categories are a hierarchical set of groups where we list items of a similar nature and call a Category Tree. Before publishing a product, you have to use this category predictor API to predict in which category you should publish products. It helps sellers and developers recognize the category domain and required attributes to be filled, improving the listing quality when uploading a product to Mercado Libre.

Contents

→Get a Category prediction
    ↳Mandatory parameter
    ↳Response fields
→Categories by site
→Categories JSON
→Path from root
→Download categories


Get a Category prediction

Make a GET request with a product title (in english) to predict one article at a time, recognize the category_id and the required attributes to list a product. Keep in mind that the answer will be made up of a list of predictions from the provided title, the first being the one with the highest prediction accuracy.

 

Mandatory parameter

q: the title of the product to be predicted, must be completely in english language.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/domain_discovery/search?q=$Q
Note:
This request has a limit 400 request per minute.

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/domain_discovery/search?q=iphone%2064gb

Response:

[
  {
    domain_id: "CBT-CELLPHONES",
    domain_name: "Cellphones",
    category_id: "CBT1055",
    category_name: "Cell Phones and Smartphones",
    attributes: [
      {
        id: "BRAND",
        name: "Brand",
        value_id: "9344",
        value_name: "Apple"
      },
      {
        id: "LINE",
        name: "Line",
        value_id: "58993",
        value_name: "iPhone"
      },
      {
        id: "MODEL",
        name: "Model",
        value_id: "14608",
        value_name: "iPhone"
      }
  	]
  }
]

Response fields

domain_id: ID of the predicted domain.
domain_name: name of the predicted domain.
category_id: ID of the predicted category.
category_name: name of the predicted category.
attributes: list of attributes for the predicted category.


Categories by site

Important:
As of March 14, 2022, we will update the maximum variations allowed (max_variations_allowed) per category from 500.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/sites/CBT/categories

Response:

[
   {
      "id":"CBT1071",
      "name":"Animals and Pets"
   },
   {
      "id":"CBT1367",
      "name":"Antiques and Collectibles"
   },
   {
      "id":"CBT5726",
      "name":"Appliances"
   },
   {
      "id":"CBT1368",
      "name":"Art, Craft and School Supplies"
   },
   {
      "id":"CBT1384",
      "name":"Babies"
   },
   {
      "id":"CBT1246",
      "name":"Beauty and Personal Care"
   },
   {
      "id":"CBT3025",
      "name":"Books, Magazines and Comics"
   },
   {
      "id":"CBT1039",
      "name":"Cameras and Accessories"
   },
   {
      "id":"CBT1743",
      "name":"Cars, Motorcycles and Others"
   },
   {
      "id":"CBT1051",
      "name":"Cell Phones and Phones"
   },
   {
      "id":"CBT1430",
      "name":"Clothing and Accessories"
   },
   {
      "id":"CBT1648",
      "name":"Computers"
   },
   {
      "id":"CBT1144",
      "name":"Consoles and Video Games"
   },
   {
      "id":"CBT1000",
      "name":"Electronics, Audio and Video"
   },
   {
      "id":"CBT1403",
      "name":"Food and Drinks"
   },
   {
      "id":"CBT1132",
      "name":"Games and Toys"
   },
   {
      "id":"CBT409431",
      "name":"Health and Health Supplies"
   },
   {
      "id":"CBT1574",
      "name":"Home, Furniture and Garden"
   },
   {
      "id":"CBT1499",
      "name":"Industries and Offices"
   },
   {
      "id":"CBT3937",
      "name":"Jewels and Watches"
   },
   {
      "id":"CBT1168",
      "name":"Music, Movies and Series"
   },
   {
      "id":"CBT1182",
      "name":"Musical Instruments"
   },
   {
      "id":"CBT1459",
      "name":"Real Estate"
   },
   {
      "id":"CBT1540",
      "name":"Services"
   },
   {
      "id":"CBT9304",
      "name":"Souvenirs, Favours and Parties"
   },
   {
      "id":"CBT1276",
      "name":"Sports and Fitness"
   },
   {
      "id":"CBT2547",
      "name":"Tickets"
   },
   {
      "id":"CBT407134",
      "name":"Tools and Construction"
   },
   {
      "id":"CBT5725",
      "name":"Vehicle Accessories"
   },
   {
      "id":"CBT1953",
      "name":"Other categories"
   }
]

For a second level categories, or information related to specific categories, you have to use the Categories resource, sending the category Id as a URL parameter. The next example shows the “Beauty and Personal Care" category:

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN'  -X GET https://api.mercadolibre.com/categories/CBT1246

Response:

{
  "id": "CBT1246",
  "name": "Beauty and Personal Care",
  "picture": "http://resources.mlstatic.com/category/images/d1c445e9-f3bb-49e8-8cd3-3cfa81e57cf9.png",
  "permalink": null,
  "total_items_in_this_category": 0,
  "path_from_root": [
    {
      "id": "CBT1246",
      "name": "Beauty and Personal Care"
    }
  ],
  "children_categories": [
    {
      "id": "CBT417575",
      "name": "Beard & Mustache Care",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT417770",
      "name": "Beauty Treatments",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT29884",
      "name": "Foot, Hand & Nail Care",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT455174",
      "name": "Hair & Styling Appliances",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT1263",
      "name": "Hair Care",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT43673",
      "name": "Hair Removal",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT431642",
      "name": "Hair Salon Listings",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT1248",
      "name": "Makeup",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT1275",
      "name": "Other",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT454712",
      "name": "Perfumes & Fragrances",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT393366",
      "name": "Personal Care",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT431646",
      "name": "Pharmacy",
      "total_items_in_this_category": 0
    },
    {
      "id": "CBT1253",
      "name": "Skin Care",
      "total_items_in_this_category": 0
    }
  ],
  "attribute_types": "attributes",
  "settings": {
    "adult_content": false,
    "buying_allowed": true,
    "buying_modes": [
      "auction",
      "buy_it_now"
    ],
    "catalog_domain": "CBT-BEAUTY_AND_PERSONAL_CARE_SUPPLIES",
    "coverage_areas": "not_allowed",
    "currencies": [
      "USD"
    ],
    "fragile": false,
    "immediate_payment": "required",
    "item_conditions": [
      "new"
    ],
    "items_reviews_allowed": false,
    "listing_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 12,
    "max_pictures_per_item_var": 10,
    "max_sub_title_length": 70,
    "max_title_length": 60,
    "max_variations_allowed": 100,
    "maximum_price": null,
    "maximum_price_currency": "USD",
    "minimum_price": 1,
    "minimum_price_currency": "USD",
    "mirror_category": null,
    "mirror_master_category": null,
    "mirror_slave_categories": [
    ],
    "price": "required",
    "reservation_allowed": "not_allowed",
    "restrictions": [
    ],
    "rounded_address": false,
    "seller_contact": "not_allowed",
    "shipping_options": [
      "carrier",
      "custom"
    ],
    "shipping_profile": "optional",
    "show_contact_information": false,
    "simple_shipping": "optional",
    "stock": "required",
    "sub_vertical": "health_beauty",
    "subscribable": false,
    "tags": [
    ],
    "vertical": "consumer_goods",
    "vip_subdomain": "articulo",
    "buyer_protection_programs": null,
    "status": "enabled"
  },
  "channels_settings": [
    {
      "channel": "mp-merchants",
      "settings": {
        "buying_modes": [
          "buy_it_now"
        ],
        "immediate_payment": "required",
        "minimum_price": 1,
        "status": "enabled"
      }
    }
  ],
  "meta_categ_id": null,
  "attributable": false,
  "date_created": "2018-04-25T08:12:56.000Z"
}

As you can see, you get the “path_from_root” and children_categories attributes. Use these attributes to browse through the category tree and find the specific category for your item.


Categories JSON

Make a request to a specific category will allow you to know the information and specific description of it. Below you will find the description of some of these attributes.

Request:

curl -X GET https://api.mercadolibre.com/categories/$CATEGORY_ID

Example:

curl -X GET https://api.mercadolibre.com/categories/CBT11796

Response:

{
   "id":"CBT11796",
   "name":"Footwear",
   "picture":null,
   "permalink":null,
   "total_items_in_this_category":0,
   "path_from_root":[
      {
         "id":"CBT1430",
         "name":"Clothing and Accessories"
      },
      {
         "id":"CBT1455",
         "name":"Baby Clothes & Shoes"
      },
      {
         "id":"CBT11796",
         "name":"Footwear"
      }
   ],
   "children_categories":[

   ],
   "attribute_types":"variations",
   "settings":{
      "adult_content":false,
      "buying_allowed":true,
      "buying_modes":[
         "auction",
         "buy_it_now"
      ],
      "catalog_domain":"CBT-BABIES_FOOTWEAR",
      "coverage_areas":"not_allowed",
      "currencies":[
         "USD"
      ],
      "fragile":false,
      "immediate_payment":"required",
      "item_conditions":[
         "new"
      ],
      "items_reviews_allowed":false,
      "listing_allowed":true,
      "max_description_length":50000,
      "max_pictures_per_item":12,
      "max_pictures_per_item_var":10,
      "max_sub_title_length":70,
      "max_title_length":60,
      "maximum_price":null,
      "minimum_price":1,
      "mirror_category":null,
      "mirror_master_category":null,
      "mirror_slave_categories":[

      ],
      "price":"required",
      "reservation_allowed":"not_allowed",
      "restrictions":[

      ],
      "rounded_address":false,
      "seller_contact":"not_allowed",
      "shipping_modes":[
         "custom",
         "not_specified"
      ],
      "shipping_options":[
         "custom",
         "carrier"
      ],
      "shipping_profile":"optional",
      "show_contact_information":false,
      "simple_shipping":"optional",
      "stock":"required",
      "sub_vertical":"clothes",
      "subscribable":false,
      "tags":[

      ],
      "vertical":"apparel",
      "vip_subdomain":"articulo",
      "buyer_protection_programs":null,
      "status":"enabled"
   },
   "meta_categ_id":null,
   "attributable":false,
   "date_created":"2019-09-10T14:12:56.000Z"
}


Path from root

When you are in a category you can know the path from root to the category selected. Take a look how Mercado Libre uses this path to show the item’s category:
image-category (1)


Download categories

Finally and in case of not being able to use the Category Predictor, you can download the category tree.