GSC_QUERY
Query personalizzata di Google Search Console con controllo completo su dimensioni e filtri.
=GSC_QUERY(startDate, endDate, [dimensions], [limit], [filterDimension], [filterOperator], [filterValue], [siteUrl])Restituisce: 2D array with columns for each selected dimension + Clicks, Impressions, CTR, Position
Panoramica
GSC_QUERY è la funzione di Search Console più flessibile e potente, dandoti il controllo completo su quali dati recuperi e come sono strutturati. Mentre le altre funzioni GSC coprono casi d'uso comuni con parametri semplificati, GSC_QUERY ti consente di specificare dimensioni personalizzate, applicare filtri e combinare più assi di dati in una singola richiesta. Replica le capacità complete dell'endpoint searchAnalytics.query dell'API di Google Search Console, rendendo possibile costruire praticamente qualsiasi report sulle prestazioni di ricerca.
Parametri
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
startDate | string | Sì | Data di inizio in formato "AAAA-MM-GG" o formato relativo come "-30d" per 30 giorni fa. |
endDate | string | Sì | Data di fine in formato "AAAA-MM-GG" o formato relativo come "-1d" per ieri. |
dimensions | string | No (query) | Elenco separato da virgole di dimensioni: query, page, country, device, date. Predefinito "query". |
limit | number | No (100) | Numero massimo di righe da restituire. Predefinito 100, massimo 25000. |
filterDimension | string | No | La dimensione su cui filtrare: query, page, country o device. |
filterOperator | string | No | L'operatore di filtro: "equals", "contains" o "notContains". |
filterValue | string | No | Il valore su cui filtrare (es. un pattern URL, codice paese o parola chiave). |
siteUrl | string | No | URL della proprietà di Search Console. Se omesso, utilizza la proprietà connessa predefinita. |
Esempi
Query per paese
Ottieni le query principali suddivise per paese per capire le prestazioni di ricerca geografiche.
=GSC_QUERY("-30d", "-1d", "query,country", 500)Output
| 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 |
Tendenze di clic giornalieri
Ottieni clic e impressioni giornalieri totali per gli ultimi 14 giorni per tracciare le tendenze di ricerca complessive.
=GSC_QUERY("-14d", "-1d", "date", 14)Output
| 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 |
Query solo del blog filtrate per pagina
Ottieni query che hanno generato traffico solo verso le pagine del blog filtrando sull'URL della pagina che contiene "/blog/".
=GSC_QUERY("-30d", "-1d", "query", 200, "page", "contains", "/blog/")Output
| 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 |
Analisi del traffico non-branded
Escludi le query del nome brand per analizzare solo le prestazioni di ricerca organica non-branded.
=GSC_QUERY("-30d", "-1d", "query", 1000, "query", "notContains", "mycompany")Output
| 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 |
Prestazioni mobile vs desktop per pagina
Suddividi le prestazioni della pagina per tipo di dispositivo per identificare pagine che hanno prestazioni inferiori su mobile.
=GSC_QUERY("-30d", "-1d", "page,device", 500)Output
| 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 |
Casi d'Uso
Analisi delle prestazioni geografiche
Le aziende internazionali analizzano le prestazioni di ricerca per paese per identificare quali mercati hanno la visibilità organica più forte e dove investire in contenuti localizzati e sforzi SEO.
Dashboard di monitoraggio SEO giornaliero
Le agenzie costruiscono dashboard di monitoraggio giornaliero usando la dimensione "date" per tracciare le tendenze dei clic, individuare cali improvvisi di traffico e correlare i cambiamenti con aggiornamenti dell'algoritmo di Google o attività dei competitor.
Ottimizzazione SEO mobile-first
I team di sviluppo confrontano le prestazioni mobile vs. desktop per pagine chiave, identificando problemi di posizionamento specifici per mobile che indicano problemi di Core Web Vitals o usabilità mobile.
Reportistica del traffico non-branded
I team di marketing isolano il traffico di ricerca non-branded usando filtri di query per misurare la vera crescita della ricerca organica indipendente dalle campagne di brand awareness e dalle ricerche dirette del brand.
Prestazioni delle sezioni di contenuto
Gli editori filtrano per pattern URL di pagina per confrontare le prestazioni tra sezioni di contenuto (notizie, opinioni, recensioni, tutorial), guidando l'allocazione delle risorse editoriali.
Valutazione dell'impatto degli aggiornamenti algoritmo
I consulenti SEO usano query con dimensione date intorno a date di aggiornamento algoritmo note per misurare l'impatto sui siti dei clienti, fornendo raccomandazioni basate sui dati per strategie di recupero.
Suggerimenti Professionali
Usa la dimensione "date" senza altre dimensioni per ottenere totali di clic giornalieri a livello di sito, perfetto per creare un semplice grafico delle tendenze di traffico.
Filtra per page "contains" un segmento URL per analizzare le prestazioni per sezioni specifiche del sito senza dover conoscere ogni singolo URL di pagina.
Combina le dimensioni "query,date" con un filtro di query per tracciare i cambiamenti di posizione giornalieri per una parola chiave specifica nel tempo, creando una linea di tendenza di posizione.
Usa la dimensione "query" con un filtro di pagina (filterDimension "page", filterOperator "contains", filterValue "/product/") per trovare tutte le parole chiave che generano traffico specificamente verso le pagine prodotto.
Per l'analisi del traffico non-branded, usa filterDimension "query" con filterOperator "notContains" e il tuo nome brand come filterValue. Questo è più efficiente che filtrare dopo il fatto.
Il parametro dimensions controlla quali colonne di dati vengono restituite. Puoi richiedere qualsiasi combinazione di "query", "page", "country", "device" e "date" come stringa separata da virgole. Ad esempio, dimensions "query,country" restituisce le prestazioni di ricerca suddivise per parola chiave e paese, mentre "page,device" mostra le prestazioni della pagina divise per desktop, mobile e tablet. La dimensione "date" è particolarmente potente in quanto abilita l'analisi time-series, permettendoti di tracciare le tendenze giornaliere per clic, impressioni e posizioni.
Il sistema di filtraggio ti consente di restringere i risultati a sottoinsiemi specifici dei tuoi dati. Scegli una dimensione di filtro (query, page, country o device), un operatore (equals, contains o notContains) e un valore da includere o escludere dati specifici. Ad esempio, filtra per page "contains" "/blog/" per vedere solo le prestazioni dei contenuti del blog, o filtra per query "notContains" "nome brand" per isolare il traffico di ricerca non-branded. Questo elimina la necessità di post-elaborazione con funzioni FILTER e riduce il trasferimento dati.
GSC_QUERY è la funzione da usare quando le funzioni GSC più semplici non forniscono esattamente la vista dati di cui hai bisogno. Che tu voglia suddivisioni a livello di paese, prestazioni specifiche per dispositivo, dati di tendenza giornalieri o sottoinsiemi filtrati delle tue analisi di ricerca, questa funzione li fornisce con una singola formula.
Errori Comuni
INVALID_DIMENSION: Dimensione sconosciuta specificataCausa: Il parametro dimensions contiene un nome di dimensione non riconosciuto. Le dimensioni valide sono: query, page, country, device, date.
Soluzione: Controlla gli errori di battitura nel parametro dimensions. Usa solo i valori supportati: "query", "page", "country", "device", "date". Separa più dimensioni con virgole e senza spazi (es. "query,country" non "query, country").
INVALID_FILTER: L'operatore di filtro deve essere equals, contains o notContainsCausa: Il parametro filterOperator contiene un valore di operatore non supportato.
Soluzione: Usa uno dei tre operatori supportati: "equals" per corrispondenza esatta, "contains" per corrispondenza parziale o "notContains" per esclusione. Questi operatori fanno distinzione tra maiuscole e minuscole nel parametro ma applicano corrispondenza case-insensitive ai dati.
INCOMPLETE_FILTER: Tutti e tre i parametri di filtro devono essere forniti insiemeCausa: Solo alcuni dei parametri di filtro (filterDimension, filterOperator, filterValue) sono stati forniti. Tutti e tre sono richiesti quando si usano filtri.
Soluzione: Quando applichi un filtro, devi fornire tutti e tre i parametri: filterDimension (cosa filtrare), filterOperator (come filtrare) e filterValue (quale valore corrispondere). Se non vuoi filtrare, ometti tutti e tre i parametri.
Domande Frequenti
Puoi combinare una qualsiasi di queste dimensioni: "query", "page", "country", "device" e "date". Passale come stringa separata da virgole come "query,country" o "page,device,date". Ogni combinazione ti dà una diversa sezione trasversale di dati. Nota che più dimensioni risultano in dati più granulari e più righe, quindi potresti dover aumentare il parametro limit.
I valori dei paesi vengono restituiti come codici ISO 3166-1 alpha-3 a 3 lettere (es. "USA", "GBR", "DEU", "FRA", "JPN"). Quando filtri per paese, usa questi stessi codici. Ad esempio, filterDimension "country", filterOperator "equals", filterValue "USA" per ottenere solo dati di ricerca USA.
La dimensione device restituisce tre valori: "DESKTOP", "MOBILE" e "TABLET". Quando filtri per dispositivo, usa queste stringhe esatte. Ad esempio, filterDimension "device", filterOperator "equals", filterValue "MOBILE" per ottenere solo dati di ricerca mobile.
La funzione corrente supporta un singolo filtro per chiamata. Per condizioni di filtro multiple, puoi fare chiamate GSC_QUERY separate con filtri diversi o applicare un singolo filtro API e poi usare la funzione FILTER di Google Sheets sui risultati per ulteriore filtraggio. Per la maggior parte dei casi d'uso, un filtro combinato con formule del foglio di calcolo è sufficiente.
L'operatore "equals" corrisponde al valore esatto (es. query equals "seo tools" corrisponde solo a quella query esatta). L'operatore "contains" corrisponde se il valore della dimensione include la stringa del filtro ovunque (es. page contains "/blog/" corrisponde a qualsiasi URL con /blog/ in esso). L'operatore "notContains" esclude valori corrispondenti (es. query notContains "nome brand" esclude tutte le query del brand). Questi operatori non fanno distinzione tra maiuscole e minuscole.
Quando "date" è inclusa come dimensione, i risultati sono suddivisi per singolo giorno. Ogni riga include una colonna date in formato "AAAA-MM-GG" insieme alle metriche per quel giorno specifico. Questo è essenziale per l'analisi time-series e la creazione di grafici delle tendenze. Senza la dimensione date, le metriche sono aggregate sull'intero intervallo di date.
Il massimo è di 25.000 righe indipendentemente dalle dimensioni. Tuttavia, combinare più dimensioni aumenta drammaticamente il numero di righe uniche. Ad esempio, 1.000 query in 5 paesi produrrebbero fino a 5.000 righe. Se i tuoi dati superano il limite, restringi il tuo intervallo di date, aggiungi un filtro o riduci le dimensioni.
Sì, GSC_QUERY è la funzione potente sottostante. GSC_TOP_QUERIES è equivalente a GSC_QUERY con dimensions "query", GSC_TOP_PAGES con dimensions "page", GSC_PAGE_QUERIES con dimensions "query" e un filtro di pagina, e GSC_KEYWORD_POSITION con dimensions "query" e un filtro di query. Le funzioni specializzate sono più semplici da usare per casi comuni.
Funzioni Correlate
GSC_TOP_QUERIES
Ottieni le query di ricerca principali da Google Search Console ordinate per clic.
GSC_TOP_PAGES
Ottieni le pagine principali da Google Search Console ordinate per clic.
GSC_PAGE_QUERIES
Ottieni le query di ricerca che generano traffico verso una pagina specifica.
GSC_KEYWORD_POSITION
Ottieni la posizione media per una parola chiave specifica da Google Search Console.
Inizia a usare GSC_QUERY oggi
Installa Unlimited Sheets per ottenere GSC_QUERY e altre 41 potenti funzioni in Google Sheets.
