Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 15/03/2023

Categories and Attributes


Categories are a hierarchical set of groups in which items of a similar nature are listed, called “Category Tree”. Categories help users to easily browse the kind of items they want. Each site has its own set of categories, which means that Argentina will have a unique set of categories, different from the ones you’ll find on Brazil, since each country has their own classified market particularities. Before listing an item, you need to go through the category structure and choose the one in which you want to list. To help you make it, you can download the complete category hierarchy with ID and human-friendly names from our API. To list a real estate property, you will have to choose the category_id according to operation and property type.


Categories by Site

The Sites resource can give you the category structure for a particular country, in this case Argentina.

Example:

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

Response:

[
    {
        "id": "MLA5725",
        "name": "Accesorios para Vehículos"
    },
    {
        "id": "MLA1512",
        "name": "Agro"
    },
    {
        "id": "MLA1403",
        "name": "Alimentos y Bebidas"
    },
    {
        "id": "MLA1071",
        "name": "Animales y Mascotas"
    },
    {
        "id": "MLA1367",
        "name": "Antigüedades y Colecciones"
    },
    {
        "id": "MLA1368",
        "name": "Arte, Librería y Mercería"
    },
    {
        "id": "MLA1743",
        "name": "Autos, Motos y Otros"
    },
    {
        "id": "MLA1384",
        "name": "Bebés"
    },
    {
        "id": "MLA1246",
        "name": "Belleza y Cuidado Personal"
    },
    {
        "id": "MLA1039",
        "name": "Cámaras y Accesorios"
    },
    {
        "id": "MLA1051",
        "name": "Celulares y Teléfonos"
    },
    {
        "id": "MLA1648",
        "name": "Computación"
    },
    {
        "id": "MLA1144",
        "name": "Consolas y Videojuegos"
    },
    {
        "id": "MLA1500",
        "name": "Construcción"
    },
    {
        "id": "MLA1276",
        "name": "Deportes y Fitness"
    },
    {
        "id": "MLA5726",
        "name": "Electrodomésticos y Aires Ac."
    },
    {
        "id": "MLA1000",
        "name": "Electrónica, Audio y Video"
    },
    {
        "id": "MLA2547",
        "name": "Entradas para Eventos"
    },
    {
        "id": "MLA407134",
        "name": "Herramientas"
    },
    {
        "id": "MLA1574",
        "name": "Hogar, Muebles y Jardín"
    },
    {
        "id": "MLA1499",
        "name": "Industrias y Oficinas"
    },
    {
        "id": "MLA1459",
        "name": "Inmuebles"
    },
    {
        "id": "MLA1182",
        "name": "Instrumentos Musicales"
    },
    {
        "id": "MLA3937",
        "name": "Joyas y Relojes"
    },
    {
        "id": "MLA1132",
        "name": "Juegos y Juguetes"
    },
    {
        "id": "MLA3025",
        "name": "Libros, Revistas y Comics"
    },
    {
        "id": "MLA1168",
        "name": "Música, Películas y Series"
    },
    {
        "id": "MLA1430",
        "name": "Ropa y Accesorios"
    },
    {
        "id": "MLA409431",
        "name": "Salud y Equipamiento Médico"
    },
    {
        "id": "MLA1540",
        "name": "Servicios"
    },
    {
        "id": "MLA9304",
        "name": "Souvenirs, Cotillón y Fiestas"
    },
    {
        "id": "MLA1953",
        "name": "Otras categorías"
    }
]

For second level categories, or information related to specific categories, you have to use the Categories resource sending the category Id as a URL parameter.


Let’s see what we find under “Inmuebles” category.


Example:

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

Respuesta:

{
    "id": "MLA1459",
    "name": "Inmuebles",
    "picture": "http://resources.mlstatic.com/category/images/cc0eed64-9cfb-4b78-9258-6266475f6427.png",
    "permalink": "https://www.mercadolibre.com.ar/c/inmuebles",
    "total_items_in_this_category": 652169,
    "path_from_root": [
        {
            "id": "MLA1459",
            "name": "Inmuebles"
        }
    ],
    "children_categories": [
        {
            "id": "MLA374730",
            "name": "Camas Náuticas",
            "total_items_in_this_category": 319
        },
        {
            "id": "MLA1496",
            "name": "Campos",
            "total_items_in_this_category": 5789
        },
        {
            "id": "MLA1466",
            "name": "Casas",
            "total_items_in_this_category": 172797
        },
        {
            "id": "MLA50541",
            "name": "Cocheras",
            "total_items_in_this_category": 9817
        },
        {
            "id": "MLA392265",
            "name": "Consultorios",
            "total_items_in_this_category": 506
        },
        {
            "id": "MLA1472",
            "name": "Departamentos",
            "total_items_in_this_category": 279183
        },
        {
            "id": "MLA1475",
            "name": "Depósitos y Galpones",
            "total_items_in_this_category": 11609
        },
        {
            "id": "MLA50545",
            "name": "Fondo de Comercio",
            "total_items_in_this_category": 2984
        },
        {
            "id": "MLA79242",
            "name": "Locales",
            "total_items_in_this_category": 23445
        },
        {
            "id": "MLA50538",
            "name": "Oficinas",
            "total_items_in_this_category": 16826
        },
        {
            "id": "MLA50544",
            "name": "Parcelas, Nichos y Bóvedas",
            "total_items_in_this_category": 406
        },
        {
            "id": "MLA105179",
            "name": "PH",
            "total_items_in_this_category": 28017
        },
        {
            "id": "MLA50547",
            "name": "Quintas",
            "total_items_in_this_category": 4927
        },
        {
            "id": "MLA1493",
            "name": "Terrenos y Lotes",
            "total_items_in_this_category": 88830
        },
        {
            "id": "MLA50536",
            "name": "Tiempo Compartido",
            "total_items_in_this_category": 299
        },
        {
            "id": "MLA1892",
            "name": "Otros Inmuebles",
            "total_items_in_this_category": 6401
        }
    ],
    "attribute_types": "none",
    "settings": {
        "adult_content": false,
        "buying_allowed": false,
        "buying_modes": [
            "classified"
        ],
        "catalog_domain": null,
        "coverage_areas": "not_allowed",
        "currencies": [
            "USD",
            "ARS"
        ],
        "fragile": false,
        "immediate_payment": "optional",
        "item_conditions": [
            "not_specified",
            "new",
            "used"
        ],
        "items_reviews_allowed": false,
        "listing_allowed": false,
        "max_description_length": 50000,
        "max_pictures_per_item": 30,
        "max_pictures_per_item_var": 6,
        "max_sub_title_length": 70,
        "max_title_length": 200,
        "maximum_price": null,
        "maximum_price_currency": "ARS",
        "minimum_price": 33,
        "minimum_price_currency": "ARS",
        "mirror_category": null,
        "mirror_master_category": null,
        "mirror_slave_categories": [],
        "price": "required",
        "reservation_allowed": "not_allowed",
        "restrictions": [],
        "rounded_address": false,
        "seller_contact": "optional",
        "shipping_modes": [
            "custom",
            "not_specified"
        ],
        "shipping_options": [],
        "shipping_profile": "not_allowed",
        "show_contact_information": true,
        "simple_shipping": "not_allowed",
        "stock": "required",
        "sub_vertical": "null",
        "subscribable": false,
        "tags": [],
        "vertical": "real_estate",
        "vip_subdomain": "inmueble",
        "buyer_protection_programs": [
            "delivered",
            "undelivered"
        ],
        "status": "enabled"
    },
    "channels_settings": [],
    "meta_categ_id": null,
    "attributable": false,
    "date_created": "2018-04-25T08:12:56.000Z"
}

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. As you can see, categories are based on property types first followed by operation type. You need to choose the children category.

Example:

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

Response:

{
    "id": "MLA1459",
    "name": "Inmuebles",
    "picture": "http://resources.mlstatic.com/category/images/cc0eed64-9cfb-4b78-9258-6266475f6427.png",
    "permalink": "https://www.mercadolibre.com.ar/c/inmuebles",
    "total_items_in_this_category": 652169,
    "path_from_root": [
        {
            "id": "MLA1459",
            "name": "Inmuebles"
        }
    ],
    "children_categories": [
        {
            "id": "MLA374730",
            "name": "Camas Náuticas",
            "total_items_in_this_category": 319
        },
        {
            "id": "MLA1496",
            "name": "Campos",
            "total_items_in_this_category": 5789
        },
        {
            "id": "MLA1466",
            "name": "Casas",
            "total_items_in_this_category": 172797
        },
        {
            "id": "MLA50541",
            "name": "Cocheras",
            "total_items_in_this_category": 9817
        },
        {
            "id": "MLA392265",
            "name": "Consultorios",
            "total_items_in_this_category": 506
        },
        {
            "id": "MLA1472",
            "name": "Departamentos",
            "total_items_in_this_category": 279183
        },
        {
            "id": "MLA1475",
            "name": "Depósitos y Galpones",
            "total_items_in_this_category": 11609
        },
        {
            "id": "MLA50545",
            "name": "Fondo de Comercio",
            "total_items_in_this_category": 2984
        },
        {
            "id": "MLA79242",
            "name": "Locales",
            "total_items_in_this_category": 23445
        },
        {
            "id": "MLA50538",
            "name": "Oficinas",
            "total_items_in_this_category": 16826
        },
        {
            "id": "MLA50544",
            "name": "Parcelas, Nichos y Bóvedas",
            "total_items_in_this_category": 406
        },
        {
            "id": "MLA105179",
            "name": "PH",
            "total_items_in_this_category": 28017
        },
        {
            "id": "MLA50547",
            "name": "Quintas",
            "total_items_in_this_category": 4927
        },
        {
            "id": "MLA1493",
            "name": "Terrenos y Lotes",
            "total_items_in_this_category": 88830
        },
        {
            "id": "MLA50536",
            "name": "Tiempo Compartido",
            "total_items_in_this_category": 299
        },
        {
            "id": "MLA1892",
            "name": "Otros Inmuebles",
            "total_items_in_this_category": 6401
        }
    ],
    "attribute_types": "none",
    "settings": {
        "adult_content": false,
        "buying_allowed": false,
        "buying_modes": [
            "classified"
        ],
        "catalog_domain": null,
        "coverage_areas": "not_allowed",
        "currencies": [
            "USD",
            "ARS"
        ],
        "fragile": false,
        "immediate_payment": "optional",
        "item_conditions": [
            "not_specified",
            "new",
            "used"
        ],
        "items_reviews_allowed": false,
        "listing_allowed": false,
        "max_description_length": 50000,
        "max_pictures_per_item": 30,
        "max_pictures_per_item_var": 6,
        "max_sub_title_length": 70,
        "max_title_length": 200,
        "maximum_price": null,
        "maximum_price_currency": "ARS",
        "minimum_price": 33,
        "minimum_price_currency": "ARS",
        "mirror_category": null,
        "mirror_master_category": null,
        "mirror_slave_categories": [],
        "price": "required",
        "reservation_allowed": "not_allowed",
        "restrictions": [],
        "rounded_address": false,
        "seller_contact": "optional",
        "shipping_modes": [
            "custom",
            "not_specified"
        ],
        "shipping_options": [],
        "shipping_profile": "not_allowed",
        "show_contact_information": true,
        "simple_shipping": "not_allowed",
        "stock": "required",
        "sub_vertical": "null",
        "subscribable": false,
        "tags": [],
        "vertical": "real_estate",
        "vip_subdomain": "inmueble",
        "buyer_protection_programs": [
            "delivered",
            "undelivered"
        ],
        "status": "enabled"
    },
    "channels_settings": [],
    "meta_categ_id": null,
    "attributable": false,
    "date_created": "2018-04-25T08:12:56.000Z"
}

On this case the children_categories are “Venta” and “Alquiler”. You can list your real estate property under the one that suits you better.


Categories JSON

Making a call to a particular category will let you know the attributes that belong to it. Following you’ll find a description of some of these attributes. When you make a GET to the category_id, you’ll find all available attributes and you can know if they’re required to list under the category or if they’re optional.

Example:

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

Response:

{
    "id": "MLA79243",
    "name": "Alquiler",
    "picture": null,
    "permalink": null,
    "total_items_in_this_category": 8964,
    "path_from_root": [
        {
            "id": "MLA1459",
            "name": "Inmuebles"
        },
        {
            "id": "MLA79242",
            "name": "Locales"
        },
        {
            "id": "MLA79243",
            "name": "Alquiler"
        }
    ],
    "children_categories": [],
    "attribute_types": "attributes",
    "settings": {
        "adult_content": false,
        "buying_allowed": false,
        "buying_modes": [
            "classified"
        ],
        "catalog_domain": "MLA-RETAIL_SPACE_FOR_RENT",
        "coverage_areas": "not_allowed",
        "currencies": [
            "USD",
            "ARS"
        ],
        "fragile": false,
        "immediate_payment": "optional",
        "item_conditions": [
            "not_specified",
            "new",
            "used"
        ],
        "items_reviews_allowed": false,
        "listing_allowed": true,
        "max_description_length": 50000,
        "max_pictures_per_item": 30,
        "max_pictures_per_item_var": 6,
        "max_sub_title_length": 70,
        "max_title_length": 200,
        "maximum_price": 8000000,
        "maximum_price_currency": "ARS",
        "minimum_price": 33,
        "minimum_price_currency": "ARS",
        "mirror_category": null,
        "mirror_master_category": null,
        "mirror_slave_categories": [],
        "price": "required",
        "reservation_allowed": "not_allowed",
        "restrictions": [],
        "rounded_address": false,
        "seller_contact": "optional",
        "shipping_modes": [
            "custom",
            "not_specified"
        ],
        "shipping_options": [],
        "shipping_profile": "not_allowed",
        "show_contact_information": true,
        "simple_shipping": "not_allowed",
        "stock": "required",
        "sub_vertical": "properties",
        "subscribable": false,
        "tags": [],
        "vertical": "real_estate",
        "vip_subdomain": "inmueble",
        "buyer_protection_programs": [
            "delivered",
            "undelivered"
        ],
        "status": "enabled"
    },
    "channels_settings": [],
    "meta_categ_id": null,
    "attributable": false,
    "date_created": "2018-04-25T08:12:56.000Z"
}

Specific category attributes

To know the specific category attributes and possible values you need to send to list an item check the /attributes resource.

Example:

[
  {
    "id": "CONTACT_SCHEDULE",
    "name": "Horario de contacto",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "string",
    "value_max_length": 255,
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "PROPERTY_TYPE",
    "name": "Inmueble",
    "tags": {
      "fixed": true,
      "product_pk": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "list",
    "values": [
      {
        "id": "242065",
        "name": "Local"
      }
    ],
    "attribute_group_id": "MAIN",
    "attribute_group_name": "Principales"
  },
  {
    "id": "OPERATION",
    "name": "Operación",
    "tags": {
      "fixed": true,
      "product_pk": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "list",
    "values": [
      {
        "id": "242073",
        "name": "Alquiler"
      }
    ],
    "attribute_group_id": "MAIN",
    "attribute_group_name": "Principales"
  },
  {
    "id": "TOTAL_AREA",
    "name": "Superficie total",
    "tags": {
      "catalog_required": true,
      "required": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "m²",
        "name": "m²"
      }
    ],
    "default_unit": "m²",
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "COVERED_AREA",
    "name": "Superficie cubierta",
    "tags": {
      "catalog_required": true,
      "required": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "m²",
        "name": "m²"
      }
    ],
    "default_unit": "m²",
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "FULL_BATHROOMS",
    "name": "Baños",
    "tags": {
      "catalog_required": true,
      "required": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number",
    "value_max_length": 255,
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "PARKING_LOTS",
    "name": "Cocheras",
    "tags": {
      "catalog_required": true,
      "required": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number",
    "value_max_length": 255,
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "WAREHOUSES",
    "name": "Bodegas",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number",
    "value_max_length": 255,
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "FLOORS",
    "name": "Pisos",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number",
    "value_max_length": 255,
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "PROPERTY_AGE",
    "name": "Antigüedad",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number_unit",
    "value_max_length": 255,
    "allowed_units": [
      {
        "id": "años",
        "name": "años"
      }
    ],
    "default_unit": "años",
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "IPTU_TAX",
    "name": "Valor del IPTU",
    "tags": {
      "hidden": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number",
    "value_max_length": 255,
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "CONDO_VALUE",
    "name": "Valor del condominio",
    "tags": {
      "hidden": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number",
    "value_max_length": 255,
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "MAINTENANCE_FEE",
    "name": "Expensas",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "number",
    "value_max_length": 255,
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "HAS_INTERNET_ACCESS",
    "name": "Acceso a internet",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "COMOYAMEN",
    "attribute_group_name": "Comodidades y amenities"
  },
  {
    "id": "HAS_TAP_WATER",
    "name": "Agua corriente",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      },
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Características adicionales"
  },
  {
    "id": "HAS_AIR_CONDITIONING",
    "name": "Aire acondicionado",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "COMOYAMEN",
    "attribute_group_name": "Comodidades y amenities"
  },
  {
    "id": "HAS_HEATING",
    "name": "Calefacción",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "COMOYAMEN",
    "attribute_group_name": "Comodidades y amenities"
  },
  {
    "id": "HAS_NATURAL_GAS",
    "name": "Gas natural",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Características adicionales"
  },
  {
    "id": "HAS_ELECTRIC_GENERATOR",
    "name": "Grupo electrógeno",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Características adicionales"
  },
  {
    "id": "HAS_ELECTRIC_LIGHT",
    "name": "Luz eléctrica",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Características adicionales"
  },
  {
    "id": "HAS_FIRE_SYSTEM",
    "name": "Sistema contra incendio",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Características adicionales"
  },
  {
    "id": "HAS_TELEPHONE_LINE",
    "name": "Línea telefónica",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Características adicionales"
  },
  {
    "id": "HAS_SECURITY",
    "name": "Seguridad",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "COMOYAMEN",
    "attribute_group_name": "Comodidades y amenities"
  },
  {
    "id": "HAS_KITCHEN",
    "name": "Cocina",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "AMBIENTES",
    "attribute_group_name": "Ambientes"
  },
  {
    "id": "HAS_FITTING_ROOM",
    "name": "Probador",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Características adicionales"
  },
  {
    "id": "HAS_GUEST_PARKING",
    "name": "Estacionamiento para visitantes",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      },
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      }
    ],
    "attribute_group_id": "COMOYAMEN",
    "attribute_group_name": "Comodidades y amenities"
  },
  {
    "id": "WHEELCHAIR_RAMP",
    "name": "Rampa para silla de ruedas",
    "tags": {
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      },
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Características adicionales"
  },
  {
    "id": "CMG_SITE",
    "name": "Sitio de origen",
    "tags": {
      "hidden": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "string",
    "value_max_length": 255,
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "CANONICAL_URL",
    "name": "Url canónica",
    "tags": {
      "hidden": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "string",
    "value_max_length": 255,
    "attribute_group_id": "DFLT",
    "attribute_group_name": "Otros"
  },
  {
    "id": "HAS_LIFT",
    "name": "Ascensor",
    "tags": {
      "hidden": true
    },
    "hierarchy": "ITEM",
    "relevance": 1,
    "value_type": "boolean",
    "values": [
      {
        "id": "242084",
        "name": "No",
        "metadata": {
          "value": false
        }
      },
      {
        "id": "242085",
        "name": "Sí",
        "metadata": {
          "value": true
        }
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  },
  {
    "id": "ITEM_CONDITION",
    "name": "Condición del ítem",
    "tags": {
      "hidden": true
    },
    "hierarchy": "ITEM",
    "relevance": 2,
    "value_type": "list",
    "values": [
      {
        "id": "2230581",
        "name": "Usado"
      },
      {
        "id": "2230284",
        "name": "Nuevo"
      }
    ],
    "attribute_group_id": "OTHERS",
    "attribute_group_name": "Otros"
  }
]

Name

This attribute shows a human-friendly label. Only by reading the Json above you now that, for example, this is a classified category that doesn’t allow to include shipping options, there are 1332 items listed under it, and you can include the price on ARS or USD.


Mandatory attributes

Mandatory attributes are set as “required” under the category detail. On the example above you can see that price and stock are required, coverage areas are not allowed and seller_contact is optional. Also specific category attributes like attributes like “Antigüedad” and “Estado” that has the tag “required”: true, need to be sent with the possible values detailed on the Json.


Category Dump

The category tree does not change very often. If you prefer, you can request a dump of the whole category tree for a given country site for offline processing. This API returns the category tree in JSON format within a gzip-encoded response.


To get the categories for Brazil, use this URL:

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

To get the categories for Argentina, use this URL:

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

This URL contains 2 headers that can be used to check when the last dump was generated.

  • X-Content-Created: contains the date of the last generation.
  • X-Content-MD5: contains the MD5 checksum of the last generation.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/categories/all

HTTP/1.1 200 OK

  • Server: nginx/1.0.4
  • Date: Tue, 24 Jul 2012 15:14:58 GMT
  • Content-Type: application/json;charset=UTF-8
  • Connection: keep-alive
  • X-MLAPI-Version: 1.9.5
  • Content-Encoding: gzip
  • X-Content-Created: 2012-07-24T14:00:59.716Z
  • X-Content-MD5: 943541196986770119b4af1e66bda2dc

Choose category for your property

Choosing the right category for your real estate property will determine how quickly buyers will find your item and will improve your chances of selling it. For this reason, we highly recommend to use our Category predictor tool before listing an item.


Search by category

The search operation returns items which belong to a MercadoLibre item category, there can be tons of items under certains categories but don’t worry, you can paginate results, read about paging search results. To get every item under a given category, do as it follows:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?category=MLA5726

The search response has a lot of parameters. Use OPTIONS http method to get a JSON encoded response that will describe the API, with all the allowed methods and connections between another part of the API.


Paging & sizing results

This tutorial will come handy for you from now on because it will help you to work with specific set of results each time you make an API call. Most resources have common url parameters to paginate and size results, which are: Limit and Offset.

limit

Default values

Default values are offset=0 and limit=50.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?q=ipod nano

In the paging section of the JSON response, you can see the total number of items that match the search and the offset value with the default limit applied.

  "paging": {
    "total": 285,
    "offset": 0,
    "limit": 50,
  }
 ...

Limit

To reduce the page size you can change the limit parameter. For example, if you are interested in retrieving just the first 3 items:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&limit=3

This action retrieves a JSON data with an array of 3 items as shown:

{
  "site_id": "MLA",
  "query": "ipod nano",
  "paging": {
    "total": 284,
    "offset": 0,
    "limit": 3,
  },
  "results": [
    {...},
    {...},
    {...},
  ],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...],
}

Offset

By using the offset attribute, you can move the lower limit of the result block. For example, if you are interested in retrieving the 50 items that follow the default response.

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&offset=50

Response:

{
  "site_id": "MLA",
  "query": "ipod nano",
  "paging": {
    "total": 285,
    "offset": 50,
    "limit": 50,
  },
  "results": [...],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...],
}

This response retrieves 50 items starting from the first fifty items.


Define a range of results

It is possible to combine both parameters. You can retrieve items from the third to the sixth item in the original search result:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&offset=3&limit=3

This action retrieves a JSON data with an array of 5 items as shown:

{
  "site_id": "MLA",
  "query": "ipod nano",
  "paging": {
    "total": 285,
    "offset": 3,
    "limit": 3,
  },
  "results": [
    {...},
    {...},
    {...},
  ],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...],
}
https://api.mercadolibre.com/sites/MLA/search/

Next topic: Locate your properties.