Richiede l'autorizzazione
Eseguire query sui dati del traffico di ricerca con i filtri e i 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 in quali giorni sono disponibili 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.
Per chiamare questo metodo, vedi l'esempio Python.
L'API è vincolata 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 relativi alla quantità di dati disponibili.
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"] }
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à 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, in formato AAAA-MM-GG, nel formato 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 superiore 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 risultato. 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 eseguire il raggruppamento, ma non puoi eseguire il raggruppamento in base alla stessa dimensione due volte. Esempio: [paese, dispositivo] | |
searchType |
string |
Deprecato, usa type al suo posto
|
|
type |
string |
[Facoltativo] Filtra i risultati in base al seguente tipo:
|
|
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 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:
|
|
dimensionFilterGroups[].filters[] |
list |
[Facoltativo] Zero o più filtri da testare per la 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 eseguendo il raggruppamento in base a questa dimensione.
I valori accettati sono:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Facoltativo] Il modo in cui il valore specificato deve corrispondere (o non corrispondere) al valore della dimensione della riga.
I valori accettati sono:
|
|
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à, vengono aggregati tutti i dati relativi alla stessa proprietà; se aggregati per pagina, tutti i dati vengono aggregati per URI canonico. Se filtri o raggruppi i dati per pagina, scegli la modalità automatica, altrimenti puoi aggregare i dati per proprietà o per pagina, a seconda di come vuoi che vengano calcolati i dati. Consulta la documentazione di 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 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 quello richiesto non è valido. I valori accettati sono:
|
|
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 positiva 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 i dati per dimensione Paese, verranno raggruppati tutti i risultati per "usa" e tutti i risultati per "mdv" e così via. Se hai raggruppato la ricerca per paese e dispositivo, verranno raggruppati tutti i risultati relativi a "usa, tablet", e così via. Consulta la documentazione relativa ai report Analisi delle ricerche per informazioni specifiche su come vengono calcolati i clic, le impressioni e così via e il loro significato.
I risultati sono 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 al più recente). Se c'è un legame 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 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 |
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 |
Come sono stati aggregati i risultati.Consulta la documentazione di assistenza per scoprire come i dati vengono calcolati in modo diverso per sito e pagina.
I valori accettati sono:
|
Prova.
Utilizza Explorer API di seguito per chiamare questo metodo sui dati in tempo reale e visualizzare la risposta.