Questo documento spiega come utilizzare l'API Core Reporting per accedere ai dati di Google Analytics.
Introduzione
L'API Core Reporting fornisce l'accesso ai dati tabulari nei report standard e personalizzati di Google Analytics. Per accedere ai dati, crea una query che specifichi la vista (profilo), le date di inizio e di fine, le dimensioni e le metriche che costituiscono le intestazioni di colonna nella tabella. Questa query viene inviata all'API di reporting principale e quest'ultima restituisce tutti i dati sotto forma di tabella.
Se non hai mai utilizzato l'API, leggi la Panoramica dell'API di reporting principale per saperne di più sullo scopo e sui dati che fornisce.
Prima di iniziare
Questa guida illustra come accedere all'API Google Analytics utilizzando i linguaggi di programmazione Java, Python, PHP e JavaScript.
- Leggi la pagina relativa alle librerie client per un elenco completo delle librerie client specifiche dei linguaggi di programmazione che funzionano con l'API.
- Leggi la guida di riferimento per accedere all'API senza una libreria client.
Ogni libreria client fornisce un singolo oggetto del servizio di analisi per accedere a tutti i dati dell'API Core Reporting. Per creare l'oggetto di servizio, in genere devi seguire questi passaggi:
- Registra la tua applicazione nella console API di Google.
- Autorizza l'accesso ai dati di Google Analytics.
- Creare un oggetto di servizio Analytics.
Se non hai completato questi passaggi, interrompi e leggi il tutorial sull'API Hello Google Analytics. Questo tutorial illustra i passaggi iniziali della creazione di un'applicazione API di Google Analytics. Al termine, potrai utilizzare questa guida per eseguire attività reali.
Il seguente snippet di codice contiene una variabile per archiviare un oggetto di servizio autorizzato.
Java
Analytics analytics = // Read Hello Analytics Tutorial for details.
Python
analytics = # Read Hello Analytics Tutorial for details.
PHP
$client = // Read Hello Analytics Tutorial for details. // Return results as objects. $client->setUseObjects(true); $analytics = new apiAnalyticsService($client);
La libreria PHP restituirà tutti i risultati dell'API sotto forma di array associativo. Per restituire invece oggetti
reali, puoi chiamare il metodo useObject del client
come mostrato nell'esempio precedente.
JavaScript
<script src="https://apis.google.com/js/client.js?onload=loadLib"</script>
<script>
function loadLib() {
// Handle all the authorization work.
// Read Hello Analytics Tutorial for details.
gapi.client.load('analytics', 'v3', makeApiCall);
}
</script>
Il primo tag script carica la libreria JavaScript dell'API di Google. Una volta
caricato, viene eseguito loadLib per caricare la classe del servizio di analisi.
Al termine, l'oggetto gapi.client.analytics dovrebbe esistere
nel DOM ed essere pronto per essere utilizzato per eseguire query sull'API di reporting principale.
Dopo aver creato un oggetto del servizio di analisi, puoi effettuare richieste all'API Core Reporting.
Nota: l'oggetto del servizio di analisi può essere utilizzato anche per accedere all'API di gestione.
Panoramica
In genere, un'applicazione che utilizza l'API di reporting principale prevede due passaggi:
- Esegui una query sull'API Core Reporting
- Utilizza i risultati dell'API
Esaminiamo entrambi i passaggi.
Esegui una query sull'API Core Reporting
Creare una query dell'API Core Reporting
L'oggetto del servizio di analisi contiene un metodo per creare una query dell'API Core Reporting.
Ogni query dell'API Core Reporting contiene un insieme di parametri che specificano quali dati restituire.Uno dei parametri di query più importanti è il parametro ids
o l'ID tabella. Questo parametro specifica la vista (profilo) Google Analytics da cui recuperare i dati. Il valore è nel formato
ga:xxx, dove xxx è l'ID vista (profilo).
Java
Get apiQuery = analytics.data().ga()
.get(tableId, // Table Id.
"2012-01-01", // Start date.
"2012-01-15", // End date.
"ga:sessions") // Metrics.
.setDimensions("ga:source,ga:keyword")
.setSort("-ga:sessions,ga:source")
.setFilters("ga:medium==organic")
.setMaxResults(25);
Python
api_query = service.data().ga().get(
ids=TABLE_ID,
start_date='2012-01-01',
end_date='2012-01-15',
metrics='ga:sessions',
dimensions='ga:source,ga:keyword',
sort='-ga:sessions,ga:source',
filters='ga:medium==organic',
max_results='25')
PHP
private function queryCoreReportingApi() {
$optParams = array(
'dimensions' => 'ga:source,ga:keyword',
'sort' => '-ga:sessions,ga:source',
'filters' => 'ga:medium==organic',
'max-results' => '25');
return $service->data_ga->get(
TABLE_ID,
'2010-01-01',
'2010-01-15',
'ga:sessions',
$optParams);
}
In questa libreria, il metodo get non solo crea una query dell'API Core Reporting,
ma esegue anche la richiesta all'API.
JavaScript
function makeApiCall() {
var apiQuery = gapi.client.analytics.data.ga.get({
'ids': TABLE_ID,
'start-date': '2010-01-01',
'end-date': '2010-01-15',
'metrics': 'ga:sessions',
'dimensions': 'ga:source,ga:keyword',
'sort': '-ga:sessions,ga:source',
'filters': 'ga:medium==organic',
'max-results': 25
});
// ...
}
In questo esempio, la funzione makeApiCall viene richiamata dopo il caricamento della libreria client JavaScript. All'interno, la funzione crea una nuova
query dell'API Google Analytics e archivia l'oggetto nella
variabile apiQuery.
Un elenco completo di tutti i parametri di query e delle loro funzioni è disponibile nella guida di riferimento dell'API di reporting principale. Inoltre, i parametri di dimensioni e metriche ti consentono di specificare quali dati recuperare da Google Analytics. Puoi trovare un elenco completo nella pagina di riferimento relativa a dimensioni e metriche.
Effettuare una richiesta di dati dell'API Core Reporting
Dopo aver definito una query, ne chiami il metodo execute
per inviarla ai server di Google Analytics.
Java
try {
apiQuery.execute();
// Success. Do something cool!
} catch (GoogleJsonResponseException e) {
// Catch API specific errors.
handleApiError(e);
} catch (IOException e) {
// Catch general parsing network errors.
e.printStackTrace();
}
Se preferisci accedere alla risposta dell'API non elaborata, utilizza il metodo executeUnparsed():
HttpResponse response = apiQuery.executeUnparsed();
Python
try:
results = get_api_query(service).execute()
print_results(results)
except TypeError, error:
# Handle errors in constructing a query.
print ('There was an error in constructing your query : %s' % error)
except HttpError, error:
# Handle API service errors.
print ('There was an API error : %s : %s' %
(error.resp.status, error._get_reason()))
PHP
try {
$results = queryCoreReportingApi();
// Success. Do something cool!
} catch (apiServiceException $e) {
// Handle API service exceptions.
$error = $e->getMessage();
}
JavaScript
function makeApiCall() {
// ...
apiQuery.execute(handleCoreReportingResults);
}
function handleCoreReportingResults(results) {
if (!results.error) {
// Success. Do something cool!
} else {
alert('There was an error: ' + results.message);
}
}
Questo esempio segue il passaggio precedente in cui è stata creata una query dell'API Core Reporting. In questo passaggio, viene eseguita la query.
Il parametro del metodo execute è un riferimento a una funzione di callback che viene eseguita una volta restituiti i dati dall'API.
Quando l'API restituisce i risultati, la funzione di callback viene eseguita e i dati vengono passati dall'API. Se si verifica un errore, i risultati conterranno una proprietà denominata error.
In questo esempio, viene eseguito un controllo per verificare se error esiste o se l'API è stata restituita correttamente.
Se la query ha esito positivo, l'API restituirà i dati richiesti. Se si verificano errori, l'API restituirà un codice di stato specifico e un messaggio che descrive l'errore. Tutte le applicazioni devono rilevare e gestire correttamente gli errori.
Utilizzo dei risultati dell'API
Se la query dell'API Core Reporting ha esito positivo, l'API restituisce i dati dei report di Analytics e altre informazioni correlate sui dati.
Dati dei report di Analytics
I dati principali restituiti dall'API possono essere considerati come una tabella con 2 tipi principali di dati:
- L'intestazione che descrive i tipi di valori in ogni colonna
- Le righe di dati nella tabella
Dati dell'intestazione di colonna
Ogni risposta dell'API contiene un campo di intestazione di colonna che rappresenta le informazioni di intestazione della tabella. Il campo è un elenco (o un array) di oggetti in cui ciascun oggetto descrive il tipo di dati nella colonna. L'ordine delle colonne corrisponde alle colonne delle dimensioni seguite dalle colonne delle metriche nello stesso ordine specificato nella query originale.
Java
private void printColumnHeaders(GaData gaData) {
System.out.println("Column Headers:");
for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
System.out.println("Column Name: " + header.getName());
System.out.println("Column Type: " + header.getColumnType());
System.out.println("Column Data Type: " + header.getDataType());
}
}
Python
def print_column_headers():
headers = results.get('columnHeaders')
for header in headers:
# Print Dimension or Metric name.
print 'Column name = %s' % header.get('name'))
print 'Column Type = %s' % header.get('columnType')
print 'Column Data Type = %s' % header.get('dataType')
PHP
private function printColumnHeaders(&results) {
$html = '';
$headers = $results->getColumnHeaders();
foreach ($headers as $header) {
$html .= <<<HTML
Column Name = {$header->getName()}
Column Type = {$header->getColumnType()}
Column Data Type = {$header->getDataType()}
HTML;
print $html;
}
JavaScript
function printColumnHeaders(results) {
var output = [];
for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
output.push(
'Name = ', header.name, '\n',
'Column Type = ', header.columnType, '\n',
'Data Type = ', header.dataType, '\n'
);
}
alert(output.join(''));
}
Dati riga
I dati principali restituiti dall'API vengono restituiti come List di stringhe bidimensionali. L'elenco esterno rappresenta tutte le righe di dati.
Ogni elenco interno rappresenta una singola riga, in cui l'ordine delle celle di una riga
corrisponde a quello dei campi nell'oggetto intestazione di colonna descritto sopra.
Poiché i dati di ogni cella vengono restituiti come stringa, il campo DataType in ogni oggetto di intestazione di colonna è particolarmente utile poiché può essere utilizzato per analizzare i valori stringa in un tipo appropriato. Consulta la
risposta dell'API metadata per tutti i possibili tipi di dati.
Negli esempi riportati di seguito vengono stampate sia le intestazioni sia le righe della tabella.
Java
private void printDataTable(GaData gaData) {
if (gaData.getTotalResults() > 0) {
System.out.println("Data Table:");
// Print the column names.
for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
System.out.format("%-32s", header.getName() + '(' + header.getDataType() + ')');
}
System.out.println();
// Print the rows of data.
for (List<String> rowValues : gaData.getRows()) {
for (String value : rowValues) {
System.out.format("%-32s", value);
}
System.out.println();
}
} else {
System.out.println("No Results Found");
}
Python
def print_data_table(results):
# Print headers.
output = []
for header in results.get('columnHeaders'):
output.append('%30s' % header.get('name'))
print ''.join(output)
# Print rows.
if results.get('rows', []):
for row in results.get('rows'):
output = []
for cell in row:
output.append('%30s' % cell)
print ''.join(output)
else:
print 'No Results Found'
PHP
private function printDataTable(&$results) {
if (count($results->getRows()) > 0) {
$table .= '<table>';
// Print headers.
$table .= '<tr>';
foreach ($results->getColumnHeaders() as $header) {
$table .= '<th>' . $header->name . '</th>';
}
$table .= '</tr>';
// Print table rows.
foreach ($results->getRows() as $row) {
$table .= '<tr>';
foreach ($row as $cell) {
$table .= '<td>'
. htmlspecialchars($cell, ENT_NOQUOTES)
. '</td>';
}
$table .= '</tr>';
}
$table .= '</table>';
} else {
$table .= '<p>No Results Found.</p>';
}
print $table;
}
JavaScript
function printRows(results) {
output = [];
if (results.rows && results.rows.length) {
var table = ['<table>'];
// Put headers in table.
table.push('<tr>');
for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
table.push('<th>', header.name, '</th>');
}
table.push('</tr>');
// Put cells in table.
for (var i = 0, row; row = results.rows[i]; ++i) {
table.push('<tr><td>', row.join('</td><td>'), '</td></tr>');
}
table.push('</table>');
output.push(table.join(''));
} else {
output.push('<p>No Results Found</p>');
}
alert(output.join(''));
}
Informazioni sulla segnalazione
Insieme ai dati della tabella principale, i dati restituiti dall'API contengono alcune informazioni generali sulla risposta. Puoi stamparla utilizzando:
Java
private void printResponseInfo(GaData gaData) {
System.out.println("Contains Sampled Data: " + gaData.getContainsSampledData());
System.out.println("Kind: " + gaData.getKind());
System.out.println("ID:" + gaData.getId());
System.out.println("Self link: " + gaData.getSelfLink());
}
Python
def print_response_info(results):
print 'Contains Sampled Data = %s' % results.get('containsSampledData')
print 'Kind = %s' % results.get('kind')
print 'ID = %s' % results.get('id')
print 'Self Link = %s' % results.get('selfLink')
PHP
private function printReportInfo(&$results) {
$html = <<<HTML
<pre>
Contains Sampled Data = {$results->getContainsSampledData()}
Kind = {$results->getKind()}
ID = {$results->getId()}
Self Link = {$results->getSelfLink()}
</pre>
HTML;
print $html;
}
JavaScript
function printReportInfo(results) {
var output = [];
output.push(
'Contains Sampled Data = ', results.containsSampledData, '\n',
'Kind = ', results.kind, '\n',
'ID = ', results.id, '\n',
'Self Link = ', results.selfLink, '\n');
alert(output.join(''));
}
Il campo containsSampledData è importante perché descrive se la risposta dell'API è stata campionata.
Il campionamento può influire sui risultati dei dati e un motivo comune per cui i valori restituiti dall'API non corrispondono all'interfaccia web. Per ulteriori dettagli, consulta la guida concettuale sul campionamento.
Visualizzare le informazioni (profilo)
Ogni risposta contiene un gruppo di parametri che indicano l'account, la proprietà web e la vista (profilo) a cui appartengono i dati.
Java
private void printProfileInfo(GaData gaData) {
GaDataProfileInfo profileInfo = gaData.getProfileInfo();
System.out.println("Account ID: " + profileInfo.getAccountId());
System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
System.out.println("Table ID: " + profileInfo.getTableId());
}
Python
def print_profile_info(result):
info = results.get('profileInfo')
print 'Account Id = %s' % info.get('accountId')
print 'Web Property Id = %s' % info.get('webPropertyId')
print 'Web Property Id = %s' % info.get('internalWebPropertyId')
print 'View (Profile) Id = %s' % info.get('profileId')
print 'Table Id = %s' % info.get('tableId')
print 'View (Profile) Name = %s' % info.get('profileName')
PHP
private function printProfileInformation(&$results) {
$profileInfo = $results->getProfileInfo();
$html = <<<HTML
<pre>
Account ID = {$profileInfo->getAccountId()}
Web Property ID = {$profileInfo->getWebPropertyId()}
Internal Web Property ID = {$profileInfo->getInternalWebPropertyId()}
Profile ID = {$profileInfo->getProfileId()}
Table ID = {$profileInfo->getTableId()}
Profile Name = {$profileInfo->getProfileName()}
</pre>
HTML;
print $html;
}
JavaScript
function printProfileInfo(results) {
var output = [];
var info = results.profileInfo;
output.push(
'Account Id = ', info.accountId, '\n',
'Web Property Id = ', info.webPropertyId, '\n',
'View (Profile) Id = ', info.profileId, '\n',
'Table Id = ', info.tableId, '\n',
'View (Profile) Name = ', info.profileName);
alert(output.join(''));
}
Ciascuno di questi ID corrisponde a varie entità nella gerarchia dell'API di gestione. Puoi utilizzare questi ID per creare query dell'API di gestione al fine di ottenere ulteriori informazioni di configurazione sulla vista (profilo). Ad esempio, puoi eseguire query sulla raccolta di obiettivi dell'API di gestione per vedere quali obiettivi sono attivi e i nomi degli obiettivi configurati.
Informazioni sulla query
Ogni risposta dell'API Core Reporting contiene un oggetto che contiene tutti i valori dei parametri di query utilizzati per creare la risposta.
Java
private void printQueryInfo(GaData gaData) {
GaDataQuery query = gaData.getQuery();
System.out.println("Ids: " + query.getIds());
System.out.println("Start Date: " + query.getStartDate());
System.out.println("End Date: " + query.getEndDate());
System.out.println("Metrics: " + query.getMetrics()); // List
System.out.println("Dimensions: " + query.getDimensions());
System.out.println("Sort: " + query.getSort()); // List
System.out.println("Segment: " + query.getSegment());
System.out.println("Filters: " + query.getFilters());
System.out.println("Start Index: " + query.getStartIndex());
System.out.println("Max Results: " + query.getMaxResults());
}
Python
def print_query_info(results):
query = results.get('query')
for key, value in query.iteritems():
print '%s = %s' % (key, value)
PHP
private function printQueryParameters(&$results) {
$query = $results->getQuery();
$html = '<pre>';
foreach ($query as $paramName => $value) {
$html .= "$paramName = $value\n";
}
$html .= '</pre>';
print $html;
}
JavaScript
function printQuery(results) {
output = [];
for (var key in results.query) {
output.push(key, ' = ', results.query[key], '\n');
}
alert(output.join(''));
}
I parametri metrics e sort
vengono restituiti come valori in un elenco, mentre gli altri
parametri vengono restituiti come stringhe.
Informazioni sull'impaginazione
Qualsiasi richiesta dell'API di reporting principale potrebbe corrispondere a centinaia di migliaia di righe di dati di Google Analytics. L'API di reporting principale restituisce solo un sottoinsieme in un determinato momento, definendolo come una singola pagina di dati. Puoi utilizzare i campi di impaginazione per recuperare tutte le pagine di dati.
Java
private void printPaginationInfo(GaData gaData) {
System.out.println("Items Per Page: " + gaData.getItemsPerPage());
System.out.println("Total Results: " + gaData.getTotalResults());
System.out.println("Previous Link: " + gaData.getPreviousLink());
System.out.println("Next Link: " + gaData.getNextLink());
}
Python
def print_pagination_info(results):
print 'Items per page = %s' % results.get('itemsPerPage')
print 'Total Results = %s' % results.get('totalResults')
print 'Previous Link = %s' % results.get('previousLink')
print 'Next Link = %s' % results.get('nextLink')
PHP
private function getPaginationInfo(&$results) {
$html = <<<HTML
<pre>
Items per page = {$results->getItemsPerPage()}
Total results = {$results->getTotalResults()}
Previous Link = {$results->getPreviousLink()}
Next Link = {$results->getNextLink()}
</pre>
HTML;
print $html;
}
JavaScript
function printPaginationInfo(results) {
var output = [];
output.push(
'Items Per Page = ', results.itemsPerPage, '\n',
'Total Results = ', results.totalResults, '\n',
'Previous Link = ', results.previousLink, '\n',
'Next Link = ', results.nextLink, '\n');
alert(output.join(''));
}
Il campo totalResults rappresenta il numero totale di
righe di dati corrispondenti alla query in Google Analytics. Può essere maggiore del numero effettivo di righe restituite in una singola pagina della risposta.
Il campo itemsPerPage rappresenta il numero di righe restituite in questa pagina.
I parametri previousLink e nextLink sono presenti solo se esiste una pagina precedente o successiva. Controlla questi
link per verificare se è possibile recuperare altre pagine di dati
dall'API di reporting principale.
Totali per tutti i risultati
Come menzionato nella sezione delle informazioni sulla paginazione sopra, una query all'API di reporting principale può corrispondere a molte righe di dati in Google Analytics, ma restituire solo un sottoinsieme di dati.
I valori totali delle metriche per tutte le righe corrispondenti vengono restituiti nell'oggetto totalsForAllResults.
Questi dati sono utili per il calcolo delle medie.
Java
private void printTotalsForAllResults(GaData gaData) {
Map totalsMap = gaData.getTotalsForAllResults();
for (Map.Entry entry : totalsMap.entrySet()) {
System.out.println(entry.getKey() + " : " + entry.getValue());
}
}
Python
def print_totals_for_all_results(results):
totals = results.get('totalsForAllResults')
for metric_name, metric_total in totals.iteritems():
print 'Metric Name = %s' % metric_name
print 'Metric Total = %s' % metric_total
PHP
private function printTotalsForAllResults(&$results) {
$totals = $results->getTotalsForAllResults();
foreach ($totals as $metricName => $metricTotal) {
$html .= "Metric Name = $metricName\n";
$html .= "Metric Total = $metricTotal";
}
print $html;
}
JavaScript
function printTotalsForAllResults(results) {
var output = [];
var totals = results.totalsForAllResults;
for (metricName in totals) {
output.push(
'Metric Name = ', metricName, '\n',
'Metric Total = ', totals[metricName], '\n');
}
alert(output.join(''));
}
Campioni funzionanti
Per visualizzare gli esempi completi di funzionamento, controlla l'esempio di API di reporting principale nella directory di esempio di ogni libreria client.
Java
Libreria client Java dell'API di Google Esempio di API di reporting principale
Python
Libreria client Python dell'API Google Esempio di API di reporting principale
PHP
Libreria client PHP dell'API di Google Esempio di API di reporting principale
JavaScript
Libreria client JavaScript dell'API Google Esempio di API di reporting principale