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, todos 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 maneira arbitrária.
Veja o exemplo em 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, mas das principais.
Consulte os limites para a quantidade de dados disponíveis.
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"] }
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 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 | Observações |
---|---|---|---|
startDate |
string |
[Obrigatório] Data de início do período solicitado, no formato AAAA-MM-DD, no horário do PT (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 PT (UTC - 7:00/8:00). Precisa ser maior ou igual à data de início. Esse valor está incluído no intervalo. | |
dimensions[] |
list |
[Opcional] Nenhuma 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, assim como "data".Os valores das dimensões de agrupamento são combinados para criar uma chave única 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: [country, device] | |
searchType |
string |
Descontinuado, use type
|
|
type |
string |
[Opcional] Filtre os resultados para o seguinte tipo:
|
|
dimensionFilterGroups[] |
list |
[Opcional] Nenhum 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, você pode especificar se todos os filtros precisam ser correspondentes ou pelo menos um deles precisa ser correspondente. | |
dimensionFilterGroups[].groupType |
string |
Define se todos os filtros nesse grupo precisam retornar verdadeiro ("e") ou um ou mais deles precisam retornar "true" (ainda não é compatível).
Os valores aceitáveis são os seguintes:
|
|
dimensionFilterGroups[].filters[] |
list |
[Opcional] Nenhum 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. É 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:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Opcional] Como o valor especificado precisa corresponder (ou não) ao valor de dimensão da linha.
Os valores aceitáveis são os seguintes:
|
|
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 forem agregados por propriedade, todos os dados da mesma propriedade vão ser agregados. Se forem agregados por página, todos eles vão ser agregados por URI canônico. Se você filtrar ou agrupar por página, escolha "automático". Caso contrário, agregue por propriedade ou 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 ou 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, receberá um erro. A API nunca vai mudar o tipo de agregação se o solicitado for inválido. Estes são os valores aceitáveis:
|
|
rowLimit |
integer |
[Opcional. Intervalo válido de 1 a 25.000. O padrão é 1.000] O número máximo de linhas a serem retornadas. Para percorrer os resultados, use o deslocamento startRow . |
|
startRow |
integer |
[Opcional; o padrão é 0] Índice baseado em zero da primeira linha da resposta. Precisa ser um número não negativo. Se startRow exceder o número de resultados para a 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 serão agrupados em uma única linha. Por exemplo, se você agrupar pela dimensão "país", todos os resultados de "usa" serão agrupados, todos os resultados de "mdv" serão agrupados, e assim por diante. Se você tiver agrupado por país e dispositivo, todos os resultados para "usa, tablet" serão agrupados, todos os resultados para "usa, dispositivo móvel" serão agrupados e assim por diante. Consulte a documentação de relatórios do Search Analytics para saber mais detalhes de como são calculados os cliques, as impressões e assim por diante.
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 (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-chave na ordem dada 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, 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 forma diferente por site e página.
Os valores aceitáveis são os seguintes:
|
Confira!
Use o APIs Explorer abaixo para chamar esse método em dados ativos e ver a resposta.