GSC_QUERY
Consulta personalizada do Google Search Console com controle total sobre dimensões e filtros.
=GSC_QUERY(startDate, endDate, [dimensions], [limit], [filterDimension], [filterOperator], [filterValue], [siteUrl])Retorna: 2D array with columns for each selected dimension + Clicks, Impressions, CTR, Position
Visão Geral
GSC_QUERY é a função de Search Console mais flexível e poderosa, dando a você controle completo sobre quais dados você recupera e como são estruturados. Enquanto as outras funções GSC cobrem casos de uso comuns com parâmetros simplificados, GSC_QUERY permite especificar dimensões personalizadas, aplicar filtros e combinar múltiplos eixos de dados em uma única requisição. Ela espelha as capacidades completas do endpoint searchAnalytics.query da API do Google Search Console, tornando possível construir virtualmente qualquer relatório de desempenho de pesquisa.
Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
startDate | string | Sim | Data inicial no formato "YYYY-MM-DD" ou formato relativo como "-30d" para 30 dias atrás. |
endDate | string | Sim | Data final no formato "YYYY-MM-DD" ou formato relativo como "-1d" para ontem. |
dimensions | string | Não (query) | Lista separada por vírgulas de dimensões: query, page, country, device, date. Padrão "query". |
limit | number | Não (100) | Número máximo de linhas a retornar. Padrão 100, máximo 25000. |
filterDimension | string | Não | A dimensão a filtrar: query, page, country ou device. |
filterOperator | string | Não | O operador de filtro: "equals", "contains" ou "notContains". |
filterValue | string | Não | O valor a filtrar (por exemplo, um padrão de URL, código de país ou palavra-chave). |
siteUrl | string | Não | A URL da propriedade do Search Console. Se omitida, usa a propriedade conectada padrão. |
Exemplos
Consultas por país
Obtenha as principais consultas detalhadas por país para entender o desempenho de pesquisa geográfica.
=GSC_QUERY("-30d", "-1d", "query,country", 500)Saída
| Query | Country | Clicks | Impressions | CTR | Position |
| best crm software | USA | 520 | 9400 | 5.5% | 3.1 |
| best crm software | GBR | 180 | 3200 | 5.6% | 3.4 |
| crm comparison | USA | 340 | 6100 | 5.6% | 4.2 |
| crm comparison | DEU | 95 | 2100 | 4.5% | 5.8 |
Tendências diárias de cliques
Obtenha cliques e impressões diários totais dos últimos 14 dias para criar gráficos de tendências gerais de pesquisa.
=GSC_QUERY("-14d", "-1d", "date", 14)Saída
| Date | Clicks | Impressions | CTR | Position |
| 2025-03-01 | 1250 | 18500 | 6.8% | 12.3 |
| 2025-03-02 | 1180 | 17800 | 6.6% | 12.5 |
| 2025-03-03 | 1420 | 21200 | 6.7% | 11.8 |
Consultas apenas de blog filtradas por página
Obtenha consultas que geraram tráfego apenas para páginas de blog filtrando pela URL da página contendo "/blog/".
=GSC_QUERY("-30d", "-1d", "query", 200, "page", "contains", "/blog/")Saída
| Query | Clicks | Impressions | CTR | Position |
| how to write a business plan | 890 | 14200 | 6.3% | 3.8 |
| business plan template | 720 | 12500 | 5.8% | 4.1 |
| startup business plan example | 540 | 8900 | 6.1% | 4.5 |
Análise de tráfego não-marca
Exclua consultas de nome de marca para analisar apenas o desempenho de pesquisa orgânica não-marca.
=GSC_QUERY("-30d", "-1d", "query", 1000, "query", "notContains", "mycompany")Saída
| Query | Clicks | Impressions | CTR | Position |
| project management tools | 980 | 22100 | 4.4% | 5.1 |
| task tracking software | 650 | 14800 | 4.4% | 6.3 |
| team collaboration app | 520 | 11200 | 4.6% | 5.8 |
Desempenho Mobile vs Desktop por página
Detalhe o desempenho de página por tipo de dispositivo para identificar páginas com baixo desempenho em mobile.
=GSC_QUERY("-30d", "-1d", "page,device", 500)Saída
| Page | Device | Clicks | Impressions | CTR | Position |
| https://example.com/pricing | DESKTOP | 1800 | 24000 | 7.5% | 2.3 |
| https://example.com/pricing | MOBILE | 1200 | 19000 | 6.3% | 2.8 |
| https://example.com/blog/guide | DESKTOP | 950 | 13500 | 7.0% | 3.5 |
| https://example.com/blog/guide | MOBILE | 1100 | 16200 | 6.8% | 3.2 |
Casos de Uso
Análise de Performance Geográfica
Empresas internacionais analisam desempenho de pesquisa por país para identificar quais mercados têm a visibilidade orgânica mais forte e onde investir em conteúdo localizado e esforços de SEO.
Dashboard de Monitoramento Diário de SEO
Agências constroem dashboards de monitoramento diário usando a dimensão "date" para acompanhar tendências de cliques, detectar quedas súbitas de tráfego e correlacionar mudanças com atualizações de algoritmo do Google ou atividade de concorrentes.
Otimização de SEO Mobile-First
Equipes de desenvolvimento comparam desempenho mobile vs. desktop para páginas chave, identificando problemas de ranking específicos de mobile que indicam problemas de Core Web Vitals ou usabilidade mobile.
Relatórios de Tráfego Não-Marca
Equipes de marketing isolam tráfego de pesquisa não-marca usando filtros de consulta para medir crescimento real de pesquisa orgânica independente de campanhas de awareness de marca e pesquisas diretas de marca.
Performance de Seção de Conteúdo
Editores filtram por padrões de URL de página para comparar desempenho em seções de conteúdo (notícias, opiniões, reviews, tutoriais), orientando alocação de recursos editoriais.
Avaliação de Impacto de Atualização de Algoritmo
Consultores de SEO usam consultas de dimensão de data em torno de datas conhecidas de atualização de algoritmo para medir impacto em sites de clientes, fornecendo recomendações baseadas em dados para estratégias de recuperação.
Dicas Profissionais
Use a dimensão "date" sem nenhuma outra dimensão para obter totais diários de cliques em todo o site, perfeito para criar um gráfico simples de tendência de tráfego.
Filtre por página "contains" um segmento de URL para analisar desempenho para seções específicas do site sem precisar conhecer cada URL de página individual.
Combine dimensões "query,date" com um filtro de consulta para acompanhar mudanças de posição diárias para uma palavra-chave específica ao longo do tempo, criando uma linha de tendência de posição.
Use dimensão "query" com um filtro de página (filterDimension "page", filterOperator "contains", filterValue "/product/") para encontrar todas as palavras-chave gerando tráfego especificamente para páginas de produto.
Para análise de tráfego não-marca, use filterDimension "query" com filterOperator "notContains" e o nome da sua marca como filterValue. Isso é mais eficiente do que filtrar depois.
O parâmetro de dimensões controla quais colunas de dados são retornadas. Você pode solicitar qualquer combinação de "query", "page", "country", "device" e "date" como uma string separada por vírgulas. Por exemplo, dimensões "query,country" retorna desempenho de pesquisa detalhado tanto por palavra-chave quanto por país, enquanto "page,device" mostra desempenho de página dividido por desktop, mobile e tablet. A dimensão "date" é especialmente poderosa pois habilita análise de séries temporais, permitindo criar gráficos de tendências diárias para cliques, impressões e posições.
O sistema de filtragem permite estreitar resultados para subconjuntos específicos de seus dados. Escolha uma dimensão de filtro (query, page, country ou device), um operador (equals, contains ou notContains) e um valor para incluir ou excluir dados específicos. Por exemplo, filtre por página "contains" "/blog/" para ver apenas o desempenho de conteúdo de blog, ou filtre por consulta "notContains" "nome da marca" para isolar tráfego de pesquisa não-marca. Isso elimina a necessidade de pós-processamento com funções FILTER e reduz transferência de dados.
GSC_QUERY é a função a usar quando as funções GSC mais simples não fornecem exatamente a visualização de dados que você precisa. Seja que você queira detalhamentos por país, desempenho específico por dispositivo, dados de tendência diários ou subconjuntos filtrados de suas análises de pesquisa, esta função entrega com uma única fórmula.
Erros Comuns
INVALID_DIMENSION: Dimensão desconhecida especificadaCausa: O parâmetro dimensions contém um nome de dimensão não reconhecido. Dimensões válidas são: query, page, country, device, date.
Correção: Verifique erros de digitação no parâmetro dimensions. Use apenas os valores suportados: "query", "page", "country", "device", "date". Separe múltiplas dimensões com vírgulas e sem espaços (por exemplo, "query,country" não "query, country").
INVALID_FILTER: Operador de filtro deve ser equals, contains ou notContainsCausa: O parâmetro filterOperator contém um valor de operador não suportado.
Correção: Use um dos três operadores suportados: "equals" para correspondência exata, "contains" para correspondência parcial ou "notContains" para exclusão. Estes operadores diferenciam maiúsculas de minúsculas no parâmetro mas aplicam correspondência sem diferenciação de maiúsculas aos dados.
INCOMPLETE_FILTER: Todos os três parâmetros de filtro devem ser fornecidos juntosCausa: Apenas alguns dos parâmetros de filtro (filterDimension, filterOperator, filterValue) foram fornecidos. Todos os três são necessários ao usar filtros.
Correção: Ao aplicar um filtro, você deve fornecer todos os três parâmetros: filterDimension (o que filtrar), filterOperator (como filtrar) e filterValue (qual valor corresponder). Se você não quiser filtrar, omita todos os três parâmetros.
Perguntas Frequentes
Você pode combinar qualquer uma destas dimensões: "query", "page", "country", "device" e "date". Passe-as como uma string separada por vírgulas como "query,country" ou "page,device,date". Cada combinação dá uma seção transversal de dados diferente. Note que mais dimensões resultam em dados mais granulares e mais linhas, então você pode precisar aumentar o parâmetro de limite.
Valores de país são retornados como códigos ISO 3166-1 alpha-3 de 3 letras (por exemplo, "USA", "GBR", "DEU", "FRA", "JPN"). Ao filtrar por país, use esses mesmos códigos. Por exemplo, filterDimension "country", filterOperator "equals", filterValue "USA" para obter apenas dados de pesquisa dos EUA.
A dimensão device retorna três valores: "DESKTOP", "MOBILE" e "TABLET". Ao filtrar por dispositivo, use essas strings exatas. Por exemplo, filterDimension "device", filterOperator "equals", filterValue "MOBILE" para obter apenas dados de pesquisa mobile.
A função atual suporta um único filtro por chamada. Para múltiplas condições de filtro, você pode fazer chamadas GSC_QUERY separadas com diferentes filtros ou aplicar um único filtro de API e então usar a função FILTER do Google Sheets nos resultados para filtragem adicional. Para a maioria dos casos de uso, um filtro combinado com fórmulas de planilha é suficiente.
O operador "equals" corresponde ao valor exato (por exemplo, query equals "seo tools" corresponde apenas àquela consulta exata). O operador "contains" corresponde se o valor da dimensão inclui a string do filtro em qualquer lugar (por exemplo, page contains "/blog/" corresponde qualquer URL com /blog/ nela). O operador "notContains" exclui valores correspondentes (por exemplo, query notContains "nome da marca" exclui todas as consultas de marca). Estes operadores não diferenciam maiúsculas de minúsculas.
Quando "date" é incluída como dimensão, resultados são detalhados por dia individual. Cada linha inclui uma coluna de data no formato "YYYY-MM-DD" junto com as métricas para aquele dia específico. Isso é essencial para análise de séries temporais e criação de gráficos de tendências. Sem a dimensão date, métricas são agregadas em todo o intervalo de datas.
O máximo é 25.000 linhas independentemente das dimensões. No entanto, combinar múltiplas dimensões aumenta dramaticamente o número de linhas únicas. Por exemplo, 1.000 consultas em 5 países produziria até 5.000 linhas. Se seus dados excederem o limite, estreite seu intervalo de datas, adicione um filtro ou reduza dimensões.
Sim, GSC_QUERY é a função de poder subjacente. GSC_TOP_QUERIES é equivalente a GSC_QUERY com dimensões "query", GSC_TOP_PAGES com dimensões "page", GSC_PAGE_QUERIES com dimensões "query" e um filtro de página, e GSC_KEYWORD_POSITION com dimensões "query" e um filtro de consulta. As funções especializadas são mais simples de usar para casos comuns.
Funções Relacionadas
GSC_TOP_QUERIES
Obtenha as principais consultas de pesquisa do Google Search Console ordenadas por cliques.
GSC_TOP_PAGES
Obtenha as principais páginas do Google Search Console ordenadas por cliques.
GSC_PAGE_QUERIES
Obtenha consultas de pesquisa gerando tráfego para uma página específica.
GSC_KEYWORD_POSITION
Obtenha a posição média para uma palavra-chave específica do Google Search Console.
Comece a usar GSC_QUERY hoje
Instale o Unlimited Sheets para obter GSC_QUERY e outras 41 funções poderosas no Google Sheets.
