Questa è una guida per gli sviluppatori all'API Analytics Reporting v4. Per un riferimento dettagliato dell'API, consulta la documentazione di riferimento API.
Report
L'API Analytics Reporting v4 fornisce il metodo batchGet per accedere alla risorsa Reports.
Le seguenti sezioni descrivono la struttura del corpo della richiesta per batchGet
e la struttura del corpo della risposta da batchGet
.
Corpo della richiesta
Per utilizzare l'API Analytics Reporting v4 per richiedere i dati, devi creare un oggetto ReportRequest, che abbia i seguenti requisiti minimi:
- Un ID vista valido per il campo viewId.
- Almeno una voce valida nel campo dateRanges.
- Almeno una voce valida nel campo metrics.
Per trovare un ID vista,
esegui una query sul
metodo
riepiloghi account
o utilizza
Esplora account.
Se non viene specificato un intervallo di date, l'intervallo di date predefinito è:
{"startDate": "7daysAgo", "endDate": "yesterday"}
.
Ecco un esempio di richiesta con i campi minimi obbligatori:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
Il metodo batchGet
accetta un massimo di cinque oggetti ReportRequest. Tutte le richieste devono avere gli stessi valori di
dateRange
,
viewId
,
segments
,
samplingLevel
e cohortGroup
.
Corpo della risposta
Il corpo della risposta della richiesta API è un array di oggetti Report. La struttura del report è definita nell'oggetto ColumnHeader che descrive le dimensioni, le metriche e i relativi tipi di dati nel report. I valori delle dimensioni e delle metriche sono specificati nel campo Dati.
Di seguito è riportato un esempio di risposta per la richiesta di esempio riportata sopra:
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
Metriche
Le metriche sono misurazioni quantitative; ogni richiesta richiede almeno un oggetto Metric.
Nell'esempio seguente, la metrica Sessions
viene fornita al metodo batchGet
per ottenere il numero totale di sessioni nell'intervallo di date specificato:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
Puoi utilizzare Explorer dimensioni e metriche o l'API metadati per ottenere l'elenco delle dimensioni e delle metriche disponibili.
Applicazione dei filtri
Quando invii una richiesta batchGet
, puoi chiedergli di restituire solo metriche che soddisfano criteri specifici. Per filtrare le metriche, nel corpo della richiesta specifica una o più MetricFilterClauses e in ogni MetricFilterClause
definisci uno o più MetricFilters.
In ogni MetricFilter
, specifica i valori per gli elementi seguenti:
metricName
not
operator
comparisonValue
Consenti a {metricName}
di rappresentare la metrica, {operator}
di operator
e
{comparisonValue}
di comparisonValue
. A questo punto il filtro funziona nel seguente modo:
if {metricName} {operator} {comparisonValue}
return the metric
Se specifichi true
per not
, il filtro funziona come segue:
if {metricName} {operator} {comparisonValue}
do not return the metric
Nell'esempio seguente, batchGet
restituisce solo le visualizzazioni di pagina il cui valore
è maggiore di 2:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
Espressioni
Un'espressione di metrica è un'espressione matematica che definisci su metriche esistenti; funziona come metriche calcolate dinamiche. Puoi definire un alias per rappresentare l'espressione della metrica, ad esempio:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
Ordine
Per ordinare i risultati in base a un valore di metrica:
- Fornisci il nome o l'alias tramite il campo
fieldName
. - Specifica l'ordinamento (
ASCENDING
oDESCENDING
) tramite il camposortOrder
.
Nell'esempio seguente, batchGet
restituisce le metriche ordinate prima
per sessioni e poi in base alle visualizzazioni di pagina in ordine decrescente:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
Dimensioni
Le dimensioni descrivono le caratteristiche degli utenti, delle sessioni e delle azioni eseguite.
La dimensione Città, ad esempio, descrive una caratteristica delle sessioni e
indica la città ("Parigi" o "New York") da cui ha avuto origine ogni sessione.
In una richiesta batchGet
, puoi specificare zero o più oggetti dimensione, ad esempio:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
Applicazione dei filtri
Quando invii una richiesta batchGet
, puoi chiederle di restituire solo
le dimensioni che soddisfano criteri specifici. Per filtrare le dimensioni,
nel corpo della richiesta, specifica una o più
DimensionsFilterClauses
e in ogni DimensionsFilterClause
, definisci uno o più
DimensionsFilters.
In ogni DimensionsFilters
, specifica i valori per gli elementi seguenti:
dimensionName
not
operator
expressions
caseSensitive
Consenti a {dimensionName}
di rappresentare la dimensione, {operator}
di operator
e
{expressions}
di expressions
. A questo punto il filtro funziona nel seguente modo:
if {dimensionName} {operator} {expressions}
return the dimension
Se specifichi true
per not
, il filtro funziona come segue:
if {dimensionName} {operator} {expressions}
do not return the dimension
Nell'esempio seguente, batchGet
restituisce visualizzazioni di pagina e sessioni in un browser Chrome:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
Ordine
Per ordinare i risultati in base a un valore di dimensione:
- Fornisci il nome tramite il campo
fieldName
. - Specifica l'ordinamento (
ASCENDING
oDESCENDING
) mediante il camposortOrder
.
Ad esempio, batchGet
restituisce le dimensioni
ordinate per paese e poi per browser:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
Bucket a istogrammi
Per le dimensioni con valori interi, è più facile comprenderne le caratteristiche
raggruppando i valori in intervalli. Utilizza il campo histogramBuckets
per definire gli intervalli per i bucket risultanti e specificare HISTOGRAM_BUCKET
come tipo di ordine, ad esempio:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
Più intervalli di date
La versione 4 dell'API di reporting di Google Analytics ti consente di ottenere dati relativi a più intervalli di date in una singola richiesta. Indipendentemente dal fatto che la richiesta specifichi uno o due intervalli di date, i dati vengono restituiti nell'oggetto dateRangeValue, ad esempio:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
Ordinazione delta
Se richiedi valori delle metriche in due intervalli di date, puoi ordinare i risultati in base alla differenza tra i valori della metrica negli intervalli di date, ad esempio:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
Comportamento della dimensione Data
Se richiedi una dimensione relativa alla data o all'ora, l'oggetto DateRangeValue conserverà solo i valori per le date che rientrano nei rispettivi intervalli; tutti gli altri valori non compresi negli intervalli di date specificati saranno 0
.
Ad esempio, considera una richiesta per la dimensione ga:date
e
la metrica ga:sessions
in due intervalli di date: gennaio e febbraio.
Nella risposta per i dati richiesti di gennaio, i valori di febbraio saranno 0
; nella risposta per i dati richiesti di febbraio, i valori di gennaio saranno 0
.
Report di gennaio
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
Report di febbraio
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
Segmenti
Per richiedere un sottoinsieme di dati di Analytics, utilizza i segmenti. Ad esempio, puoi definire gli utenti di un determinato paese o città in un segmento e gli utenti che visitano una parte specifica del tuo sito in un altro. I filtri restituiscono solo le righe che soddisfano una condizione, mentre i segmenti restituiscono un sottoinsieme di utenti, sessioni o eventi che soddisfano le condizioni contenenti i segmenti.
Quando effettui una richiesta con segmenti, assicurati che:
- Ogni ReportRequest all'interno di un metodo
batchGet
deve contenere definizioni di segmenti identiche. - Aggiungi
ga:segment
all'elenco delle dimensioni.
Ad esempio:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
Consulta Esempi per altri esempi di richieste con segmenti.
ID segmento
Utilizza il campo segmentId
per richiedere segmenti.
Non puoi utilizzare sia un segmentId
che un dynamicSegment
per richiedere segmenti.
Ad esempio:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
Campionamento
Il campionamento può influire sui risultati dei dati ed è un motivo comune per cui i valori restituiti dall'API non corrispondono all'interfaccia web. Utilizza il campo samplingLevel
per impostare la dimensione del campione desiderata.
- Imposta il valore su
SMALL
per una risposta rapida con una dimensione di campionamento più piccola. - imposta il valore su
LARGE
per una risposta più precisa ma più lenta. - imposta il valore su
DEFAULT
per una risposta che bilancia velocità e precisione.
Ad esempio:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
Se un report contiene dati campionati, l'API Analytics Reporting v4 restituisce i campi samplesReadCounts
e samplingSpaceSizes
.
Se i risultati non vengono campionati, questi campi non verranno definiti.
Di seguito è riportato un esempio di risposta contenente dati campionati di una richiesta con due intervalli di date. I risultati sono stati calcolati su quasi 500.000 campioni di una dimensione dello spazio di campionamento di circa 15 milioni di sessioni:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Impaginazione
L'API Analytics Reporting v4 utilizza i campi pageToken
e pageSize
per eseguire l'impaginazione dei risultati delle risposte su più pagine. Ricevi pageToken
dal parametro
nextPageToken
nella risposta alla richiesta
reports.batchGet
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Passaggio successivo
Ora che hai esaminato le nozioni di base per la creazione di un report, dai un'occhiata alle funzionalità avanzate di API v4.