Search Analytics: query

Richiede l'autorizzazione

Esegui query sui dati sul traffico di ricerca con filtri e parametri definiti da te. 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 sapere quali giorni sono disponibili, esegui una query senza filtri raggruppati per data per l'intervallo di date di tuo interesse.

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

Consulta l'esempio di Python per chiamare questo metodo.

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

Scopri i limiti alla quantità di dati disponibili.

Esempio di POST su 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 percorso
siteUrl string L'URL della proprietà 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, 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 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.In dimensionFilterGroups[].filters[].dimension puoi utilizzare qualsiasi nome di dimensione e "data".I valori delle dimensioni di raggruppamento vengono combinati per creare una chiave unica per ogni riga dei risultati. Se non vengono specificate dimensioni, tutti i valori verranno combinati in un'unica riga. Non c'è 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, usa invece type
type string [Facoltativo] Filtra i risultati in base al seguente tipo:
  • "discover": risultati di Discover
  • "googleNews": risultati di news.google.com e dell'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": i risultati di ricerca della scheda "Immagini" nella Ricerca Google.
  • "video": risultati di ricerca video
  • "web": [Predefinito] Filtra i risultati nella 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. 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 in questo gruppo devono restituire true ("e") o se uno o più devono restituire true (non ancora supportato).

I valori accettati sono:
  • "and": tutti i filtri nel gruppo devono restituire true per il gruppo di filtri per essere true.
dimensionFilterGroups[].filters[] list [Facoltativo] Zero o più filtri da testare rispetto alla riga. Ogni filtro è costituito da un nome della 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 li stai raggruppando in base a quella dimensione.

I valori accettati sono:
  • "country": filtra in base al paese specificato, come specificato dal codice paese a tre lettere (ISO 3166-1 alpha-3).
  • "device": filtra i risultati in base al tipo di dispositivo specificato. Valori supportati:
    • DESKTOP
    • DISPOSITIVO 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à dei risultati di ricerca specifica. 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] La modalità di corrispondenza (o mancata corrispondenza) del valore specificato con il valore della dimensione per la riga.

I valori accettati sono:
  • "contains": il valore della riga deve contenere o essere uguale all'espressione (non è sensibile alle maiuscole).
  • "equals": [Valore 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 (non sensibile alle maiuscole).
  • "notEquals": l'espressione non deve corrispondere esattamente al valore della riga (sensibile alle maiuscole 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 associare o escludere dal filtro, a seconda dell'operatore.
aggregationType string

[Facoltativo] Come vengono aggregati i dati. Se aggregati per proprietà, tutti i dati per la stessa proprietà vengono aggregati; se aggregati per pagina, tutti i dati vengono aggregati per URI canonico. Se filtri o raggruppi per pagina, scegli Automatico. In caso contrario, puoi aggregare i dati per proprietà o per pagina, a seconda di come vuoi che vengano calcolati. Consulta la documentazione del Centro assistenza per scoprire in che modo i dati vengono calcolati in modo diverso in base al sito o alla pagina.

Nota: se raggruppi o filtri per pagina, non puoi aggregare 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 cambierà mai il tipo di aggregazione se il tipo richiesto non è valido.

I valori accettati sono:
  • "auto": [Predefinito] Consenti al servizio di decidere il tipo di aggregazione appropriato.
  • "byNewsShowcasePanel": valori aggregati 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 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; 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 a partire da zero della prima riga della risposta. Deve essere un numero non negativo. Se startRow supera il numero di risultati della query, la risposta sarà una risposta positiva 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 completati.

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 la dimensione paese, tutti i risultati per "usa" verranno raggruppati insieme, così come tutti i risultati per "mdv" e così via. Se hai raggruppato i dati per paese e dispositivo, verranno raggruppati tutti i risultati relativi a "usa, tablet", tutti i risultati relativi a "usa, dispositivo mobile" e così via. Consulta la documentazione del report di Analisi delle ricerche per scoprire le specifiche su come vengono calcolati i clic, le impressioni e così via e il loro significato.

I risultati vengono ordinati in base al numero di clic, in ordine decrescente, a meno che non vengano raggruppati per data, nel qual caso vengono ordinati per data, in ordine crescente (prima i più vecchi, poi i più recenti). In caso di parità tra due righe, l'ordine di ordinamento è arbitrario.

Consulta 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 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 (incluso).
rows[].position double Posizione media nei risultati di ricerca.
responseAggregationType string Come sono stati aggregati i 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 accettati sono:
  • "auto"
  • "byPage": i risultati sono stati aggregati per pagina.
  • "byProperty": i risultati sono stati aggregati per proprietà.

Prova

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