API Reporting

Com a API Reporting, um comerciante pode interagir com os dados de performance de forma programática usando a linguagem de consulta do Merchant Center. Isso é semelhante à capacidade de criar relatórios personalizados diretamente no Merchant Center. A API Reporting tem os seguintes benefícios:

• Permite que grandes comerciantes importem dados de performance para as informações de produtos nos sistemas de relatórios internos ou de terceiros.
• Permite que usuários, parceiros terceirizados e agregadores que gerenciam contas do Merchant Center acessem relatórios.

Os usuários da API podem especificar quais dados de performance querem recuperar na resposta da chamada de pesquisa, como:

• Métricas a serem retornadas (por exemplo: "Clicks", "Impressions")
• Dimensões em que segmentar os dados (por exemplo: OfferId, Date)
• Condições que precisam ser atendidas (por exemplo: cliques > 100)

A linguagem de consulta da API Reporting pode consultar a API Content for Shopping para métricas de performance (cliques, impressões), possivelmente segmentadas por várias dimensões (atributos de eventos informados, como programa e data, e atributos de produtos, como marca, categoria etc.), usando o método Search no serviço Reports.

O resultado de uma consulta ao serviço Reports é uma lista de instâncias ReportRow, em que cada ReportRow representa os valores das métricas solicitadas para os segmentos especificados na consulta. Se nenhum segmento for especificado, uma única linha será retornada com as métricas agregadas em todos os segmentos. Caso contrário, se algum segmento for solicitado com métricas, a resposta vai mostrar uma linha para cada tupla de segmento exclusiva. É possível selecionar vários segmentos e métricas em uma única consulta.

Consultar métricas

Você pode consultar as métricas (cliques, impressões, CTR etc.) que quer receber. Adicione um filtro ao período para consultar o serviço Reports. A consulta de exemplo abaixo retorna uma única linha: o valor agregado de cliques na condição adicionada de um período.

SELECT metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-21';

Exemplo de resposta

O exemplo de resposta de código JSON abaixo mostra como esse comerciante teve 4.440 cliques somados em todos os produtos e destinos entre 1º e 21 de dezembro de 2020.

{"results": [
    {
      "metrics": {
        "clicks": "4,440"
      }
    }
]}

Consultar segmentos

Além das métricas, você também pode consultar segmentos, que podem ser um atributo de um produto (offer_id, brand, category etc.) ou de um evento informado (date, program). Um evento informado é uma impressão ou um clique em um produto.

Os segmentos funcionam de maneira semelhante a uma GROUP BY em SQL. Os segmentos dividem as métricas selecionadas, agrupando por cada segmento na cláusula SELECT. A consulta de exemplo abaixo retorna cliques por dia, ordenados por cliques em ordem decrescente na condição adicionada de um período. Somente as linhas em que pelo menos uma métrica solicitada é diferente de zero serão retornadas.

SELECT
  segments.date,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-03'
ORDER BY metrics.clicks DESC;

Exemplo de resposta

O exemplo de resposta de código JSON abaixo mostra como esse comerciante teve 1.546 cliques em todos os produtos e destinos em 1º de dezembro de 2020 e 829 cliques em todos os produtos e destinos em 2 de dezembro de 2020. Nenhum objeto será retornado para 3 de dezembro de 2020 porque o comerciante não teve cliques nesse dia.

{
  "results": [
    {
      "segments": {
        "date": {
          "year": 2020,
          "month": 12,
          "day": 1
        }
      },
      "metrics": {
        "clicks": "1546"
      }
    },
    {
      "segments": {
        "date": {
          "year": 2020,
          "month": 12,
          "day": 2
        }
      },
      "metrics": {
        "clicks": "829"
      }
    }
]}