Visitas

Descrição de parâmetros

• user_id (Integer): ID do usuário.
• item_id (String): ID do anúncio.
• date_from (Date): Data, em formato ISO, que define o início da consulta. O máximo é 150 dias.
• date_to (Date): Data, em formato ISO, que define o final da consulta. O máximo é 150 dias.
• ending (Date, opcional): Data em formato ISO YYYY-MM-DD que estabelece o tempo de finalização da amostra. Por padrão é a data e hora atuais.
• unit (String): Unidade de consulta. Valores possíveis: day.
• last (Integer, opcional): Denota quantos dias antes a amostra abrangerá.

Campos de resposta

• total_visits (Integer): Total de visitantes de um anúncio.
• visits_detail (Array): Detalhamento dos visitantes por país e site.
• results (Array): Detalhamento dos visitantes por intervalos de tempo. A duração é definida pelo parâmetro unit.

Total de visitas por usuário

Recuperação do total das visitas realizadas por um usuário para cada anúncio, por site e entre faixas de datas.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items_visits?date_from=$DATE_FROM&date_to=$DATE_TO

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1000011398/items_visits?date_from=2021-01-01&date_to=2021-02-01

Resposta:

{
  "user_id": 1000011398,
  "date_from": "2021-01-01T00:00:00Z",
  "date_to": "2021-02-01T00:00:00Z",
  "total_visits": 323690,
  "visits_detail": [
    {
      "company": "mercadolibre",
      "quantity": 323690
    }
  ]
}

Visitas totais por anúncio

Recupere as visitas totais a um anúncio dos últimos dois anos.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/visits/items?ids=$ITEM_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/visits/items?ids=MLB9992242141

Resposta:

{
  "MLB9992242141": 552
}

Visitas por anúncios entre intervalos de datas

Recuperação do total das visitas segundo um conjunto de anúncios ligados em uma faixa de datas, por site.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/visits?ids=$ITEM_ID&date_from=$DATE_FROM&date_to=$DATE_TO

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/visits?ids=MCO473861358&date_from=2021-01-01&date_to=2021-02-01

Resposta:

{
  "item_id": "MCO473861358",
  "date_from": "2021-01-01T00:00:00Z",
  "date_to": "2021-02-01T00:00:00Z",
  "total_visits": 536,
  "visits_detail": [
    {
      "company": "mercadolibre",
      "quantity": 536
    }
  ]
}

Visitantes por data por usuário

Recuperação dos visitantes de cada anúncio de um usuário em uma determinada janela de tempo, por site. Detalhamento das informações por intervalos de tempo.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items_visits/time_window?last=$LAST&unit=$UNIT&ending=$ENDING

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1000011398/items_visits/time_window?last=2&unit=day

Resposta:

{
  "user_id": 1000011398,
  "date_from": "2021-01-08T00:00:00Z",
  "date_to": "2021-01-10T00:00:00Z",
  "total_visits": 2923,
  "last": 2,
  "unit": "day",
  "results": [
    {
      "date": "2021-01-08T00:00:00Z",
      "total": 2205,
      "visits_detail": [
        {
          "company": "mercadolibre",
          "quantity": 2205
        }
      ]
    },
    {
      "date": "2021-01-09T00:00:00Z",
      "total": 718,
      "visits_detail": [
        {
          "company": "mercadolibre",
          "quantity": 718
        }
      ]
    }
  ]
}

Visitantes por data por anúncio

Recuperação dos visitantes de cada anúncio em uma determinada janela de tempo, por site. Detalhamento das informações por intervalos de tempo.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/visits/time_window?last=$LAST&unit=$UNIT&ending=$ENDING

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MCO471870973/visits/time_window?last=2&unit=day&ending=2021-08-06

Resposta:

{
  "item_id": "MCO471870973",
  "date_from": "2021-08-04T00:00:00Z",
  "date_to": "2021-08-06T00:00:00Z",
  "total_visits": 26,
  "last": 2,
  "unit": "day",
  "results": [
    {
      "date": "2021-08-04T00:00:00Z",
      "total": 16,
      "visits_detail": [
        {
          "company": "mercadolibre",
          "quantity": 16
        }
      ]
    },
    {
      "date": "2021-08-05T00:00:00Z",
      "total": 10,
      "visits_detail": [
        {
          "company": "mercadolibre",
          "quantity": 10
        }
      ]
    }
  ]
}

Erros

A tabela a seguir lista os possíveis erros retornados pela API de Visitas:

Status_code	Error code	Mensagem de erro	Descrição
400	bad_request	Invalid Site ID	Quando o anúncio ou usuário não pertence a um site local válido.
400	bad_request	unknown date format	Quando o parâmetro date_from ou date_to está ausente ou tem um formato inválido.
400	bad_request	invalid time window, should be smaller or equal to 150 days	Quando o intervalo de tempo excede o máximo permitido de 150 dias.
400	bad_request	invalid date format for ending date	Quando o parâmetro ending tem um formato de data inválido. Apenas o formato YYYY-MM-DD é aceito.
400	validation_parameters	maximum amount of items to query is 1	Quando se tenta consultar mais de um anúncio por vez no parâmetro ids.
400	bad_request	Invalid item ID format: $ITEM_ID	Quando o ID do anúncio não segue o formato correto (prefixo do site + ID numérico).
403	PA_UNAUTHORIZED_RESULT_FROM_POLICIES	At least one policy returned UNAUTHORIZED	Quando o access token é inválido, expirou ou não tem as permissões necessárias.
404	not_found	Item not found	Quando o ID do anúncio não existe no endpoint time_window.