Ce document explique comment utiliser l'API Core Reporting pour accéder aux données Google Analytics.
Introduction
L'API Core Reporting permet d'accéder aux données tabulaires des rapports standards et personnalisés de Google Analytics. Pour accéder aux données, vous devez créer une requête qui spécifie la vue (profil), les dates de début et de fin, ainsi que les dimensions et les métriques qui composent les en-têtes de colonne du tableau. Cette requête est envoyée à l'API Core Reporting, qui renvoie toutes les données sous forme de tableau.
Si vous débutez avec l'API Core Reporting, lisez la présentation de l'API Core Reporting pour découvrir l'objectif de cette API et les données qu'elle fournit.
Avant de commencer
Ce guide explique comment accéder à l'API Google Analytics à l'aide des langages de programmation Java, Python, PHP et JavaScript.
- Consultez la page Bibliothèques clientes pour obtenir la liste complète des bibliothèques clientes spécifiques au langage de programmation qui fonctionnent avec l'API.
- Lisez le guide de référence pour accéder à l'API sans bibliothèque cliente.
Chaque bibliothèque cliente fournit un seul objet de service d'analyse permettant d'accéder à toutes les données de l'API Core Reporting. Pour créer l'objet de service, vous devez généralement procéder comme suit:
- Enregistrez votre application dans la console Google APIs.
- Autorisez l'accès aux données Google Analytics.
- Créez un objet de service Analytics.
Si vous n'avez pas effectué ces étapes, veuillez vous arrêter et lire le tutoriel sur l'API Hello Google Analytics. Ce tutoriel vous guide à travers les premières étapes de la création d'une application API Google Analytics. Une fois l'opération terminée, vous pourrez utiliser ce guide pour effectuer des tâches réelles.
L'extrait de code suivant contient une variable permettant de stocker un objet de service autorisé.
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 bibliothèque PHP renvoie tous les résultats de l'API sous forme de tableau associatif. Pour renvoyer des objets réels, vous pouvez appeler la méthode useObject
du client comme illustré dans l'exemple ci-dessus.
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>
Le premier tag de script charge la bibliothèque JavaScript de l'API Google. Une fois chargé, loadLib
est exécuté pour charger la classe de service d'analyse.
Une fois l'opération terminée, l'objet gapi.client.analytics
doit exister dans le DOM et être prêt à être utilisé pour interroger l'API Core Reporting.
Une fois que vous avez créé un objet de service d'analyse, vous pouvez envoyer des requêtes à l'API Core Reporting.
Remarque: L'objet de service d'analyse peut également être utilisé pour accéder à l'API Management.
Présentation
Une application qui utilise l'API Core Reporting comporte généralement deux étapes:
- Interroger l'API Core Reporting
- Exploiter les résultats de l'API
Examinons les deux étapes.
Interroger l'API Core Reporting
Créer une requête d'API Core Reporting
L'objet de service d'analyse contient une méthode permettant de créer une requête de l'API Core Reporting.
Chaque requête de l'API Core Reporting contient un ensemble de paramètres spécifiant les données à renvoyer.L'un des paramètres de requête les plus importants est le paramètre ids
, ou ID de table. Ce paramètre spécifie la vue Google Analytics (profil) à partir de laquelle les données doivent être récupérées. La valeur est au format ga:xxx
, où xxx
correspond à l'ID de la vue (profil).
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); }
Dans cette bibliothèque, la méthode get
crée non seulement une requête de l'API Core Reporting, mais l'exécute également.
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 }); // ... }
Dans cet exemple, la fonction makeApiCall
est appelée une fois la bibliothèque cliente JavaScript chargée. À l'intérieur, la fonction crée une requête API Google Analytics et stocke l'objet dans la variable apiQuery
.
La liste complète des paramètres de requête et de leur fonction est disponible dans le guide de référence de l'API Core Reporting. En outre, les paramètres de dimension et de métrique vous permettent de spécifier les données à récupérer à partir de Google Analytics. Une liste complète est disponible sur la page de référence Dimensions et métriques.
Envoyer une requête de données à l'API Core Reporting
Une fois qu'une requête est définie, vous appelez sa méthode execute
pour l'envoyer aux serveurs 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(); }
Si vous préférez accéder à la réponse de l'API brute, utilisez la méthode 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); } }
Cet exemple fait suite à l'étape précédente, où une requête de l'API Core Reporting a été créée. Au cours de cette étape, la requête est exécutée.
Le paramètre de la méthode execute
est une référence à une fonction de rappel qui sera exécutée une fois les données renvoyées par l'API.
Une fois que l'API a renvoyé les résultats, la fonction de rappel est exécutée et reçoit les données de l'API. Si une erreur se produit, les résultats contiennent une propriété nommée error
.
Dans cet exemple, une vérification est effectuée pour voir si error
existe ou si l'API a bien été renvoyée.
Si la requête a abouti, l'API renvoie les données demandées. En cas d'erreur, l'API renvoie un code d'état spécifique et un message décrivant l'erreur. Toutes les applications doivent détecter et gérer correctement les erreurs.
Utiliser les résultats de l'API
Si la requête de l'API Core Reporting a abouti, l'API renvoie les données de rapport Analytics ainsi que d'autres informations associées sur les données.
Données de rapport Analytics
Les principales données renvoyées par l'API peuvent être considérées comme un tableau comportant deux principaux types de données:
- En-tête qui décrit les types de valeurs dans chaque colonne
- Les lignes de données du tableau
Données d'en-tête de colonne
Chaque réponse de l'API contient un champ d'en-tête de colonne qui représente les informations d'en-tête de la table. Le champ est une liste (ou un tableau) d'objets, dans laquelle chaque objet décrit le type de données de la colonne. L'ordre des colonnes correspond aux colonnes de dimensions suivies des colonnes de métriques dans le même ordre que celui spécifié dans la requête d'origine.
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('')); }
Données de ligne
Les données principales renvoyées par l'API sont renvoyées sous la forme d'une List
bidimensionnelle de chaînes. La liste externe représente toutes les lignes de données.
Chaque liste interne représente une seule ligne, où l'ordre des cellules sur une ligne est le même que celui des champs de l'objet d'en-tête de colonne décrit ci-dessus.
Les données de chaque cellule étant renvoyées sous forme de chaîne, le champ DataType
de chaque objet d'en-tête de colonne est particulièrement utile, car il peut être utilisé pour analyser les valeurs de chaîne dans un type approprié. Consultez la
réponse de l'API Metadata pour tous les types de données possibles.
Les exemples suivants impriment les en-têtes et les lignes du tableau.
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('')); }
Informations sur le rapport
En plus des données de la table principale, les données renvoyées par l'API contiennent des informations générales sur la réponse. Vous pouvez l'imprimer à l'aide de la commande suivante:
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('')); }
Le champ containsSampledData
est important, car il indique si la réponse de l'API a été échantillonnée.
L'échantillonnage peut avoir une incidence sur les résultats de vos données et une raison courante pour laquelle les valeurs renvoyées par l'API ne correspondent pas à l'interface Web. Pour en savoir plus, consultez le guide sur le concept d'échantillonnage.
Afficher les informations (profil)
Chaque réponse contient un groupe de paramètres qui indiquent le compte, le site Web et la vue (profil) auxquels ces données appartiennent.
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('')); }
Chacun de ces identifiants correspond à différentes entités dans la hiérarchie de l'API Management. Vous pouvez utiliser ces ID pour former des requêtes de l'API Management afin d'obtenir des informations de configuration supplémentaires sur la vue (profil). Par exemple, vous pouvez interroger la collection d'objectifs de l'API Management pour identifier les objectifs actifs et leur nom configuré.
Informations sur la requête
Chaque réponse de l'API Core Reporting contient un objet qui comporte toutes les valeurs de paramètre de requête utilisées pour créer la réponse.
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('')); }
Les paramètres metrics
et sort
sont renvoyés sous forme de valeurs dans une liste, tandis que les autres paramètres sont renvoyés sous forme de chaînes.
Informations sur la pagination
Toute requête de l'API Core Reporting peut correspondre à des centaines de milliers de lignes de données Google Analytics. L'API Core Reporting ne renvoie qu'un sous-ensemble à la fois, que l'on appelle une page de données unique. Vous utilisez les champs de pagination pour récupérer toutes les pages de données.
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('')); }
Le champ totalResults
représente le nombre total de lignes de données mises en correspondance dans votre requête dans Google Analytics. Cette valeur peut être supérieure au nombre réel de lignes renvoyées sur une seule page de la réponse.
Le champ itemsPerPage
représente le nombre de lignes renvoyées sur cette page.
Les paramètres previousLink
et nextLink
ne sont présents que s'il existe une page précédente ou suivante. Consultez ces liens pour voir s'il est possible de récupérer d'autres pages de données à partir de l'API Core Reporting.
Totaux pour tous les résultats
Comme indiqué dans la section sur les informations de pagination ci-dessus, une requête envoyée à l'API Core Reporting peut mettre en correspondance de nombreuses lignes de données dans Google Analytics, mais ne renverra qu'un sous-ensemble de données.
Les valeurs totales des métriques pour toutes les lignes correspondantes sont renvoyées dans l'objet totalsForAllResults
.
Ces données sont utiles pour calculer des moyennes.
Java
private void printTotalsForAllResults(GaData gaData) { MaptotalsMap = 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('')); }
Exemples de travail
Pour voir tous les exemples de travail, consultez l'exemple d'API Core Reporting dans le répertoire d'exemples de chaque bibliothèque cliente.
Java
Bibliothèque cliente Java des API Google Exemple d'API Core Reporting
Python
Bibliothèque cliente des API Google pour Python Exemple d'API Core Reporting
PHP
Bibliothèque cliente des API Google pour PHP Exemple d'API Core Reporting
JavaScript
Bibliothèque cliente JavaScript des API Google Exemple d'API Core Reporting