En este documento, se explica cómo usar la API de Core Reporting para acceder a los datos de Google Analytics.
Introducción
La API de Core Reporting proporciona acceso a los datos tabulares en los informes estándares y personalizados de Google Analytics. Para acceder a los datos, crea una consulta que especifique la vista (perfil), las fechas de inicio y finalización y las dimensiones y métricas que conforman los encabezados de columna en la tabla. Esta consulta se envía a la API de Core Reporting, y esta API muestra todos los datos en forma de tabla.
Si es la primera vez que usas la API, lee la Descripción general de la API de Core Reporting para obtener una introducción a la finalidad de la API de Core Reporting y los datos que proporciona.
Antes de comenzar
En esta guía, se muestra cómo acceder a la API de Google Analytics con los lenguajes de programación Java, Python, PHP y JavaScript.
- Lee la página sobre bibliotecas cliente para obtener una lista completa de las bibliotecas cliente específicas de cada lenguaje de programación que funcionan con la API.
- Lee la Guía de referencia para acceder a la API sin una biblioteca cliente.
Cada biblioteca cliente proporciona un solo objeto de servicio de estadísticas para acceder a todos los datos de la API de Core Reporting. Por lo general, debes seguir estos pasos para crear el objeto de servicio:
- Registra tu aplicación en la Consola de API de Google.
- Autoriza el acceso a los datos de Google Analytics.
- Crear un objeto de servicio de Analytics
Si no completaste estos pasos, detente y lee el instructivo de la API de Hello Google Analytics. En este instructivo, se explican los pasos iniciales para compilar una aplicación de la API de Google Analytics. Una vez que se complete, podrás usar esta guía para realizar tareas del mundo real.
El siguiente fragmento de código contiene una variable para almacenar un objeto de servicio autorizado.
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 biblioteca PHP devolverá todos los resultados de la API como un arreglo asociativo. Si, por el contrario, se muestran objetos reales, puedes llamar al método useObject del cliente como se muestra en el ejemplo anterior.
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>
La primera etiqueta de la secuencia de comandos carga la biblioteca JavaScript de la API de Google. Una vez cargado, se ejecuta loadLib para cargar la clase de servicio de estadísticas.
Una vez que se complete, el objeto gapi.client.analytics debería existir en el DOM y estar listo para usarse para consultar la API de Core Reporting.
Una vez que crees un objeto de servicio de estadísticas, estarás listo para realizar solicitudes a la API de Core Reporting.
Nota: El objeto del servicio de estadísticas también se puede usar para acceder a la API de Management.
Descripción general
Por lo general, una aplicación que usa la API de Core Reporting seguirá 2 pasos:
- Consulta la API de Core Reporting
- Cómo trabajar con los resultados de la API
Analicemos ambos pasos.
Consulta la API de Core Reporting
Cómo compilar una consulta a la API de Core Reporting
El objeto del servicio de estadísticas contiene un método para crear una consulta a la API de Core Reporting.
Cada consulta de la API de Core Reporting contiene un conjunto de parámetros que especifican qué datos mostrar.Uno de los parámetros de consulta más importantes es el parámetro ids o el ID de la tabla. Este parámetro especifica desde qué vista (perfil) de Google Analytics se recuperarán los datos. El valor tiene el formato ga:xxx, en el que xxx es el ID de la vista (perfil).
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);
}
En esta biblioteca, el método get no solo crea una consulta a la API de Core Reporting, sino que también ejecuta la solicitud a la 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
});
// ...
}
En este ejemplo, se llama a la función makeApiCall una vez que se carga la biblioteca cliente de JavaScript. En él, la función crea una nueva consulta de la API de Google Analytics y almacena el objeto en la variable apiQuery.
En la guía de referencia de la API de Core Reporting, puedes encontrar una lista completa de todos los parámetros de consulta y su función. Además, los parámetros de dimensión y métrica te permiten especificar qué datos recuperar de Google Analytics. Puedes encontrar una lista completa en la página de referencia de dimensiones y métricas.
Cómo realizar una solicitud de datos a la API de Core Reporting
Una vez que definas una búsqueda, la llamarás al método execute para enviarla a los servidores de 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 prefieres acceder a la respuesta de la API sin procesar, usa el método 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);
}
}
Este ejemplo sigue del paso anterior, en el que se creó una consulta de la API de Core Reporting. En este paso, se ejecuta la consulta.
El parámetro del método execute es una referencia a una función de devolución de llamada que se ejecutará una vez que la API muestre datos.
Una vez que la API muestra resultados, se ejecuta la función de devolución de llamada y se pasan los datos de la API. Si se produce un error, los resultados contendrán una propiedad llamada error.
En este ejemplo, se realiza una verificación para ver si error existe o si la API se mostró de manera correcta.
Si la consulta fue exitosa, la API mostrará los datos solicitados. Si se produce algún error, la API mostrará un código de estado específico y un mensaje que describe el error. Todas las aplicaciones deben detectar y manejar errores de forma adecuada.
Cómo trabajar con los resultados de la API
Si la consulta de la API de Core Reporting se realizó correctamente, la API mostrará los datos de informes de Analytics, así como otra información relacionada sobre los datos.
Datos de informes de Analytics
Los datos principales que muestra la API pueden considerarse una tabla con 2 tipos principales de datos:
- El encabezado que describe los tipos de valores de cada columna
- Las filas de datos en la tabla
Datos de encabezados de columna
Cada respuesta de la API contiene un campo de encabezado de columna que representa la información de encabezado de la tabla. El campo es una lista (o un array) de objetos en la que cada objeto describe el tipo de datos de la columna. El orden de las columnas son las columnas de dimensiones seguidas de las columnas de métricas en el mismo orden que se especificó en la consulta original.
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(''));
}
Datos de la fila
Los datos principales que muestra la API se muestran como un List bidimensional de cadenas. La lista externa representa todas las filas de datos.
Cada lista interna representa una sola fila, en la que el orden de las celdas en una fila es el mismo que el de los campos en el objeto de encabezado de columna descrito anteriormente.
Dado que los datos de cada celda se muestran como una string, el campo DataType en cada objeto de encabezado de columna es particularmente útil, ya que se puede usar para analizar valores de string en un tipo adecuado. Consulta la
respuesta de la API de metadatos para conocer todos los tipos de datos posibles.
En los siguientes ejemplos, se imprimen los encabezados y las filas de la tabla.
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(''));
}
Información del informe
Junto con los datos de la tabla principal, los datos que muestra la API contienen información de alto nivel sobre la respuesta. Puedes imprimirlo con el siguiente comando:
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(''));
}
El campo containsSampledData es importante porque describe si se muestreó la respuesta de la API.
El muestreo puede afectar los resultados de tus datos y un motivo común por el que los valores que muestra la API no coinciden con la interfaz web. Consulta la guía conceptual Muestreo para obtener más detalles.
Ver información (perfil)
Cada respuesta contiene un grupo de parámetros que indican la cuenta, la propiedad web y la vista (perfil) a la que pertenecen estos datos.
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(''));
}
Cada uno de estos ID corresponde a varias entidades en la jerarquía de la API de Management. Puedes usar estos ID para formar consultas de la API de Management a fin de obtener información de configuración adicional sobre la vista (perfil). Por ejemplo, puedes consultar la colección de objetivos de la API de Management para ver qué objetivos están activos junto con los nombres de objetivos configurados.
Información de consulta
Cada respuesta de la API de Core Reporting contiene un objeto que incluye todos los valores de los parámetros de consulta que se usaron para crear la respuesta.
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(''));
}
Los parámetros metrics y sort se muestran como valores en una lista, mientras que los demás parámetros se muestran como cadenas.
Información de paginación
Cualquier solicitud a la API de Core Reporting puede coincidir con cientos de miles de filas de datos de Google Analytics. La API de Core Reporting solo mostrará un subconjunto en un momento determinado, que puede denominarse una sola página de datos. Los campos de paginación te permiten recuperar todas las páginas de datos.
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(''));
}
El campo totalResults representa la cantidad total de filas de datos con las que tu consulta coincidió en Google Analytics. Puede ser mayor que la cantidad real de filas que se muestran en una sola página de la respuesta.
El campo itemsPerPage representa la cantidad de filas que se muestran en esta página.
Los parámetros previousLink y nextLink solo están presentes si existe una página anterior o siguiente. Consulta estos vínculos para ver si se pueden recuperar más páginas de datos de la API de Core Reporting.
Totales de todos los resultados
Como se mencionó anteriormente en la sección de información sobre paginación, una consulta a la API de Core Reporting puede coincidir con muchas filas de datos en Google Analytics, pero solo puede mostrar un subconjunto de datos.
Los valores totales de la métrica para todas las filas coincidentes se muestran en el objeto totalsForAllResults.
Estos datos son útiles para calcular promedios.
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(''));
}
Muestras de trabajo
Para ver los ejemplos de trabajo completos, consulta la muestra de la API de Core Reporting en el directorio de muestra de cada biblioteca cliente.
Java
Biblioteca cliente de Java de la API de Google Ejemplo de la API de Core Reporting
Python
Biblioteca cliente de Python de la API de Google Ejemplo de la API de Core Reporting
PHP
Biblioteca cliente de PHP de la API de Google Ejemplo de la API de Core Reporting
JavaScript
Biblioteca cliente de JavaScript de la API de Google Ejemplo de la API de Core Reporting