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ê define. Você deve 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 no 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 maneira arbitrária.

Consulte o exemplo do Python para chamar este método.

A API é limitada por limitações internas do Search Console e não garante o retorno de todas as linhas de dados, somente as primeiras.

Veja 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
        }
      ]
    }
  ],
  "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. Este 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 PT (UTC - 7:00/8:00). Precisa ser maior ou igual à data de início. Este 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.É possível usar qualquer nome de dimensão em dimensionFilterGroups[].filters[].dimension, além de "data".Os valores das dimensões 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 podem ser agrupadas, mas não é possível agrupar pela mesma dimensão duas vezes. Exemplo: [país, dispositivo]
searchType string Descontinuado. Em vez disso, use type
type string [Opcional] Filtre os resultados para o seguinte tipo:
  • "discover": descobrir resultados
  • "googleNews": resultados do news.google.com e do app Google Notícias em Android e iOS. Não inclui resultados de "Notícias" na Pesquisa Google.
  • "news": resultados da pesquisa de "Notícias" na Pesquisa Google.
  • "image": resultados da pesquisa de "Imagem" na Pesquisa Google.
  • "video": resultados da pesquisa de vídeos
  • "web": [padrão] filtra os resultados para a guia combinada ("Todos") em Pesquisa Google. Não inclui resultados do Discover ou do Google Notícias.
dimensionFilterGroups[] list [Opcional] Zero ou mais grupos de filtros para aplicar aos valores do agrupamento de dimensões. Todos os grupos de filtros precisam ser correspondentes para que uma linha seja retornada na resposta. Em um único grupo de filtros, é possível especificar se todos os filtros precisam corresponder ou pelo menos um.
dimensionFilterGroups[].groupType string Indica se todos os filtros neste grupo precisam retornar "true" ("e") ou um ou mais precisam retornar "true" (ainda não compatível).

Os valores aceitáveis são os seguintes:
  • "and": todos os filtros do grupo precisam retornar "true" no grupo de filtros para ser 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. Comprimento máximo de 4.096 caracteres. Exemplos:
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string A dimensão à qual este filtro se aplica. É possível filtrar por qualquer dimensão listada aqui, mesmo que você não esteja agrupando por essa dimensão.

Os valores aceitáveis são:
  • "country": filtra o país especificado, conforme o código do país de três letras (ISO 3166-1 alfa-3).
  • "device": filtrar os resultados de acordo com o tipo de dispositivo especificado. Valores aceitos:
    • COMPUTADORES
    • DISPOSITIVOS MÓVEIS
    • TABLET
  • "page": filtra a string de URI especificada.
  • "query": filtra a string de consulta especificada.
  • "searchAppearance": filtre de acordo com um recurso específico de resultado da pesquisa. Para ver uma lista de valores disponíveis, execute uma consulta agrupada por "searchAppearance".
dimensionFilterGroups[].filters[].operator string [Opcional] Indica como o valor especificado precisa corresponder (ou não) ao valor de dimensão da linha.

Os valores aceitáveis são os seguintes:
  • "contains": o valor da linha precisa conter ou ser igual à sua expressão (sem diferenciação de maiúsculas e minúsculas).
  • "equals": [padrão] a expressão precisa ser exatamente igual ao valor da linha (diferencia maiúsculas de minúsculas nas dimensões de página e consulta).
  • "notContains": o valor da linha não pode conter sua expressão como uma substring ou como uma correspondência completa (sem diferenciação de maiúsculas e minúsculas).
  • "notEquals": sua expressão não pode ser exatamente igual ao valor da linha (diferencia maiúsculas de minúsculas nas dimensões de página e consulta).
  • "includingRegex": um Expressão regular da sintaxe RE2 que precisa ser correspondida.
  • "excludingRegex": um Expressão regular da sintaxe RE2 que não pode ter correspondência.
dimensionFilterGroups[].filters[].expression string O valor do filtro para corresponder ou excluir, dependendo do operador.
aggregationType string

[Opcional] Como os dados são agregados. Se agregados por propriedade, todos os dados de a mesma propriedade é agregada; Se forem agregados por página, todos os dados serão agregados por página canônica URI. Ao filtrar ou agrupar por página, escolha "Automático". caso contrário, você pode agregar por propriedade ou página, dependendo de como você quer que os dados sejam calculados, ver 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 outro valor que não seja automático, o tipo de agregação no resultado 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 os seguintes:
  • "auto": [Padrão] deixa o serviço decidir o tipo de agregação apropriado.
  • "byNewsShowcasePanel": agregar valores por Painel de Destaques Jornalísticos. Precisa ser usado em combinação com o NEWS_SHOWCASE searchAppearance. e type=discover ou type=googleNews. Se você agrupar por página, filtrar por página ou filtrar por outra searchAppearance, não é possível agregar por byNewsShowcasePanel.
  • "byPage": valores agregados por URI.
  • "byProperty": agrega valores por propriedade. Incompatí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. Precisa ser um número não negativo. Se startRow exceder o número de resultados da consulta, a resposta será uma resposta bem-sucedida sem linhas.
dataState string [Opcional] Se "todos" (não diferencia maiúsculas de minúsculas), os dados incluirão dados atualizados. Se for "final" (não diferencia maiúsculas de minúsculas) ou, se esse parâmetro for omitido, os dados retornados incluirão apenas dados finalizados.

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 são agrupados em uma única linha. Por exemplo, se você agrupar pela dimensão "País", todos os resultados para "EUA" serão agrupados, todos os resultados para "mdv" serão agrupados e assim por diante. Se você tiver agrupado por país e dispositivo, todos os resultados para "EUA, tablet" serão agrupados, todos os resultados para "EUA, celular" serão agrupados e assim por diante. Consulte a documentação de relatórios de Search Analytics para saber os detalhes de como cliques, impressões e assim por diante 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 serão classificados por data, em ordem crescente (mais antigo primeiro, mais recente por último). 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 informada 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 para a linha.
rows[].impressions double Contagem de impressões para a linha.
rows[].ctr double Taxa de cliques (CTR) da linha. Os valores variam de 0 a 1, 0.
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 forma diferente por site e por página.

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

Confira!

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