Search Analytics: query

Richiede autorizzazione

Esegui query sui dati sul traffico di ricerca con filtri e parametri che definisci. Il metodo restituisce zero o più righe raggruppate in base alle chiavi di riga (dimensioni) che definisci. Devi definire un intervallo di date di uno o più giorni.

Quando la data è una delle dimensioni, i giorni senza dati vengono omessi dall'elenco dei risultati. Per scoprire quali giorni contengono dati, esegui una query senza filtri raggruppati per data per l'intervallo di date di interesse.

I risultati sono ordinati in base al conteggio dei clic in ordine decrescente. Se due righe hanno lo stesso numero di clic, vengono ordinate in modo arbitrario.

Per chiamare questo metodo, consulta l'esempio di Python.

L'API è limitata da limitazioni interne di Search Console e non garantisce la restituzione di tutte le righe di dati, ma solo di quelle principali.

Visualizza i limiti alla quantità di dati disponibili.

Esempio di POST JSON: 
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fblue-sea-697d.quartiers047.workers.dev%3A443%2Fhttps%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
  "startDate": "2015-04-01",
  "endDate": "2015-05-01",
  "dimensions": ["country","device"]
}
Prova subito.

Richiesta

Richiesta HTTP

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

Parametri

Nome parametro Valore Descrizione
Parametri del percorso
siteUrl string L'URL della proprietà come definito in Search Console. Esempi: http://www.example.com/ (per una proprietà con prefisso URL) o sc-domain:example.com (per una proprietà Dominio)

Autorizzazione

Questa richiesta richiede l'autorizzazione con almeno uno dei seguenti ambiti (scopri di più su autenticazione e autorizzazione).

Ambito
https://www.googleapis.com/auth/webmasters.readonly
https://www.googleapis.com/auth/webmasters

Corpo della richiesta

Nel corpo della richiesta, fornisci i dati con la seguente struttura:

{
  "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 proprietà Valore Descrizione Note
startDate string [Obbligatorio] Data di inizio dell'intervallo di date richiesto, nel formato AAAA-MM-GG, in ora PT (UTC - 7:00/8:00). Deve essere precedente o uguale alla data di fine. Questo valore è incluso nell'intervallo.
endDate string [Obbligatorio] Data di fine dell'intervallo di date richiesto, in formato AAAA-MM-GG, in ora PT (UTC - 7:00/8:00). Deve essere maggiore o uguale alla data di inizio. Questo valore è incluso nell'intervallo.
dimensions[] list [Facoltativo] Zero o più dimensioni in base alle quali raggruppare i risultati. I risultati vengono raggruppati nell'ordine in cui fornisci queste dimensioni. Puoi utilizzare qualsiasi nome di dimensione in dimensionFilterGroups[].filters[].dimension, nonché "data" e "ora". I valori della dimensione di raggruppamento vengono combinati per creare una chiave univoca per ogni riga di risultati. Se non vengono specificate dimensioni, tutti i valori verranno combinati in un'unica riga. Non esiste un limite al numero di dimensioni in base alle quali puoi raggruppare, ma non puoi raggruppare in base alla stessa dimensione due volte. Esempio: [country, device]
searchType string Deprecato, utilizza type
type string [Facoltativo] Filtra i risultati in base al seguente tipo:
  • "discover": risultati di Discover
  • "googleNews": risultati provenienti da news.google.com e dall'app Google News su Android e iOS. Non include i risultati della scheda "Notizie" nella Ricerca Google.
  • "news": risultati di ricerca della scheda "Notizie" nella Ricerca Google.
  • "image": risultati di ricerca della scheda "Immagini" nella Ricerca Google.
  • "video": risultati di ricerca video
  • "web": [Predefinito] Filtra i risultati in base alla scheda combinata ("Tutti") nella Ricerca Google. Non include i risultati di Discover o Google News.
dimensionFilterGroups[] list [Facoltativo] Zero o più gruppi di filtri da applicare ai valori di raggruppamento delle dimensioni. Tutti i gruppi di filtri devono corrispondere affinché una riga venga restituita nella risposta. All'interno di un singolo gruppo di filtri, puoi specificare se tutti i filtri devono corrispondere o se deve corrispondere almeno uno.
dimensionFilterGroups[].groupType string Indica se tutti i filtri di questo gruppo devono restituire il valore vero ("e") o se uno o più devono restituire il valore vero (non ancora supportato).

I valori accettati sono:
  • "and": tutti i filtri del gruppo devono restituire il valore true affinché il gruppo di filtrisia vero.
dimensionFilterGroups[].filters[] list [Facoltativo] Zero o più filtri da testare rispetto alla riga. Ogni filtro è composto da un nome di dimensione, un operatore e un valore. Lunghezza massima 4096 caratteri. Esempi: 
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string La dimensione a cui si applica questo filtro. Puoi filtrare in base a qualsiasi dimensione elencata qui, anche se non stai raggruppando in base a quella dimensione.

I valori accettati sono:
  • "country": filtra in base al paese specificato, come indicato dal codice paese di tre lettere (ISO 3166-1 alpha-3).
  • "device": filtra i risultati in base al tipo di dispositivo specificato. Valori supportati:
    • DESKTOP
    • MOBILE
    • TABLET
  • "page": filtra in base alla stringa URI specificata.
  • "query": filtra in base alla stringa di query specificata.
  • "searchAppearance": filtra in base a una funzionalità specifica dei risultati di ricerca. Per visualizzare un elenco dei valori disponibili, esegui una query raggruppata per "searchAppearance". L'elenco completo dei valori e delle descrizioni è disponibile anche nella documentazione di assistenza.
dimensionFilterGroups[].filters[].operator string [Facoltativo] In che modo il valore specificato deve corrispondere (o non corrispondere) al valore della dimensione per la riga.

I valori accettati sono:
  • "contains": il valore della riga deve contenere o essere uguale all'espressione (senza distinzione tra maiuscole e minuscole).
  • "equals": [Predefinito] L'espressione deve corrispondere esattamente al valore della riga (sensibile alle maiuscole per le dimensioni pagina e query).
  • "notContains": il valore della riga non deve contenere l'espressione come sottostringa o come corrispondenza completa (senza distinzione tra maiuscole e minuscole).
  • "notEquals": l'espressione non deve essere esattamente uguale al valore della riga (sensibile alle maiuscole e minuscole per le dimensioni pagina e query).
  • "includingRegex": un'espressione regolare con sintassi RE2 che deve corrispondere.
  • "excludingRegex": un'espressione regolare con sintassi RE2 che non deve corrispondere.
dimensionFilterGroups[].filters[].expression string Il valore da includere o escludere dal filtro, a seconda dell'operatore.
aggregationType string

[Facoltativo] Modalità di aggregazione dei dati. Se i dati sono aggregati per proprietà, vengono aggregati tutti i dati per la stessa proprietà; se sono aggregati per pagina, vengono aggregati tutti i dati per URI canonico. Se filtri o raggruppi per pagina, scegli Automatico; altrimenti puoi aggregare per proprietà o per pagina, a seconda di come vuoi che vengano calcolati i dati. Consulta la documentazione del Centro assistenza per scoprire come i dati vengono calcolati in modo diverso per sito e per pagina.

Nota: Se raggruppi o filtri per pagina, non puoi aggregare per proprietà.

Se specifichi un valore diverso da auto, il tipo di aggregazione nel risultato corrisponderà al tipo richiesto oppure, se richiedi un tipo non valido, riceverai un errore. L'API non modificherà mai il tipo di aggregazione se il tipo richiesto non è valido.

I valori accettabili sono:
  • "auto": [Predefinito] Consente al servizio di decidere il tipo di aggregazione appropriato.
  • "byNewsShowcasePanel": aggrega i valori per pannello News Showcase. Deve essere utilizzato in combinazione con il filtro NEWS_SHOWCASE searchAppearance e con type=discover o type=googleNews. Se raggruppi per pagina, filtri per pagina o filtri per un altro searchAppearance, non puoi eseguire l'aggregazione per byNewsShowcasePanel.
  • "byPage": aggrega i valori per URI.
  • "byProperty": aggrega i valori per proprietà. Non supportato per type=discover o type=googleNews
rowLimit integer [Facoltativo; intervallo valido 1-25.000; valore predefinito 1000] Il numero massimo di righe da restituire. Per scorrere i risultati, utilizza l'offset startRow.
startRow integer [Facoltativo; il valore predefinito è 0] Indice in base zero della prima riga nella risposta. Deve essere un numero non negativo. Se startRow supera il numero di risultati per la query, la risposta sarà una risposta riuscita con zero righe.
dataState string [Facoltativo] Se "all" (senza distinzione tra maiuscole e minuscole), i dati includeranno dati aggiornati. Se il valore è "final" (senza distinzione tra maiuscole e minuscole) o se questo parametro viene omesso, i dati restituiti includeranno solo i dati finalizzati. Se "hourly_all" (senza distinzione tra maiuscole e minuscole), i dati includeranno la suddivisione oraria. Questo indica che i dati orari includono dati parziali e devono essere utilizzati quando si raggruppano in base alla dimensione API HOUR.

Risposta

I risultati vengono raggruppati in base alle dimensioni specificate nella richiesta. Tutti i valori con lo stesso insieme di valori delle dimensioni verranno raggruppati in un'unica riga. Ad esempio, se raggruppi in base alla dimensione Paese, tutti i risultati per "usa" verranno raggruppati, tutti i risultati per "mdv" verranno raggruppati e così via. Se hai raggruppato per paese e dispositivo, tutti i risultati per "Stati Uniti, tablet" verranno raggruppati, tutti i risultati per "Stati Uniti, dispositivo mobile" verranno raggruppati e così via. Consulta la documentazione del report Analisi della ricerca per scoprire i dettagli su come vengono calcolati i clic, le impressioni e così via e cosa significano.

I risultati vengono ordinati in base al conteggio dei clic, in ordine decrescente, a meno che non vengano raggruppati per data, nel qual caso vengono ordinati per data, in ordine crescente (dal più vecchio al più recente). Se due righe hanno lo stesso valore, l'ordinamento è arbitrario.

Consulta la proprietà rowLimit nella richiesta per scoprire il numero massimo di valori che possono essere restituiti.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
Nome proprietà Valore Descrizione Note
rows[] list Un elenco di righe raggruppate in base ai valori delle chiavi nell'ordine specificato nella query.
rows[].keys[] list Un elenco dei valori delle dimensioni per quella riga, raggruppati in base alle dimensioni nella richiesta, nell'ordine specificato nella richiesta.
rows[].clicks double Conteggio dei clic per la riga.
rows[].impressions double Conteggio delle impressioni per la riga.
rows[].ctr double Percentuale di clic (CTR) per la riga. I valori sono compresi tra 0 e 1,0, inclusi.
rows[].position double Posizione media nei risultati di ricerca.
responseAggregationType string Come sono stati aggregati i risultati. Consulta la documentazione del Centro assistenza per scoprire in che modo i dati vengono calcolati in modo diverso per sito e per pagina.

I valori accettati sono:
  • "auto"
  • "byPage": i risultati sono stati aggregati per pagina.
  • "byProperty": i risultati sono stati aggregati per proprietà.
metadata object

Un oggetto che può essere restituito con i risultati della query, fornendo il contesto sullo stato dei dati.

Quando richiedi dati recenti (utilizzando all o hourly_all per dataState), alcune delle righe restituite potrebbero rappresentare dati incompleti, il che significa che i dati sono ancora in fase di raccolta ed elaborazione. Questo oggetto di metadati ti aiuta a identificare esattamente quando inizia e termina.

Tutte le date e gli orari forniti in questo oggetto sono nel fuso orario America/Los_Angeles.

Il campo specifico restituito all'interno di questo oggetto dipende da come hai raggruppato i dati nella richiesta:

  • first_incomplete_date (string): la prima data per cui i dati vengono ancora raccolti ed elaborati, presentata nel formato YYYY-MM-DD (formato della data locale esteso ISO-8601).

    Questo campo viene compilato solo quando dataState della richiesta è all e i dati sono raggruppati per date e l'intervallo di date richiesto contiene punti dati incompleti.

    Tutti i valori dopo first_incomplete_date potrebbero comunque cambiare in modo significativo.

  • first_incomplete_hour (string): la prima ora per cui i dati vengono ancora raccolti ed elaborati, presentata in formato YYYY-MM-DDThh:mm:ss[+|-]hh:mm (formato data e ora con offset esteso ISO-8601).

    Questo campo viene compilato solo quando dataState della richiesta è hourly_all e i dati sono raggruppati per hour e l'intervallo di date richiesto contiene punti dati incompleti.

    Tutti i valori dopo first_incomplete_hour potrebbero comunque cambiare in modo significativo.

Prova

Utilizza Explorer API di seguito per chiamare questo metodo sui dati live e visualizzare la risposta.