Richiede autorizzazione
Esegui una 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 hanno 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 conteggio dei clic, vengono ordinate in modo arbitrario.
Consulta l'esempio di Python per chiamare questo metodo.
L'API è vincolata dalle limitazioni interne di Search Console e non garantisce la restituzione di tutte le righe di dati, ma solo di quelle principali.
Consulta i limiti della 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 parametro | Valore | Descrizione |
|---|---|---|
| Parametri del percorso | ||
siteUrl |
string |
L'URL della proprietà come definita 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, 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é "date" e "hour". 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 una singola 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 invece
|
|
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 se deve corrispondere almeno uno. | |
dimensionFilterGroups[].groupType |
string |
Indica se tutti i filtri in questo gruppo devono restituire true ("and") o se uno o più devono restituire true (non ancora supportato).
I valori accettabili sono:
|
|
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 accettabili sono:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Facoltativo] Indica se il valore specificato deve corrispondere (o non corrispondere) al valore della dimensione per la riga.
I valori accettabili sono:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Il valore del filtro da includere o escludere, a seconda dell'operatore. | |
aggregationType |
string |
[Facoltativo] Modalità di aggregazione dei dati. Se i dati vengono aggregati per proprietà, vengono aggregati tutti i dati per la stessa proprietà; se vengono aggregati per pagina, vengono aggregati tutti i dati per URI canonico. Se filtri o raggruppi per pagina, scegli auto; in caso contrario, puoi aggregare per proprietà o per 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 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:
|
|
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; 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 "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 raggruppa 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 di dimensione verranno raggruppati in una singola 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 "usa, tablet" verranno raggruppati, tutti i risultati per "usa, mobile" verranno raggruppati e così via. Consulta la documentazione del report Analisi delle ricerche 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 raggruppi per data, nel qual caso i risultati vengono ordinati per data, in ordine crescente (prima i più vecchi, poi i più recenti). 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 indicato nella query. | |
rows[].keys[] |
list |
Un elenco dei valori delle dimensioni per la 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 vanno da 0 a 1,0, inclusi. | |
rows[].position |
double |
Posizione media nei risultati di ricerca. | |
responseAggregationType |
string |
Modalità di aggregazione dei risultati.Consulta la documentazione di assistenza per scoprire in che modo i dati vengono calcolati in modo diverso per sito e per pagina.
I valori accettabili sono:
|
|
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 Tutte le date e gli orari forniti in questo oggetto sono nel Il campo specifico restituito all'interno di questo oggetto dipende da come hai raggruppato i dati in the request:
|
Prova
Utilizza l'Explorer API di seguito per chiamare questo metodo sui dati live e visualizzare la risposta.