En este documento se explica cómo usar la API de informes centrales para acceder a los datos de Google Analytics.
Introducción
La API de informes centrales proporciona acceso a los datos tabulares de los informes estándar y personalizados de Google Analytics. Para acceder a los datos, debes crear una consulta que especifique: la vista (perfil), las fechas de inicio y de finalización, y las dimensiones y las métricas que componen los encabezados de columna de la tabla. Esta consulta se envía a la API de informes centrales, que devuelve todos los datos con formato tabular.
Si es la primera vez que usas la API, consulta en Descripción general de la API de informes centrales una introducción a la finalidad de la API y los datos que proporciona.
Antes de empezar
En esta guía se explica cómo acceder a la API de Google Analytics mediante los lenguajes de programación Java, Python, PHP y JavaScript.
- Consulta la página de bibliotecas de cliente para obtener una lista completa de las bibliotecas de cliente de cada lenguaje de programación que funcionan con la API.
- Consulta la guía de referencia para acceder a la API sin una biblioteca de cliente.
Cada biblioteca de cliente proporciona un solo objeto de servicio analytics para acceder a todos los datos de la API de informes centrales. Por lo general, para crear el objeto de servicio tienes que realizar los pasos siguientes:
- Registrar tu aplicación en la consola de la API de Google
- Autoriza el acceso a los datos de Google Analytics.
- Crear un objeto de servicio Analytics.
Si no has completado estos pasos, no sigas y lee el tutorial de presentación de la API de Google Analytics. Con este tutorial recorrerás los pasos iniciales de la creación de una aplicación de la API de Google Analytics. Una vez completado, podrás usar esta guía para realizar tareas del mundo real.
El fragmento de código siguiente 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 una matriz asociativa. Para devolver los objetos reales, se puede llamar al método useObject de cliente, tal como se ha mostrado 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 secuencia de comandos carga la biblioteca de JavaScript de la API de Google. Una vez cargada, se ejecuta loadLib para cargar la clase de servicio analytics.
Una vez completado, el objeto gapi.client.analytics debe encontrarse en el DOM y estar preparado para usarlo a fin de consultar la API de informes centrales.
Después de crear un objeto de servicio analytics, estarás preparado para realizar consultas a la API de informes centrales.
Nota: El objeto de servicio analytics también se puede usar para acceder a la API de administración.
Descripción general
Por lo general, una aplicación que usa la API de informes centrales realiza dos pasos:
- Consultar la API de informes centrales
- Trabajar con los resultados de la API
Veamos ambos pasos.
Consultar la API de informes centrales
Crear una consulta de la API de informes centrales
El objeto de servicio analytics contiene un método para crear una consulta de la API de informes centrales.
Cada consulta de la API de informes centrales contiene un conjunto de parámetros que especifican los datos que se devolverán.Uno de los parámetros de consulta más importantes es ids, o el ID de tabla. Este parámetro especifica de qué vista (perfil) se recuperarán los datos. El valor tiene el formato ga:xxx, donde xxx es el ID de 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 de la API de informes centrales, 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 ha cargado la biblioteca de cliente JavaScript. Internamente, 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 informes centrales puedes encontrar una lista completa de todos los parámetros de consulta y lo que hace cada uno. También los parámetros de dimensiones y de métricas permiten especificar los datos que se recuperarán de Google Analytics. En la página de referencia de dimensiones y de métricas se puede encontrar una lista completa.
Realizar una solicitud de datos de la API de informes centrales
Una vez que hayas definido una consulta, llama a su 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, utiliza 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 continúa a partir del paso anterior donde se ha creado una consulta de la API de informes centrales. 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 devuelva los datos.
Cuando la API devuelve los resultados, se ejecuta la función de devolución de llamada y se pasan los datos desde la API. Si se produce un error, los resultados contienen una propiedad llamada error.
En este ejemplo se comprueba si existe la propiedad error o si la API ha devuelto los datos correctamente.
Si la consulta se ha realizado correctamente, la API devolverá los datos solicitados. Si se producen errores, la API devolverá un código de estado específico y un mensaje en el que se describe el error. Todas las aplicaciones deben interceptar y gestionar correctamente los errores.
Trabajar con los resultados de la API
Si la consulta de la API de informes centrales se ha realizado correctamente, la API devuelve los datos de informe, así como otra información relacionada con los datos.
Datos de informe de Analytics
Los datos principales que se devuelven de la API se pueden considerar como una tabla con dos tipos principales de datos:
- El encabezado que describe los tipos de valores de cada columna
- Las filas de datos de la tabla
Datos de encabezado 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 una matriz) de objetos donde cada uno describe el tipo de datos de la columna. El orden de las columnas es el de columnas de dimensiones seguidas de las columnas de métricas en el mismo orden especificado 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 filas
Los datos principales que se devuelven de la API es una lista (List) bidimensional de cadenas. La lista exterior representa todas las filas de datos.
Cada lista interior representa una sola fila, donde el orden de las celdas de una fila es el mismo que los campos del objeto de encabezado de columna descrito antes.
Debido a que los datos de cada celda se devuelven como una cadena, el campo DataType de cada objeto de encabezado de columna resulta muy útil ya que se puede usar para analizar los valores de cadena en su tipo adecuado. Consulta la
respuesta de la API de metadatos para conocer todos los tipos de datos posibles.
Con los ejemplos siguientes 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(''));
}
Datos del informe
Junto con los datos de tabla principales, la API devuelve información general sobre la respuesta. Puedes imprimirla usando:
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 ha muestreado la respuesta de la API.
El muestreo puede afectar a los resultados de los datos y un motivo habitual por el que los valores que devuelve la API no coinciden con la interfaz web. Consulta la guía conceptual Muestreo para obtener más información.
Información de vista (perfil)
Cada respuesta contiene un grupo de parámetros que indican la cuenta, la propiedad web y la vista (perfil) a las 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 de la jerarquía de la API de administración. Puedes usar estos ID para crear consultas de la API de administración para obtener información de configuración adicional sobre la vista (perfil). Por ejemplo, puedes consultar la colección de objetivos de la API de administración para averiguar qué objetivos están activos junto con sus nombres de objetivo configurados.
Información de consulta
Cada respuesta de la API de informes centrales incluye un objeto que contiene todos los valores de parámetro de consulta empleados 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 devuelven como valores de una lista, mientras que los demás parámetros se devuelven como cadenas.
Información de paginación
Cualquier solicitud de la API de informes centrales puede coincidir con centenares de miles de filas de datos de Google Analytics. La API solo devolverá un subconjunto en un momento dado, que se puede denominar como una sola página de datos. Los campos de paginación se utilizan para 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 el número total de filas de datos con los que ha coincidido tu consulta en Google Analytics. Puede ser mayor que el número real de filas devueltas en una sola página de la respuesta.
El campo itemsPerPage representa el número de filas devueltas en esta página.
Los parámetros previousLink y nextLink solo se muestran si existe una página anterior o siguiente. Consulta estos enlaces para determinar si se pueden recuperar más páginas de datos de la API de informes centrales.
Totales de todos los resultados
Como se ha mencionado en la sección sobre la información de paginación anterior, una consulta a la API de informes centrales puede coincidir con muchas filas de datos en Google Analytics, pero solo devolver un subconjunto de datos.
Los valores de métrica totales de todas las filas coincidentes se devuelven 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 funcionales
Para ver las muestras funcionales completas, consulta la muestra de la API de informes centrales en el directorio de muestras de cada biblioteca de cliente.
Java
Biblioteca de cliente Java de la API de Google: muestra de la API de informes centrales
Python
Biblioteca de cliente Python de la API de Google: muestra de la API de informes centrales
PHP
Biblioteca de cliente PHP de la API de Google: muestra de la API de informes centrales
JavaScript
Biblioteca de cliente JavaScript de la API de Google: muestra de la API de informes centrales