Categorias e Atributos

As categorias são conjuntos hierárquicos nos quais agrupamos os produtos de natureza similar. As categorias ajudam os usuários a buscar facilmente o produto desejado e cada site (Brasil, Argentina, México, etc.) tem seu próprio conjunto de categorias. Como ajuda, recomendamos que use o preditor de categorias que permite identificar a melhor categoria conforme o título do seu produto. Caso contrário, para fazer a publicação de um veículo, você deverá utilizar o recurso /categories e escolher em qual publicar. Atributos representam características do item, por exemplo, Marca e Modelo, obrigatórios para publicar. Lembre-se que os atributos mudam dependendo da categoria.


Conteúdos

→Categorias →Preditor de categorias →Atributos específicos das categorias →Atributos obrigatórios →Valores mais utilizados (top values) →Dump de categorias →Busca por categoria →Valores padrão →Limit →Offset →Definição de uma faixa de resultados


Categorias

O recurso /sites pode oferecer a estrutura de categorias de um país em particular, nesse caso, do Brasil.

Chamada:
curl -X GET https://api.mercadolibre.com/sites/MLB/categories
Resposta:
[
  {
    "id": "MLB5672",
    "name": "Acessórios para Veículos"
  },
  {
    "id": "MLB271599",
    "name": "Agro"
  },
  {
    "id": "MLB1403",
    "name": "Alimentos e Bebidas"
  },
  {
    "id": "MLB1071",
    "name": "Animais"
  },
  {
    "id": "MLB1367",
    "name": "Antiguidades e Coleções"
  },
  {
    "id": "MLB1368",
    "name": "Arte, Papelaria e Armarinho"
  },
  {
    "id": "MLB1384",
    "name": "Bebês"
  },
  {
    "id": "MLB1246",
    "name": "Beleza e Cuidado Pessoal"
  },
  {
    "id": "MLB1132",
    "name": "Brinquedos e Hobbies"
  },
  {
    "id": "MLB1430",
    "name": "Calçados, Roupas e Bolsas"
  },
  {
    "id": "MLB1039",
    "name": "Câmeras e Acessórios"
  },
  {
    "id": "MLB1743",
    "name": "Carros, Motos e Outros"
  },
  {
    "id": "MLB1574",
    "name": "Casa, Móveis e Decoração"
  },
  {
    "id": "MLB1051",
    "name": "Celulares e Telefones"
  },
  {
    "id": "MLB5726",
    "name": "Eletrodomésticos"
  },
  {
    "id": "MLB1000",
    "name": "Eletrônicos, Áudio e Vídeo"
  },
  {
    "id": "MLB1276",
    "name": "Esportes e Fitness"
  },
  {
    "id": "MLB263532",
    "name": "Ferramentas e Construção"
  },
  {
    "id": "MLB12404",
    "name": "Festas e Lembrancinhas"
  },
  {
    "id": "MLB1144",
    "name": "Games"
  },
  {
    "id": "MLB1459",
    "name": "Imóveis"
  },
  {
    "id": "MLB1499",
    "name": "Indústria e Comércio"
  },
  {
    "id": "MLB1648",
    "name": "Informática"
  },
  {
    "id": "MLB218519",
    "name": "Ingressos"
  },
  {
    "id": "MLB1182",
    "name": "Instrumentos Musicais"
  },
  {
    "id": "MLB3937",
    "name": "Joias e Relógios"
  },
  {
    "id": "MLB1196",
    "name": "Livros, Revistas e Comics"
  },
  {
    "id": "MLB1168",
    "name": "Música, Filmes e Seriados"
  },
  {
    "id": "MLB264586",
    "name": "Saúde"
  },
  {
    "id": "MLB1540",
    "name": "Serviços"
  },
  {
    "id": "MLB1953",
    "name": "Mais Categorias"
  }
]

Para categorias do segundo nível, ou informações relacionadas com categorias específicas, você deverá utilizar o recurso /categories e enviar o ID da categoria como parâmetro na URL. Veja o que podemos encontrar na categoria MLB1743 “Carros, Motos e Outros”.


Chamada:

ccurl -X GET https://api.mercadolibre.com/categories/MLB1743

Resposta:

{
    "id": "MLB1743",
    "name": "Carros, Motos e Outros",
    "picture": "http://resources.mlstatic.com/category/images/e1a43666-ad57-4b8b-b405-f9d04dbbd8fc.png",
    "permalink": "https://www.mercadolivre.com.br/veiculos/",
    "total_items_in_this_category": 275080,
    "path_from_root": [
        {
            "id": "MLB1743",
            "name": "Carros, Motos e Outros"
        }
    ],
    "children_categories": [
        {
            "id": "MLB5839",
            "name": "Caminhões",
            "total_items_in_this_category": 15356
        },
        {
            "id": "MLB1745",
            "name": "Carros Antigos",
            "total_items_in_this_category": 10338
        },
        {
            "id": "MLB1744",
            "name": "Carros e Caminhonetes",
            "total_items_in_this_category": 192571
        },
        {
            "id": "MLB10965",
            "name": "Consórcios",
            "total_items_in_this_category": 97
        },
        {
            "id": "MLB7370",
            "name": "Motorhomes",
            "total_items_in_this_category": 475
        },
        {
            "id": "MLB1763",
            "name": "Motos",
            "total_items_in_this_category": 20246
        },
        {
            "id": "MLB1785",
            "name": "Náutica",
            "total_items_in_this_category": 7789
        },
        {
            "id": "MLB47400",
            "name": "Ônibus",
            "total_items_in_this_category": 4905
        },
        {
            "id": "MLB76421",
            "name": "Veículos Pesados",
            "total_items_in_this_category": 2829
        },
        {
            "id": "MLB1907",
            "name": "Outros Veículos",
            "total_items_in_this_category": 20278
        }
    ],
    "attribute_types": "none",
    "settings": {
        "adult_content": false,
        "buying_allowed": false,
        "buying_modes": [
            "classified"
        ],
        "catalog_domain": null,
        "coverage_areas": "not_allowed",
        "currencies": [
            "BRL"
        ],
        "fragile": false,
        "immediate_payment": "optional",
        "item_conditions": [
            "not_specified",
            "used",
            "new"
        ],
        "items_reviews_allowed": false,
        "listing_allowed": false,
        "max_description_length": 50000,
        "max_pictures_per_item": 15,
        "max_pictures_per_item_var": 6,
        "max_sub_title_length": 70,
        "max_title_length": 60,
        "maximum_price": null,
        "minimum_price": null,
        "mirror_category": null,
        "mirror_master_category": null,
        "mirror_slave_categories": [],
        "price": "required",
        "reservation_allowed": "mandatory",
        "restrictions": [],
        "rounded_address": false,
        "seller_contact": "optional",
        "shipping_modes": [
            "not_specified",
            "custom"
        ],
        "shipping_options": [
            "custom"
        ],
        "shipping_profile": "not_allowed",
        "show_contact_information": true,
        "simple_shipping": "not_allowed",
        "stock": "required",
        "sub_vertical": null,
        "subscribable": false,
        "tags": [],
        "vertical": "motors",
        "vip_subdomain": "veiculo",
        "buyer_protection_programs": [
            "delivered",
            "undelivered"
        ],
        "status": "enabled"
    },
    "meta_categ_id": null,
    "attributable": false,
    "date_created": "2018-04-25T08:12:56.000Z"
}

Você obtém os atributos “path_from_root” e "children_categories". Utilize esses atributos para explorar a árvore de categorias e encontrar a categoria específica de seu produto. Como você pode observar, as categorias são baseadas nos tipos de veículos. Essa chamada acima retornou as categorias como caminhões, motos e automóveis. Vamos fazer outra chamada, agora na categoria MLB1744, que é a categoria "Carros e Caminhonetes”.


Chamada:

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

Resposta:

{
    "id": "MLB1744",
    "name": "Carros e Caminhonetes",
    "picture": "http://resources.mlstatic.com/category/images/470e5a62-5d07-432a-8f00-6a67b2ffada8.png",
    "permalink": null,
    "total_items_in_this_category": 192571,
    "path_from_root": [
        {
            "id": "MLB1743",
            "name": "Carros, Motos e Outros"
        },
        {
            "id": "MLB1744",
            "name": "Carros e Caminhonetes"
        }
    ],
    "children_categories": [
        {
            "id": "MLB270644",
            "name": "Agrale",
            "total_items_in_this_category": 23
        },
        {
            "id": "MLB6039",
            "name": "Alfa Romeo",
            "total_items_in_this_category": 55
        },
        {
            "id": "MLB10356",
            "name": "Asia",
            "total_items_in_this_category": 30
        },
        {
            "id": "MLB180276",
            "name": "Aston Martin",
            "total_items_in_this_category": 14
        },
        {
            "id": "MLB5782",
            "name": "Audi",
            "total_items_in_this_category": 2313
        },
        {
            "id": "MLB5783",
            "name": "BMW",
            "total_items_in_this_category": 3150
        },
        { ...
        }
    ],
    "attribute_types": "attributes",
    "settings": {
        "adult_content": false,
        "buying_allowed": false,
        "buying_modes": [
            "classified"
        ],
        "catalog_domain": "MLB-CARS_AND_VANS",
        "coverage_areas": "not_allowed",
        "currencies": [
            "BRL"
        ],
        "fragile": false,
        "immediate_payment": "optional",
        "item_conditions": [
            "not_specified",
            "used",
            "new"
        ],
        "items_reviews_allowed": false,
        "listing_allowed": false,
        "max_description_length": 50000,
        "max_pictures_per_item": 15,
        "max_pictures_per_item_var": 6,
        "max_sub_title_length": 70,
        "max_title_length": 60,
        "maximum_price": null,
        "minimum_price": null,
        "mirror_category": null,
        "mirror_master_category": null,
        "mirror_slave_categories": [],
        "price": "required",
        "reservation_allowed": "mandatory",
        "restrictions": [],
        "rounded_address": false,
        "seller_contact": "optional",
        "shipping_modes": [
            "not_specified",
            "custom"
        ],
        "shipping_options": [
            "custom"
        ],
        "shipping_profile": "not_allowed",
        "show_contact_information": true,
        "simple_shipping": "not_allowed",
        "stock": "required",
        "sub_vertical": "cars",
        "subscribable": false,
        "tags": [],
        "vertical": "motors",
        "vip_subdomain": "carro",
        "buyer_protection_programs": [
            "delivered",
            "undelivered"
        ],
        "status": "enabled"
    },
    "meta_categ_id": null,
    "attributable": true,
    "date_created": "2018-04-25T08:12:56.000Z"
}

Preditor de categorias

Para identificar a melhor categoria para o seu produto, faça uma chamada GET no recurso /domain_discovery com o título da sua publicação. A primeira resposta é a que tem maior probabilidade.


Parâmetros obrigatórios

site_id: é o site onde você publica.

q: é o título do artigo a prever e deve estar completamente no idioma do site.


Parâmetros opcionais

limit: o valor padrão será 4, mas pode chegar a 8, para que você possa definir um limite entre 1 e 8.

target: pode ser constituído por core ou classified, dependendo da vertical em que está sendo publicado.


Chamada:

curl -X GET https://api.mercadolibre.com/sites/$SITE_ID/domain_discovery/search?q=$Q

Exemplo:

curl -X GET https://api.mercadolibre.com/sites/MLB/domain_discovery/search?limit=1&q=fiat%20uno

Resposta

[
    {
        "domain_id": "MLB-CARS_AND_VANS",
        "domain_name": "Carros e caminhonetes",
        "category_id": "MLB24322",
        "category_name": "Uno",
        "attributes": []
    }
]

Campos da resposta

domain_id: ID do domínio previsto para o item.

domain_name: nome do domínio previsto.

category_id: ID da categoria prevista para o item.

category_name: nome da categoria prevista.

attributes: lista de atributos para a categoria prevista.


Atributos específicos das categorias

Para conhecer os atributos específicos e valores possíveis das categorias que você deve encaminhar para publicar um produto, consulte o recurso /attributes.


Chamada:

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

Resposta resumida:

[
    {
        "id": "BRAND",
        "name": "Marca",
        "tags": {
            "catalog_required": true,
            "required": true
        },
        "hierarchy": "PARENT_PK",
        "relevance": 1,
        "value_type": "string",
        "value_max_length": 255,
        "values": [
        ...
           {
                "id": "389168",
                "name": "Chery"
            },
            {
                "id": "58955",
                "name": "Chevrolet"
            },
            {
                "id": "66395",
                "name": "Chrysler"
            },
            {
                "id": "389169",
                "name": "Citroën"
            },
        ...
        ],
        "attribute_group_id": "FIND",
        "attribute_group_name": "Ficha técnica"
    },
    {
        "id": "MODEL",
        "name": "Modelo",
        "tags": {
            "catalog_required": true,
            "required": true
        },
        "hierarchy": "PARENT_PK",
        "relevance": 1,
        "value_type": "string",
        "value_max_length": 255,
        "values": [
        ...
            {
                "id": "389394",
                "name": "Aircross"
            },
            {
                "id": "389395",
                "name": "Airtrek"
            },
            {
                "id": "71720",
                "name": "Albea"
            },
            {
                "id": "60597",
                "name": "Alhambra"
            },
            {
                "id": "64101",
                "name": "Alliance"
            },
        ...
        ],
        "attribute_group_id": "FIND",
        "attribute_group_name": "Ficha técnica"
    },
    {
        "id": "VEHICLE_YEAR",
        "name": "Año",
        "tags": {
            "required": true
        },
        "hierarchy": "PARENT_PK",
        "relevance": 1,
        "value_type": "number",
        "value_max_length": 18,
        "attribute_group_id": "FIND",
        "attribute_group_name": "Ficha técnica"
    },
    {
        "id": "TRIM",
        "name": "Versión",
        "tags": {
            "catalog_required": true,
            "required": true
        },
        "hierarchy": "PARENT_PK",
        "relevance": 1,
        "value_type": "string",
        "value_max_length": 255,
        "attribute_group_id": "FIND",
        "attribute_group_name": "Ficha técnica"
    },
   {
   ...
   }
]
Nota:
Na resposta estão todos os atributos referentes à categoria. Como o resultado é muito longo, o exemplo está resumido.

Atributos obrigatórios

Os atributos obrigatórios são configurados como “required” nos detalhes da categoria. No exemplo anterior, você pode observar que marca e modelo são obrigatórios; não são autorizadas áreas de cobertura e o seller_contact é opcional.


Valores mais utilizados (top values)

Importante:
Este recurso está disponível apenas para Argentina, Brasil, México e Uruguai para o domínio CARS_AND_VANS.

Com este recurso, você poderá saber quais são os valores mais utilizados para um atributo específico de um domínio. Também é possível pesquisar mais, indicando outros valores de atributo, para que apenas os valores que se apliquem a eles sejam listados.


Os vendedores poderão usar os valores obtidos para escolher o correto entre eles e melhorar a qualidade das publicações.


Parâmetros obrigatórios

omain_id: ID do domínio ao qual queremos nos referir.

attribute_id: ID do atributo do qual precisamos conhecer os valores mais usados.


Parâmetros opcionais

limit: o limite de resultados solicitados têm no máximo 1000.

metric_type: métrica pela qual os resultados serão ordenados, a princípio, apenas NOLs (novas publicações nos últimos 90 dias) são suportadas. O único parâmetro no momento é NOL_90. Novos critérios serão adicionados no futuro. Exemplo: metric_type = NOL_90.


Para identificar os atributos recomendados e conhecidos, deve executar um POST.


Chamada simples com um único atributo:

curl -X POST https://api.mercadolibre.com/catalog_domains/$DOMAIN_ID/attributes/$ATTRIBUTE_ID/top_values

Exemplo:

curl -X POST https://api.mercadolibre.com/catalog_domains/MLB-CARS_AND_VANS/attributes/BRAND/top_values

Resposta:

[

    {

        "id": "60249",

        "name": "Volkswagen",

        "metric": 7987

    },

    {
 "id": "66432",

        "name": "Ford",

        "metric": 5619

    },

    {

        "id": "9909",

        "name": "Renault",

        "metric": 4659

    },

    {

        "id": "58955",

        "name": "Chevrolet",

        "metric": 4319

    },

    {

        "id": "60279",

        "name": "Peugeot",

        "metric": 4285

    },

    {

        "id": "67781",

        "name": "Fiat",

        "metric": 4172

    },

...

]

Exemplo com mais de um atributo


Chamada

curl -X POST https://api.mercadolibre.com/catalog_domains/$DOMAIN_ID/attributes/$ATTRIBUTE_ID/top_values

{

    "known_attributes": [

        {

            "id": "attributes.id",

            "value_id": "attributes.value_id"

        }

    ]

}

Exemplo

{

    "known_attributes": [

        {

            "id": "BRAND",

            "value_id": "60249"

        }

    ]

}

Nesse caso, o conteúdo da resposta será os modelos mais usados da marca Volkswagen 6249.

Nota:
A listagem em known_attributes representa o conjunto de atributos que serão considerados para o cálculo de top values.

Dump de categorias

Lembre-se de que recomendamos o uso do preditor de categorias na sua aplicação. Mas se você preferir, pode solicitar o dump de toda a árvore de categorias para o site de um determinado país para processamento offline. A API retorna a árvore de categorias no formato JSON em uma resposta codificada em gzip. Para obter as categorias do Brasil, utilize a URL abaixo:

curl -X GET https://api.mercadolibre.com/sites/MLB/categories/all

Essa URL contém dois cabeçalhos que podem ser utilizados para verificar quando foi gerado o último dump.


X-Content-Created: contém a data da última geração.

X-Content-MD5: contém a soma de verificação MD5 da última geração.


Chamada:

curl -X GET https://api.mercadolibre.com/sites/MLB/categories/all

Resposta

HTTP/2 200 

content-type: application/json

content-length: 0

date: Wed, 29 Apr 2020 20:40:14 GMT

x-amz-id-2: VTcFVSUdn06VM4dbsuP5vZyHQ5fycw3kHjUgzRxEzSJxSJfEuYpr9DlHZ6ab+2DPvJ/SD97R7OQ=

x-amz-replication-status: COMPLETED

x-amz-request-id: 8BA998DE0241013D

x-amz-version-id: nhcoZXYi83Rh5CjxRYMmFLRIPO_cz7yl

x-content-type-options: nosniff

x-request-id: 071f0a43-1b95-4b04-accd-77646bd6dc3e

x-frame-options: DENY

x-xss-protection: 1; mode=block

access-control-allow-origin: *

access-control-allow-headers: Content-Type

access-control-allow-methods: PUT, GET, POST, DELETE, OPTIONS

access-control-max-age: 86400

accept-ranges: bytes

last-modified: Wed, 29 Apr 2020 20:01:12 GMT

cache-control: max-age=300

content-encoding: gzip

x-content-created: 2020-04-29T20:01:12.000Z

x-content-md5: 7526ed93467ec227359522beac126d82

x-cache: Miss from cloudfront

via: 1.1 b7b2667a8f791fb60d70bb1835ef9b2b.cloudfront.net (CloudFront)

x-amz-cf-pop: GRU1-C1

x-amz-cf-id: bvgXHVEFMS1BSLQCqEJxXmUL6zMRQQnCHBCCJMg78WUfPLVYGubO8Q==

Busca por categorias

Na operação de busca aparecem produtos pertencentes a uma categoria de produto do Mercado Livre. Apesar de existirem toneladas de produtos em algumas categorias, não se preocupe: você poderá paginar os resultados. Leia sobre paginação dos resultados de busca. Para obter todos os produtos de uma determinada categoria, você precisa fazer o seguinte:

curl -X GET https://api.mercadolibre.com/MLB/search?category=MLB5726

A resposta da busca tem uma enorme quantidade de parâmetros. Utilize o método http OPÇÕES para obter uma resposta codificada em JSON que descreverá a API com todos os métodos e conexões permitidos entre ele e a outra parte da API.


Paginação e dimensionamento dos resultados

Daqui em diante, este tutorial será útil para trabalhar com conjuntos específicos de resultados toda vez que você fizer uma chamada à API. A maior parte dos recursos apresentam parâmetros URL normais para paginar e dimensionar resultados: limit e offset.


Valores padrão

Os valores padrões são: offset=0 e limit=50.

curl -X GET https://api.mercadolibre.com/sites/MLB/search?q=fiatuno

Na seção de paginação da resposta JSON, você pode visualizar a quantidade total de produtos que correspondem à busca e o valor de offset com o limit padrão aplicado.

.....

  "paging": {

  "total": 285,

  "offset": 0,

  "limit": 50,

  }

  .....

Limit

Para reduzir o tamanho da página, você pode alterar o parâmetro do limite. Por exemplo, caso esteja interessado em recuperar somente os três primeiros produtos.


Exemplo:

curl -X GET https://api.mercadolibre.com/sites/MLB/search?q=fiatuno&limit=3

Essa ação recupera dados do JSON com um conjunto de três produtos, conforme mostrado a seguir:


Exemplo:

{

  "site_id": "MLB",

  "query": "fiatuno",

  "paging": {

  "total": 284,

  "offset": 0,

  "limit": 3,

  },

  "results": [

  {...},

  {...},

  {...},

  ],

  "sort": {...},

  "available_sorts": [...],

  "filters": [...],

  "available_filters": [...],

}

Offset

Ao usar o atributo offset, você pode mover o limite inferior do bloco de resultados. Por exemplo, se estiver interessado em recuperar os 50 produtos que seguem à resposta padrão.


Exemplo

curl -X GET https://api.mercadolibre.com/sites/MLB/search?q=fiatuno&offset=50

Resposta

{

  "site_id": "MLB",

  "query": "fiatuno",

  "paging": {

  "total": 285,

  "offset": 50,

  "limit": 50,

  },

  "results": [...],

  "sort": {...},

  "available_sorts": [...],

  "filters": [...],

  "available_filters": [...],

}

A resposta acima recupera 50 produtos a partir dos primeiros cinquenta.


Definição de uma faixa de resultados

Ambos parâmetros podem ser combinados. Você pode recuperar produtos do terceiro ao sexto no resultado da busca original:

curl -X GET https://api.mercadolibre.com/sites/MLB/search?q=fiatuno&offset=3&limit=3

Essa ação recupera um dado do JSON com um conjunto de três produtos, conforme mostrado a seguir:

{

  "site_id": "MLB",

  "query": "fiatuno",

  "paging": {

  "total": 285,

  "offset": 3,

  "limit": 3,

  },

  "results": [

  {...},

  {...},

  {...},

  ],
Próxima: Localização de veículos.
ou registre-se para receber as últimas notícias sobre nossa API