Search Analytics: query

Requer autorização

Consulte seus dados de tráfego de pesquisa com filtros e parâmetros definidos por você. O método retorna zero ou mais linhas agrupadas pelas chaves de linha (dimensões) que você definir. É preciso definir um período de um ou mais dias.

Quando a data é uma das dimensões, os dias sem dados são omitidos da lista de resultados. Para saber quais dias têm dados, faça uma consulta sem filtros agrupados por data para o período de interesse.

Os resultados são classificados por contagem de cliques em ordem decrescente. Se duas linhas tiverem a mesma contagem de cliques, elas serão classificadas de forma arbitrária.

Consulte o exemplo em Python para chamar esse método.

A API é limitada por restrições internas do Search Console e não garante o retorno de todas as linhas de dados, mas sim das principais.

Confira os limites da quantidade de dados disponíveis.

Exemplo de JSON POST:
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
  "startDate": "2015-04-01",
  "endDate": "2015-05-01",
  "dimensions": ["country","device"]
}
Faça o teste agora.

Solicitação

Solicitação HTTP

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

Parâmetros

Nome do parâmetro Valor Descrição
Parâmetros de caminho
siteUrl string O URL da propriedade, conforme definido no Search Console. Exemplos: http://www.example.com/ (para uma propriedade de prefixo de URL) ou sc-domain:example.com (para uma propriedade do domínio)

Autorização

Esta solicitação requer autorização com pelo menos um dos seguintes escopos (leia mais sobre autenticação e autorização).

Escopo
https://www.googleapis.com/auth/webmasters.readonly
https://www.googleapis.com/auth/webmasters

Corpo da solicitação

No corpo da solicitação, forneça os dados com a seguinte estrutura:

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ],
      "filterLists": [
        {
          "dimension": string,
          "expressions": [
            string
          ]
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
Nome da propriedade Valor Descrição Observações
startDate string [Obrigatório] Data de início do período solicitado, no formato AAAA-MM-DD, no horário do Pacífico (UTC - 7:00/8:00). Precisa ser menor ou igual à data de término. Esse valor está incluído no intervalo.
endDate string [Obrigatório] Data de término do período solicitado, no formato AAAA-MM-DD, no horário do Pacífico (UTC - 7:00/8:00). Precisa ser maior ou igual à data de início. Esse valor está incluído no intervalo.
dimensions[] list [Opcional] Zero ou mais dimensões para agrupar os resultados. Os resultados são agrupados na ordem em que você fornece essas dimensões. Você pode usar qualquer nome de dimensão em dimensionFilterGroups[].filters[].dimension, além de "data" e "hora". Os valores da dimensão de agrupamento são combinados para criar uma chave exclusiva para cada linha de resultado. Se nenhuma dimensão for especificada, todos os valores serão combinados em uma única linha. Não há limite para o número de dimensões que você pode agrupar por, mas não é possível agrupar pela mesma dimensão duas vezes. Exemplo: [country, device]
searchType string Descontinuado. Use type
type string [Opcional] Filtrar resultados para o seguinte tipo:
  • "discover": resultados do Discover
  • "googleNews": resultados de news.google.com e do app Google Notícias para Android e iOS. Não inclui resultados da guia "Notícias" na Pesquisa Google.
  • "news": resultados da pesquisa na guia "Notícias" da Pesquisa Google.
  • "image": resultados da guia "Imagens" na Pesquisa Google.
  • "video": resultados da pesquisa de vídeos
  • "web": [padrão] filtra os resultados para a guia combinada ("Todas") na Pesquisa Google. Não inclui resultados do Discover ou do Google Notícias.
  • "webMultimodal": resultados da pesquisa do Google Lens, do Circule para Pesquisar no Android e de uploads de imagens na Pesquisa Google.
dimensionFilterGroups[] list [Opcional] Zero ou mais grupos de filtros para aplicar aos valores de agrupamento de dimensões. Todos os grupos de filtros precisam corresponder para que uma linha seja retornada na resposta. Em um único grupo de filtros, é possível especificar se todos os filtros precisam corresponder ou se pelo menos um precisa corresponder.
dimensionFilterGroups[].groupType string Se todos os filtros desse grupo precisam retornar verdadeiro ("and") ou se um ou mais precisam retornar verdadeiro (ainda não disponível).

Os valores aceitáveis são:
  • "and": todos os filtros no grupo precisam retornar "true" para que o grupo de filtros seja verdadeiro.
dimensionFilterGroups[].filters[] list [Opcional] Zero ou mais filtros para testar na linha. Cada filtro consiste em um nome de dimensão, um operador e um valor. O tamanho máximo é de 4.096 caracteres. Exemplos:
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string A dimensão a que esse filtro se aplica. É possível filtrar por qualquer dimensão listada aqui, mesmo que você não esteja agrupando por ela.

Os valores aceitáveis são:
  • "country": filtra pelo país especificado, conforme o código de país de três letras (ISO 3166-1 alfa-3).
  • "device": filtra os resultados de acordo com o tipo de dispositivo especificado. Valores compatíveis:
    • COMPUTADOR
    • DISPOSITIVOS MÓVEIS
    • TABLET
  • "page": filtra de acordo com a string de URI especificada.
  • "query": filtra de acordo com a string de consulta especificada.
  • "searchAppearance": filtra um recurso específico de resultado da pesquisa. Para ver uma lista de valores disponíveis, execute uma consulta agrupada por "searchAppearance". A lista completa de valores e descrições também está disponível na documentação de ajuda.
  • "brandedClassification": filtra os resultados de acordo com a classificação de consulta de marca especificada (somente o operador "equals" é aceito). Não é possível combinar a filtragem ou o agrupamento por "brandedClassification" com um filtro "query" na mesma solicitação. Os dados estão disponíveis a partir de 21 de fevereiro de 2026 e apenas para propriedades de nível superior com volume suficiente de consultas e impressões (consulte o comunicado sobre consultas de marca). Valores compatíveis:
    • COM MARCA
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [Opcional] Como o valor especificado precisa corresponder (ou não) ao valor da dimensão da linha.

Os valores aceitáveis são:
  • "contains": o valor da linha precisa conter ou ser igual à sua expressão (não diferencia maiúsculas de minúsculas).
  • "equals": [padrão] sua expressão precisa ser exatamente igual ao valor da linha (diferencia maiúsculas de minúsculas para dimensões de página e consulta).
  • "notContains": o valor da linha não pode conter sua expressão como uma substring ou uma correspondência completa (sem diferenciar maiúsculas de minúsculas).
  • "notEquals": sua expressão não pode ser exatamente igual ao valor da linha (diferencia maiúsculas de minúsculas para as dimensões de página e consulta).
  • "includingRegex": uma expressão regular de sintaxe RE2 que precisa ser correspondida.
  • "excludingRegex": uma expressão regular de sintaxe RE2 que não pode ser correspondida.
dimensionFilterGroups[].filters[].expression string O valor que o filtro deve corresponder ou excluir, dependendo do operador.
dimensionFilterGroups[].filterLists[] list [Opcional] Zero ou mais filtros de dimensão com vários valores para testar na linha. Diferente de filters[], que corresponde a um único valor por entrada, filterLists[] permite a correspondência com vários valores de correspondência exata para uma única dimensão em um filtro. Uma linha corresponde a uma lista de filtros se o valor do dimension especificado for igual a qualquer um dos expressions fornecidos. Uma única solicitação não pode filtrar a mesma dimensão em filters e filterLists ao mesmo tempo.
dimensionFilterGroups[].filterLists[].dimension string [Obrigatório] A dimensão à qual essa lista de filtros se aplica.

Os valores aceitáveis são:
  • "country": filtrar pelos países especificados usando códigos de país de três letras (ISO 3166-1 alfa-3).
  • "device": filtra os tipos de dispositivo especificados (DESKTOP, MOBILE, TABLET).
dimensionFilterGroups[].filterLists[].expressions[] list [Obrigatório] A lista de valores (string) para filtrar.
aggregationType string

[Opcional] Como os dados são agregados. Se agregados por propriedade, todos os dados da mesma propriedade são agregados. Se agregados por página, todos os dados são agregados por URI canônico. Se você filtrar ou agrupar por página, escolha "auto". Caso contrário, é possível agregar por propriedade ou por página, dependendo de como você quer que os dados sejam calculados. Consulte a documentação de ajuda para saber como os dados são calculados de forma diferente por site e por página.

Observação: se você agrupar ou filtrar por página, não será possível agregar por propriedade.

Se você especificar qualquer valor diferente de auto, o tipo de agregação no resultado vai corresponder ao tipo solicitado ou, se você solicitar um tipo inválido, vai receber um erro. A API nunca vai mudar o tipo de agregação se o tipo solicitado for inválido.

Os valores aceitáveis são:
  • "auto": [Padrão] Deixe o serviço decidir o tipo de agregação apropriado.
  • byNewsShowcasePanel": agrega valores por Painel de Destaques do Destaques Jornalísticos. Ele precisa ser usado em combinação com o filtro NEWS_SHOWCASE searchAppearance e type=discover ou type=googleNews. Se você agrupar por página, filtrar por página ou filtrar para outro searchAppearance, não será possível agregar por byNewsShowcasePanel.
  • "byPage": agrega valores por URI.
  • "byProperty": agrega valores por propriedade. Não compatível com type=discover ou type=googleNews
rowLimit integer [Opcional; o intervalo válido é de 1 a 25.000; o padrão é 1.000] O número máximo de linhas a serem retornadas. Para paginar os resultados, use o deslocamento startRow.
startRow integer [Opcional; o padrão é 0] Índice baseado em zero da primeira linha na resposta. Não pode ser um número negativo. Se startRow exceder o número de resultados da consulta, a resposta será bem-sucedida, mas com zero linhas.
dataState string [Opcional] Se "all" (não diferencia maiúsculas de minúsculas), os dados vão incluir dados atualizados. Se "final" (não diferencia maiúsculas de minúsculas) ou se esse parâmetro for omitido, os dados retornados vão incluir apenas dados finalizados. Se "hourly_all" (não diferencia maiúsculas de minúsculas), os dados vão incluir o detalhamento por hora. Isso indica que os dados por hora incluem dados parciais e precisam ser usados ao agrupar pela dimensão HOUR da API.

Resposta

Os resultados são agrupados de acordo com as dimensões especificadas na solicitação. Todos os valores com o mesmo conjunto de valores de dimensão serão agrupados em uma única linha. Por exemplo, se você agrupar pela dimensão de país, todos os resultados de "usa" serão agrupados, todos os resultados de "mdv" serão agrupados e assim por diante. Se você agrupar por país e dispositivo, todos os resultados de "usa, tablet" serão agrupados, todos os resultados de "usa, dispositivo móvel" serão agrupados e assim por diante. Consulte a documentação do relatório de Search Analytics para saber como os cliques, as impressões etc. são calculados e o que eles significam.

Os resultados são classificados por contagem de cliques, em ordem decrescente, a menos que você agrupe por data. Nesse caso, os resultados são classificados por data, em ordem crescente (do mais antigo para o mais recente). Se houver um empate entre duas linhas, a ordem de classificação será arbitrária.

Consulte a propriedade rowLimit na solicitação para saber o número máximo de valores que podem ser retornados.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
Nome da propriedade Valor Descrição Observações
rows[] list Uma lista de linhas agrupadas pelos valores de chave na ordem fornecida na consulta.
rows[].keys[] list Uma lista dos valores de dimensão para essa linha, agrupados de acordo com as dimensões na solicitação, na ordem especificada na solicitação.
rows[].clicks double Contagem de cliques da linha.
rows[].impressions double Contagem de impressões da linha.
rows[].ctr double Taxa de cliques (CTR) da linha. Os valores variam de 0 a 1,0, inclusive.
rows[].position double Posição média nos resultados da pesquisa.
responseAggregationType string Como os resultados foram agregados. Consulte a documentação de ajuda para saber como os dados são calculados de maneira diferente por site e por página.

Os valores aceitáveis são:
  • "auto"
  • "byPage": os resultados foram agregados por página.
  • "byProperty": os resultados foram agregados por propriedade.
metadata object

Um objeto que pode ser retornado com os resultados da consulta, fornecendo contexto sobre o estado dos dados.

Quando você solicita dados recentes (usando all ou hourly_all para dataState), algumas das linhas retornadas podem representar dados incompletos, o que significa que os dados ainda estão sendo coletados e processados. Esse objeto de metadados ajuda a identificar exatamente quando isso começa e termina.

Todas as datas e horários fornecidos neste objeto estão no fuso horário de America/Los_Angeles.

O campo específico retornado nesse objeto depende de como você agrupou os dados na solicitação:

  • first_incomplete_date (string): a primeira data em que os dados ainda estão sendo coletados e processados, apresentada no formato YYYY-MM-DD (formato de data local estendido ISO-8601).

    Esse campo é preenchido apenas quando o dataState da solicitação é all, os dados são agrupados por date e o período solicitado contém pontos de dados incompletos.

    Todos os valores após first_incomplete_date ainda podem mudar significativamente.

  • first_incomplete_hour (string): a primeira hora em que os dados ainda estão sendo coletados e processados, apresentada no formato YYYY-MM-DDThh:mm:ss[+|-]hh:mm (formato de data e hora de deslocamento estendido ISO-8601).

    Esse campo é preenchido apenas quando o dataState da solicitação é hourly_all, os dados são agrupados por hour e o período solicitado contém pontos de dados incompletos.

    Todos os valores após first_incomplete_hour ainda podem mudar significativamente.

Confira!

Use o APIs Explorer abaixo para chamar esse método em dados ativos e ver a resposta.