Geração de relatórios

A API Waze Ads Management gera relatórios dos dados de desempenho. Para uma Account, o método generateReport permite o seguinte:

  • Agregar estatísticas de desempenho em um período
  • Classificar e ordenar resultados
  • Especificar as condições de filtro
  • Limitar o número de linhas retornadas

Campos compatíveis

Há uma lista completa de fields no corpo da solicitação. Eles incluem os atributos de recursos, os campos metric e o período que serão adicionados ao relatório.

Exemplo de solicitação

A seguinte consulta recupera o total de impressões para uma Account inteira durante um período de três dias:

curl -X POST https://ads.wazeapis.com/v1/accounts/ACCOUNT_ID:generateReport?key=API_KEY \
  -H 'Authorization: Bearer WAZE_ACCESS_TOKEN' \
  -d '{
    startDate: { year: 2020, month: 1, day: 1 },
    endDate: { year: 2020, month: 1, day: 3 },
    fields: ["date", "metric.impressionCount"]
  }'

A resposta contém três values, um para cada dia.

headers: ['date', 'metric.impressionCount'],
rows: [
  { values: ['2020-01-01', '645'] },
  { values: ['2020-01-02', '921'] },
  { values: ['2020-01-03', '723'] }
]

Estrutura da solicitação

Para fazer uma solicitação generateReport, especifique os seguintes atributos:

  • Um parâmetro de solicitação ACCOUNT_ID.
  • Uma startDate, a primeira data que será incluída no relatório.
  • Uma endDate, a última data que será incluída no relatório.
  • Uma lista de fields que serão incluídos no relatório. Na resposta, as instâncias de Row serão agrupadas por todos os campos, exceto aquelas que começam com o prefixo metric.
  • Uma order opcional para classificar os objetos Row.
  • filters opcionais para incluir apenas objetos Row que atendem a condições específicas no relatório.
  • Um parâmetro de solicitação pageSize opcional que indica quantos objetos retornar em uma única resposta. Para entender como usar a paginação, leia a seção de recursos de lista.

Agregar durante um período

Esta consulta busca o custo total acumulado de uma Account em um mês em unidades de micromoeda. Se a moeda da conta fosse USD, 1 seria representado como 1.000.000.

curl -X POST https://ads.wazeapis.com/v1/accounts/ACCOUNT_ID:generateReport?key=API_KEY \
  -H 'Authorization: Bearer WAZE_ACCESS_TOKEN' \
  -d '{
    startDate: { year: 2020, month: 6, day: 1 },
    endDate: { year: 2020, month: 6, day: 30 },
    fields: ["metric.costMicros"]
  }'

Pedir

Uma order pode classificar os objetos Row da resposta em ordem ASC ou DESC de acordo com o valor de field especificado. Por exemplo, a consulta a seguir recupera a metric.impressionCount de acordo com o location.name quando o número de impressões é maior que 10 no último mês, classificado por metric.impressionCount em ordem decrescente.

curl -X POST https://ads.wazeapis.com/v1/accounts/ACCOUNT_ID:generateReport?key=API_KEY \
  -H 'Authorization: Bearer WAZE_ACCESS_TOKEN' \
  -d '{
    startDate: { year: 2020, month: 6, day: 1 },
    endDate: { year: 2020, month: 6, day: 30 },
    fields: [
      "location.name",
      "metric.impressionCount"
    ],
    filters: {
      field: "metric.impressionCount",
      operator: "GREATER_THAN",
      value: "10"
    },
    order: {
      sort: "DESC",
      field: "metric.impressionCount"
    }
  }'

Especificar as condições de filtro

Um filter define condições para determinar quais objetos Row são retornados na resposta.

Esta consulta usa um filter para excluir objetos Row com métricas de impressão zero:

curl -X POST https://ads.wazeapis.com/v1/accounts/ACCOUNT_ID:generateReport?key=API_KEY \
  -H 'Authorization: Bearer WAZE_ACCESS_TOKEN' \
  -d '{
    startDate: { year: 2020, month: 6, day: 1 },
    endDate: { year: 2020, month: 6, day: 30 },
    fields: [
      "campaign.name",
      "metric.impressionCount"
    ],
    filters: {
      field: "metric.impressionCount",
      operator: "GREATER_THAN",
      value: "0"
    }
  }'

Também é possível especificar diversos valores com o operador IN. O filtro a seguir mantém instâncias de Row em que campaign.name é "accounts/123/campaigns/456" ou "accounts/123/campaigns/457":

filters: {
  field: "campaign.name",
  operator: "IN",
  values: [
    "accounts/123/campaigns/456",
    "accounts/123/campaigns/457"
  ]
}

Processar uma resposta

Uma consulta generateReport retorna uma resposta com estes atributos:

  • headers, que correspondem aos fields na solicitação
  • Uma coleção de instâncias Row, que são valores de cada um dos cabeçalhos de cada agrupamento
  • Um nextPageToken, que solicita o próximo lote de results

Próximas etapas

Saiba como compartilhar o acesso a uma Account do Waze Ads.