Esta página foi traduzida pela API Cloud Translation.

Search Analytics: query

Consultar os 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ê precisa 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 decrescente. Se duas linhas tiverem a mesma contagem de cliques, elas serão classificadas de maneira arbitrária.

Consulte o exemplo de Python para chamar esse 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.

Conferir os limites da quantidade de dados disponíveis.

Exemplo de POST JSON:

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 com prefixo de URL) ou `sc-domain:example.com` (para uma propriedade de 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
`startDate`	`string`	[Obrigatório] Data de início do período solicitado no formato AAAA-MM-DD, no fuso horário de Portugal (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 intervalo de datas solicitada, no formato AAAA-MM-DD, no horário de Portugal (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ê fornecer essas dimensões.É possível usar qualquer nome de dimensão em `dimensionFilterGroups[].filters[].dimension`, além de "data". 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 podem ser agrupadas, mas não é possível agrupar pela mesma dimensão duas vezes. Exemplo: [país, dispositivo]
`searchType`	`string`	Descontinuado. Use `type`.
`type`	`string`	[Opcional] Filtre os 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 da guia "Notícias" na 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.
`dimensionFilterGroups[]`	`list`	[Opcional] Zero ou mais grupos de filtros a serem aplicados aos valores de agrupamento de dimensão. Todos os grupos de filtro precisam corresponder para que uma linha seja retornada na resposta. Em um único grupo de filtros, você pode especificar se todos os filtros precisam corresponder ou se pelo menos um precisa corresponder.
`dimensionFilterGroups[].groupType`	`string`	Define se todos os filtros desse grupo precisam retornar verdadeiro ("e") ou se um ou mais precisam retornar verdadeiro (ainda não é compatível). Os valores aceitáveis são os seguintes: "`and`": todos os filtros no grupo precisam retornar verdadeiro para que o grupo de filtro 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. 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 a que este filtro se aplica. Você pode filtrar por qualquer dimensão listada aqui, mesmo que não esteja agrupando por ela. Os valores aceitáveis são: "`country`": filtra o país especificado, conforme especificado pelo 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 aceitos: DESKTOP MOBILE TABLET "`page`": filtra a string de URI especificada. "`query`": filtra a string de consulta especificada. "`searchAppearance`": filtra um recurso específico de resultado da pesquisa. Para conferir 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.
`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 (sem distinção entre maiúsculas e 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 a expressão como uma substring ou uma correspondência completa (sem distinção entre maiúsculas e minúsculas). "`notEquals`": a expressão não precisa ser exatamente igual ao valor da linha (diferencia maiúsculas de minúsculas para dimensões de página e consulta). "`includingRegex`": uma expressão regular da sintaxe RE2 que precisa ser correspondida. "`excludingRegex`": uma expressão regular de sintaxe RE2 que não pode ter correspondência.
`dimensionFilterGroups[].filters[].expression`	`string`	O valor do filtro a ser correspondido ou excluído, dependendo do operador.
`aggregationType`	`string`	[Opcional] Como os dados são agregados. Se for agregado por propriedade, todos os dados da mesma propriedade serão agregados. Se for agregado por página, todos os dados serão agregados pelo URI canônico. Se você filtrar ou agrupar por página, escolha "Automático". Caso contrário, será possível agregar por propriedade ou página, dependendo de como você quer que os dados sejam calculados. Consulte a documentação de ajuda para saber como eles são calculados de maneira 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. 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] permite que o serviço decida o tipo de agregação adequado. "`byNewsShowcasePanel`": valores agregados por painel de Destaques Jornalísticos. Ele precisa ser usado em conjunto com o filtro `searchAppearance` `NEWS_SHOWCASE` e `type=discover` ou `type=googleNews`. Se você agrupar por página, filtrar por página ou filtrar para outra `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 ser retornado. Para navegar pelos 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á bem-sucedida com zero linhas.
`dataState`	`string`	[Opcional] Se "todos" (não diferenciar maiúsculas de minúsculas), os dados incluirão dados atualizados. Se "final" (sem distinção entre maiúsculas e minúsculas) ou se esse parâmetro for omitido, os dados retornados vão incluir 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 por 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 "EUA, tablet" serão agrupados, todos os resultados de "EUA, dispositivo móvel" serão agrupados e assim por diante. Consulte a documentação do relatório do Search Analytics para saber como os cliques, as 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 são classificados por data, em ordem crescente (o mais antigo primeiro, o 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
`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`	Clique na contagem da 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: "`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.