Choose operation and property type

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.

Contents:

Categories by Site

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

https://api.mercadolibre.com/sites/MLA/categories
{
    "id": "MLA5725",
    "name": "Accesorios para Vehículos"
  },
  {
    "id": "MLA1071",
    "name": "Animales y Mascotas"
  },
  {
    "id": "MLA1367",
    "name": "Antigüedades"
  },
  {
    "id": "MLA1368",
    "name": "Arte y Artesanías"
  },
  {
    "id": "MLA1743",
    "name": "Autos, Motos y Otros"
  },
  {
    "id": "MLA1384",
    "name": "Bebés"
  },
  {
    "id": "MLA1051",
    "name": "Celulares y Teléfonos"
  },
  {
    "id": "MLA1798",
    "name": "Coleccionables y Hobbies"
  },
  {
    "id": "MLA1648",
    "name": "Computación"
  },
  {
    "id": "MLA1144",
    "name": "Consolas y Videojuegos"
  },
  {
    "id": "MLA1039",
    "name": "Cámaras y Accesorios"
  },
  {
    "id": "MLA1403",
    "name": "Delicatessen y Vinos"
  },
  {
    "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": "MLA1574",
    "name": "Hogar, Muebles y Jardín"
  },
  {
    "id": "MLA1499",
    "name": "Industrias y Oficinas"
  },
  {
    "id": "MLA1459",
    "name": "Inmuebles"
  }

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:

https://api.mercadolibre.com/categories/MLA1459
{
  "id": "MLA1459",
  "name": "Inmuebles",
  "picture": "http://resources.mlstatic.com/category/images/cc0eed64-9cfb-4b78-9258-6266475f6427.png",
  "permalink": "http://www.mercadolibre.com.ar/inmuebles/",
  "total_items_in_this_category": 109788,
  "path_from_root": [
    {
      "id": "MLA1459",
      "name": "Inmuebles"
    }
  ],
  "children_categories": [
    {
      "id": "MLA374730",
      "name": "Camas Náuticas",
      "total_items_in_this_category": 56
    },
    {
      "id": "MLA1496",
      "name": "Campos",
      "total_items_in_this_category": 747
    },
    {
      "id": "MLA1466",
      "name": "Casas",
      "total_items_in_this_category": 29579
    },
    {
      "id": "MLA50541",
      "name": "Cocheras",
      "total_items_in_this_category": 1659
    },
    {
      "id": "MLA1472",
      "name": "Departamentos",
      "total_items_in_this_category": 43732
    },
    {
      "id": "MLA1475",
      "name": "Depósitos y Galpones",
      "total_items_in_this_category": 1474
    },
    {
      "id": "MLA50545",
      "name": "Fondo de Comercio",
      "total_items_in_this_category": 1925
    },
    {
      "id": "MLA79242",
      "name": "Locales",
      "total_items_in_this_category": 2533
    },
    {
      "id": "MLA50538",
      "name": "Oficinas y Consultorios",
      "total_items_in_this_category": 2711
    },
    {
      "id": "MLA1892",
      "name": "Otros Inmuebles",
      "total_items_in_this_category": 2236
    },
    {
      "id": "MLA105179",
      "name": "PH",
      "total_items_in_this_category": 3066
    },
    {
      "id": "MLA50544",
      "name": "Parcelas, Nichos y Bóvedas",
      "total_items_in_this_category": 230
    },
    {
      "id": "MLA50547",
      "name": "Quintas",
      "total_items_in_this_category": 1828
    },
    {
      "id": "MLA1493",
      "name": "Terrenos y Lotes",
      "total_items_in_this_category": 17463
    },
    {
      "id": "MLA50536",
      "name": "Tiempo Compartido",
      "total_items_in_this_category": 566
    }
  ],
  "attribute_types": "attributes",
  "settings": {
    "adult_content": false,
    "buying_allowed": false,
    "buying_modes": [
      "classified"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS",
      "USD"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "new",
      "not_specified",
      "used"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 15,
    "max_sub_title_length": 70,
    "max_title_length": 200,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": true,
    "seller_contact": "optional",
    "shipping_modes": [
      "custom",
      "not_specified"
    ],
    "shipping_options": [
    ],
    "shipping_profile": "not_allowed",
    "show_contact_information": true,
    "simple_shipping": "not_allowed",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "inmueble",
    "mirror_category": null,
    "listing_allowed": false,
    "maximum_price": null,
    "minimum_price": null
  },
  "meta_categ_id": null,
  "attributable": true
}

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:

https://api.mercadolibre.com/categories/MLA79242

Response:

{
  "id": "MLA79242",
  "name": "Locales",
  "picture": "http://resources.mlstatic.com/category/images/f1f2bbe1-b5d4-45b1-9b9c-ac142b6bc64f.png",
  "permalink": null,
  "total_items_in_this_category": 2533,
  "path_from_root": [
    {
      "id": "MLA1459",
      "name": "Inmuebles"
    },
    {
      "id": "MLA79242",
      "name": "Locales"
    }
  ],
  "children_categories": [
    {
      "id": "MLA79243",
      "name": "Alquiler",
      "total_items_in_this_category": 1332
    },
    {
      "id": "MLA79244",
      "name": "Venta",
      "total_items_in_this_category": 1197
    }
  ],
  "attribute_types": "attributes",
  "settings": {
    "adult_content": false,
    "buying_allowed": false,
    "buying_modes": [
      "classified"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS",
      "USD"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "not_specified",
      "used",
      "new"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 15,
    "max_sub_title_length": 70,
    "max_title_length": 200,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": true,
    "seller_contact": "optional",
    "shipping_modes": [
      "custom",
      "not_specified"
    ],
    "shipping_options": [
    ],
    "shipping_profile": "not_allowed",
    "show_contact_information": true,
    "simple_shipping": "not_allowed",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "inmueble",
    "mirror_category": null,
    "listing_allowed": false,
    "maximum_price": null,
    "minimum_price": null
  },
  "meta_categ_id": 23362,
  "attributable": false
}

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:

https://api.mercadolibre.com/categories/MLA79243

Response:

{
  "id": "MLA79243",
  "name": "Alquiler",
  "picture": null,
  "permalink": null,
  "total_items_in_this_category": 1332,
  "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"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS",
      "USD"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "new",
      "not_specified",
      "used"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 15,
    "max_sub_title_length": 70,
    "max_title_length": 200,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": true,
    "seller_contact": "optional",
    "shipping_modes": [
      "not_specified",
      "custom"
    ],
    "shipping_options": [
    ],
    "shipping_profile": "not_allowed",
    "show_contact_information": true,
    "simple_shipping": "not_allowed",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "inmueble",
    "mirror_category": null,
    "listing_allowed": true,
    "maximum_price": 250000,
    "minimum_price": 100
  },
  "meta_categ_id": 12620,
  "attributable": false
}

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:

https://api.mercadolibre.com/categories/MLA79243/attributes
{
    "id": "MLA1459-INMUEBLE",
    "name": "Inmueble",
    "value_type": "list",
    "tags": {
      "fixed": true,
      "required": true
    },
    "values": [
      {
        "id": "MLA1459-INMUEBLE-LOCALES",
        "name": "Locales"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA1459-OPERACION",
    "name": "Operación",
    "value_type": "list",
    "tags": {
      "fixed": true,
      "required": true
    },
    "values": [
      {
        "id": "MLA1459-OPERACION-ALQUILER",
        "name": "Alquiler"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-ANTIG",
    "name": "Antigüedad",
    "value_type": "list",
    "tags": {
      "required": true
    },
    "values": [
      {
        "id": "MLA79242-ANTIG-A_ESTRENAR",
        "name": "A estrenar"
      },
      {
        "id": "MLA79242-ANTIG-MAX_5_ANOS",
        "name": "Max 5 años"
      },
      {
        "id": "MLA79242-ANTIG-MAX_10_ANOS",
        "name": "Max 10 años"
      },
      {
        "id": "MLA79242-ANTIG-MAX_20_ANOS",
        "name": "Max 20 años"
      },
      {
        "id": "MLA79242-ANTIG-MAX_30_ANOS",
        "name": "Max 30 años"
      },
      {
        "id": "MLA79242-ANTIG-MAX_40_ANOS",
        "name": "Max 40 años"
      },
      {
        "id": "MLA79242-ANTIG-MAS_DE_40_ANOS",
        "name": "Más de 40 años"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-BATHQTY",
    "name": "Baños",
    "value_type": "list",
    "tags": {
      "required": true
    },
    "values": [
      {
        "id": "MLA79242-BATHQTY-1",
        "name": "1"
      },
      {
        "id": "MLA79242-BATHQTY-2",
        "name": "2"
      },
      {
        "id": "MLA79242-BATHQTY-3",
        "name": "3"
      },
      {
        "id": "MLA79242-BATHQTY-4",
        "name": "4"
      },
      {
        "id": "MLA79242-BATHQTY-MAS_DE_4",
        "name": "Más de 4"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-ESTADO",
    "name": "Estado",
    "value_type": "list",
    "tags": {
      "required": true
    },
    "values": [
      {
        "id": "MLA79242-ESTADO-A_REFACCIONAR",
        "name": "A refaccionar"
      },
      {
        "id": "MLA79242-ESTADO-BUENO",
        "name": "Bueno"
      },
      {
        "id": "MLA79242-ESTADO-EXCELENTE",
        "name": "Excelente"
      },
      {
        "id": "MLA79242-ESTADO-MUY_BUENO",
        "name": "Muy bueno"
      },
      {
        "id": "MLA79242-ESTADO-REGULAR",
        "name": "Regular"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-SUPCONSCL",
    "name": "Superficie construida (m²)",
    "value_type": "number",
    "value_max_length": 60,
    "tags": {
      "required": true
    },
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-SUPTOTMX",
    "name": "Superficie total (m²)",
    "value_type": "number",
    "value_max_length": 60,
    "tags": {
      "required": true
    },
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA1459-HORPREF",
    "name": "Horario de contacto",
    "value_type": "string",
    "value_max_length": 60,
    "tags": {
    },
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-PISOSQTY",
    "name": "Plantas",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-PISOSQTY-1",
        "name": "1"
      },
      {
        "id": "MLA79242-PISOSQTY-2",
        "name": "2"
      },
      {
        "id": "MLA79242-PISOSQTY-3",
        "name": "3"
      },
      {
        "id": "MLA79242-PISOSQTY-MAS_DE_3",
        "name": "Más de 3"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-LOCALI",
    "name": "Localización",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-LOCALI-A_LA_CALLE",
        "name": "A la calle"
      },
      {
        "id": "MLA79242-LOCALI-CENTRO_COMERCIAL",
        "name": "Centro comercial"
      },
      {
        "id": "MLA79242-LOCALI-GALERIA",
        "name": "Galería"
      },
      {
        "id": "MLA79242-LOCALI-SHOPPING",
        "name": "Shopping"
      },
      {
        "id": "MLA79242-LOCALI-OTRO_LUGAR",
        "name": "Otro lugar"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-AGUACORR",
    "name": "Agua Corriente",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-AGUACORR-N",
        "name": "No"
      },
      {
        "id": "MLA79242-AGUACORR-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-AIRACON",
    "name": "Aire acondicionado",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-AIRACON-N",
        "name": "No"
      },
      {
        "id": "MLA79242-AIRACON-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-ALARSEG",
    "name": "Alarma de seguridad",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-ALARSEG-N",
        "name": "No"
      },
      {
        "id": "MLA79242-ALARSEG-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-ELEVATOR",
    "name": "Ascensor",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-ELEVATOR-SI",
        "name": "Sí"
      },
      {
        "id": "MLA79242-ELEVATOR-NO",
        "name": "No"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-CALEF",
    "name": "Calefacción",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-CALEF-N",
        "name": "No"
      },
      {
        "id": "MLA79242-CALEF-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "GARAGE",
    "name": "Cocheras",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "GARAGE-6a020b",
        "name": "No tiene"
      },
      {
        "id": "GARAGE-c4ca42",
        "name": "1"
      },
      {
        "id": "GARAGE-c81e72",
        "name": "2"
      },
      {
        "id": "GARAGE-eccbc8",
        "name": "3"
      },
      {
        "id": "GARAGE-a87ff6",
        "name": "4"
      },
      {
        "id": "GARAGE-caf5ad",
        "name": "Más de 4"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-COCINA",
    "name": "Cocina",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-COCINA-N",
        "name": "No"
      },
      {
        "id": "MLA79242-COCINA-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-INTERNET",
    "name": "Conexión a Internet",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-INTERNET-N",
        "name": "No"
      },
      {
        "id": "MLA79242-INTERNET-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-DEPOSITO",
    "name": "Depósito",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-DEPOSITO-N",
        "name": "No"
      },
      {
        "id": "MLA79242-DEPOSITO-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-ENTREPISO",
    "name": "Entrepiso",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-ENTREPISO-N",
        "name": "No"
      },
      {
        "id": "MLA79242-ENTREPISO-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-EXPENCEM",
    "name": "Expensas ($)",
    "value_type": "string",
    "value_max_length": 60,
    "tags": {
    },
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-GRUPOELEC",
    "name": "Grupo eletrógeno",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-GRUPOELEC-N",
        "name": "No"
      },
      {
        "id": "MLA79242-GRUPOELEC-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-LUMINOS",
    "name": "Luminosidad",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-LUMINOS-BUENA",
        "name": "Buena"
      },
      {
        "id": "MLA79242-LUMINOS-MUY_BUENA",
        "name": "Muy buena"
      },
      {
        "id": "MLA79242-LUMINOS-REGULAR",
        "name": "Regular"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-LINTELEF",
    "name": "Línea telefónica",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-LINTELEF-N",
        "name": "No"
      },
      {
        "id": "MLA79242-LINTELEF-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-SISTINCEN",
    "name": "Sistema contra incendio",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-SISTINCEN-N",
        "name": "No"
      },
      {
        "id": "MLA79242-SISTINCEN-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-TVCABLE",
    "name": "TV por cable",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-TVCABLE-N",
        "name": "No"
      },
      {
        "id": "MLA79242-TVCABLE-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-VESTU",
    "name": "Vestuario",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-VESTU-N",
        "name": "No"
      },
      {
        "id": "MLA79242-VESTU-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  }

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	https://api.mercadolibre.com/sites/MLB/categories/all

To get the categories for Argentina, use this URL:

~$ curl	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.
c~$ curl -I  https://api.mercadolibre.com/sites/MLB/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 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.
3

Default values

Default values are offset=0 and limit=50.

curl 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 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:
Response:

curl https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&offset=50
{
  "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 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": [...],
}



Next topic:
Locate your properties.

Please rate this