Search Analytics: query

Richiede l'autorizzazione

Eseguire query sui dati del traffico di ricerca con filtri e parametri da te definiti. Il metodo restituisce zero o più righe raggruppate in base alle chiavi di riga (dimensioni) definite. Devi definire un intervallo di date di uno o più giorni.

Se la data è una delle dimensioni, i giorni senza dati vengono omessi dall'elenco dei risultati. Per sapere quali giorni contengono dati, esegui una query senza filtri raggruppati per data, per l'intervallo di date che ti interessa.

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

Vedi l'esempio Python per chiamare questo metodo.

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

Consulta i limiti per la quantità di dati disponibili.

Esempio di 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"]
}
Prova subito.

Richiesta

Richiesta HTTP

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

Parametri

Nome del 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à del 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] La data di inizio dell'intervallo di date richiesto, nel formato AAAA-MM-GG, espressa nel campo Ora PT (UTC - 7:00/8:00). Deve essere inferiore o uguale alla data di fine. Questo valore è incluso nell'intervallo.
endDate string [Obbligatorio] Data di fine dell'intervallo di date richiesto, nel formato AAAA-MM-GG, nel fuso orario 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 e in "data".I valori delle dimensioni 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 alcun limite al numero di dimensioni che puoi utilizzare per il raggruppamento, ma non puoi farlo due volte in base alla stessa dimensione. Esempio: [paese, dispositivo]
searchType string Deprecato, utilizza invece type
type string [Facoltativo] Filtra i risultati in base al seguente tipo:
  • "discover": risultati di Discover
  • "googleNews": risultati 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 dalla scheda "Notizie" nella Ricerca Google.
  • "image": risultati di ricerca dalla scheda "Immagini" nella Ricerca Google.
  • "video": risultati di ricerca video
  • "web": [Predefinito] Filtra i risultati in base alla scheda Combinato ("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 del raggruppamento di dimensioni. Affinché una riga venga restituita nella risposta, tutti i gruppi di filtri devono corrispondere. All'interno di un singolo gruppo di filtri, puoi specificare se tutti i filtri devono corrispondere o almeno uno deve corrispondere.
dimensionFilterGroups[].groupType string Indica se tutti i filtri di questo gruppo devono restituire true ("and") oppure uno o più devono restituire true (non ancora supportato).

I valori accettati sono:
  • "and": per poter essere true, tutti i filtri nel gruppo devono restituire il valore true per il gruppo di filtri.
dimensionFilterGroups[].filters[] list [Facoltativo] Zero o più filtri da testare in base alla riga. Ogni filtro è costituito 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 eseguendo il raggruppamento in base a questa dimensione.

I valori accettati sono:
  • "country": consente di applicare un filtro in base al paese specificato, come specificato 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
    • DISPOSITIVI MOBILI
    • TABLET
  • "page": filtro in base alla stringa URI specificata.
  • "query": filtro in base alla stringa di query specificata.
  • "searchAppearance": consente di applicare un filtro in base a una funzionalità di risultato di ricerca specifica. Per visualizzare un elenco dei valori disponibili, esegui una query raggruppata per "searchAspetto".
dimensionFilterGroups[].filters[].operator string [Facoltativo] Indica in che modo il valore specificato deve corrispondere (o non corrispondere) al valore della dimensione della riga.

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

[Facoltativo] Modalità di aggregazione dei dati. Se aggregati per proprietà, tutti i dati relativi alla stessa proprietà vengono aggregati; se aggregati per pagina, tutti i dati vengono aggregati per URI canonico. Se filtri o raggruppi i dati per pagina, scegli l'opzione automatica. In caso contrario, puoi aggregare i dati per proprietà o pagina, a seconda di come vuoi che vengano calcolati i dati. Consulta la documentazione di assistenza per scoprire in che modo i dati vengono calcolati in modo diverso per sito e per pagina.

Nota: se raggruppi o filtri per pagina, non puoi aggregare i dati per proprietà.

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

I valori accettati sono:
  • "auto": [valore predefinito] Consenti al servizio di decidere il tipo di aggregazione appropriato.
  • "byNewsShowcasePanel": aggrega i valori per riquadro News Showcase. Deve essere utilizzato in combinazione con il filtro NEWS_SHOWCASE searchAppearance e type=discover o type=googleNews. Se raggruppi per pagina, filtri per pagina o filtri in base a un altro searchAppearance, non puoi aggregare 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; l'intervallo valido è 1-25.000; il valore predefinito è 1000] Il numero massimo di righe da restituire. Per sfogliare 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 scegli "Tutti" (senza distinzione tra maiuscole e minuscole), i dati includeranno dati aggiornati. Se è "finale" (senza distinzione tra maiuscole e minuscole) o se questo parametro viene omesso, i dati restituiti includeranno solo dati finalizzati.

Risposta

I risultati vengono raggruppati in base alle dimensioni specificate nella richiesta. Tutti i valori con lo stesso insieme di valori di dimensione verranno raggruppati in un'unica riga. Ad esempio, se raggruppi per dimensione Paese, tutti i risultati per "usa" vengono raggruppati, tutti i risultati per "mdv" e così via. Se hai raggruppato per paese e dispositivo, tutti i risultati per "usa, tablet" verranno raggruppati, tutti i risultati per "usa, cellulare" e così via. Consulta la documentazione relativa al report Analisi delle ricerche per conoscere le specifiche di come vengono calcolati i clic, le impressioni e così via e il relativo significato.

I risultati vengono ordinati per numero di clic, in ordine decrescente, a meno che non li raggruppi per data, nel qual caso vengono ordinati per data, in ordine crescente (dal meno recente, dal più recente). In caso di parità tra due righe, l'ordinamento è arbitrario.

Controlla la proprietà rowLimit nella richiesta per conoscere 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 alle coppie chiave-valore nell'ordine indicato nella query.
rows[].keys[] list Un elenco dei valori delle dimensioni per la riga in questione, raggruppati in base alle dimensioni nella richiesta, nell'ordine specificato nella richiesta.
rows[].clicks double Conteggio dei clic per la riga.
rows[].impressions double Numero di 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 Modalità di aggregazione dei risultati.Consulta la documentazione della guida per scoprire in che modo i dati vengono calcolati in modo diverso in base al sito e alla pagina.

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

Prova.

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