Questa pagina è stata tradotta dall'API Cloud Translation.

Search Analytics: query

Esegui 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) che hai definito. Devi definire un intervallo di date di uno o più giorni.

Se la data è una delle dimensioni, tutti 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 di interesse.

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

Vedi l'esempio di 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 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à 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
`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 univoca per ogni riga dei risultati. Se non vengono specificate dimensioni, tutti i valori verranno combinati in una singola 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: [paese, dispositivo]
`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 dalla scheda "Notizie" nella Ricerca Google. "`image`": risultati di ricerca dalla scheda "Immagini" nella Ricerca Google. "`video`": risultati di ricerca video "`web`": [valore predefinito] Filtra i risultati nella scheda combinata ("Tutti") nella Ricerca Google. Non sono inclusi 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 almeno uno deve corrispondere.
`dimensionFilterGroups[].groupType`	`string`	Indica se tutti i filtri in questo gruppo devono restituire true ("and") o 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 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 li stai raggruppando in base a quella dimensione. I valori accettati sono: "`country`": applica 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 DISPOSITIVO MOBILE TABLET "`page`": applica un filtro in base alla stringa URI specificata. "`query`": applica un filtro 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 "searchAspetto".
`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 corrispondere all'espressione (senza distinzione tra maiuscole e minuscole). "`equals`": [predefinita] L'espressione deve essere esattamente uguale al valore della riga (sensibile alle maiuscole per le dimensioni di 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 corrispondere esattamente al valore della riga (sensibile alle maiuscole per le dimensioni di pagina e 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 di corrispondenza o esclusione del filtro, a seconda dell'operatore.
`aggregationType`	`string`	[Facoltativo] Come vengono aggregati i dati. Se aggregati per proprietà, vengono aggregati tutti i dati relativi alla stessa proprietà; se invece sono aggregati per pagina, tutti i dati vengono aggregati per URI canonico. Se filtri o raggruppi i dati per pagina, scegli Automatico; altrimenti, puoi aggregarli 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 i dati 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, riceverai un errore. L'API non modificherà mai il tipo di aggregazione se quello 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 `searchAppearance` `NEWS_SHOWCASE` e `type=discover` o `type=googleNews`. Se raggruppi per pagina, filtri per pagina o filtri in base a un altro `searchAppearance`, non puoi aggregare i dati 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 per la prima riga della 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 viene selezionato "tutti" (senza distinzione tra maiuscole e minuscole), i dati includeranno dati aggiornati. Se il valore è "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 una singola riga. Ad esempio, se raggruppi i dati in base alla dimensione del paese, verranno raggruppati tutti i risultati relativi a "usa" 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 relativa ai 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 in base al numero di clic, in ordine decrescente, a meno che non raggruppi i dati per data; in questo caso i risultati sono ordinati per data in ordine crescente (dal meno recente, dal più recente per ultimo). In caso di parità tra due righe, l'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
`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 in questione, raggruppati in base alle dimensioni nella richiesta, nell'ordine specificato nella richiesta stessa.
`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`	Il modo in cui sono stati aggregati i risultati.Consulta la documentazione di assistenza 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.

Usa Explorer API in basso per chiamare questo metodo sui dati in tempo reale e visualizzare la risposta.