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 tipo de produto desejado e cada site (Brasil, Argentina, México, etc.) tem seu próprio conjunto de categorias. Como ajuda, recomendamos utilize o novo preditor de categorias que permite identificar a melhor categoria de acordo com 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 y Modelo, que agora são atributos obrigatórios para publicar. Lembre-se que os atributos mudam dependendo da categoria.

Veja nosso webinar sobre Predictor de categorias:




Conteúdos

→Categorias
→Preditor de categorias
→Valores mais utilizados (top values)
→Atributos específicos das categorias
→Atributos obrigatórios
→Dump de categorias
→Busca por categoria
→Paginação e dimensionamento dos resultados
→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:

curl -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, que são os tipos de veículos, como caminhões, motos e automóveis. Vamos fazer uma 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 sua postagem, 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 no qual 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 (tops values)

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 à 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

domain_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, em 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 simple 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:

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

{

    "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 levados em consideração para o cálculo de top values.

Dump de categorías

Lembre-se de que recomendamos o uso do preditor de categorías 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 off-line. 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/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/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 categoria

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:

{

  "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 os 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": [

	{...},

	{...},

	{...},

  ],