Esta guía para desarrolladores ofrece una introducción a la versión 4 de la API de informes de Analytics. Para acceder a la referencia detallada de la API, consulta la Referencia de la API.
Informes
La versión 4 de la API de informes de Analytics proporciona el método batchGet para acceder al recurso de informes.
En las secciones siguientes se describe la estructura del cuerpo de la solicitud que se envía a batchGet
y la estructura del cuerpo de la respuesta que se obtiene de batchGet
.
Cuerpo de la solicitud
Si quieres usar la versión 4 de la API de informes de Analytics para solicitar datos, debes crear un objeto ReportRequest con los siguientes requisitos mínimos:
- Un ID de vista válido para el campo viewId.
- Una o varias entradas válidas en el campo dateRanges.
- Una o varias entradas válidas en el campo metrics.
Para buscar un ID de vista, haz una consulta al método de resúmenes de cuentas o utiliza el Explorador de cuentas.
Si no indicas ningún periodo, se usará el periodo predeterminado:
{"startDate": "7daysAgo", "endDate": "yesterday"}
.
A continuación se muestra una solicitud de ejemplo que incluye el número mínimo de campos obligatorios:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
El método batchGet
admite hasta 5 objetos ReportRequest. Todas las solicitudes deben tener los mismos campos dateRange
, viewId
, segments
, samplingLevel
y cohortGroup
.
Cuerpo de la respuesta
El cuerpo de la respuesta de la solicitud de la API es una matriz de objetos del tipo informe. La estructura del informe se define en el objeto ColumnHeader, que describe las dimensiones y las métricas, así como sus respectivos tipos de datos en el informe. Los valores de las dimensiones y las métricas se indican en el campo data.
A continuación se muestra una respuesta de ejemplo a la solicitud anterior:
{
"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"
]
}
]
}
}
]
}
Métricas
Las métricas son mediciones cuantitativas. Cada solicitud debe incluir, como mínimo, un objeto Metric.
En el ejemplo siguiente, se proporciona la métrica Sessions
al método batchGet
para obtener el número total de sesiones durante el periodo indicado:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
Puedes usar el Explorador de dimensiones y métricas o la API de metadatos para obtener la lista de dimensiones y métricas disponibles.
Filtrado
Al enviar una solicitud batchGet
, puedes indicar que solo devuelva las métricas que cumplan determinados criterios. Para filtrar las métricas, indica uno o varios objetos MetricFilterClause en el cuerpo de la solicitud y define uno o varios objetos MetricFilter en cada cláusula MetricFilterClause
.
En cada objeto MetricFilter
, indica los valores de los elementos siguientes:
metricName
not
operator
comparisonValue
{metricName}
representa la métrica, {operator}
representa el operator
(operador) y
{comparisonValue}
representa el comparisonValue
(valor de comparación). El funcionamiento del filtro es el siguiente:
if {metricName} {operator} {comparisonValue}
return the metric
Si indicas que el valor de not
es true
, el funcionamiento del filtro es el siguiente:
if {metricName} {operator} {comparisonValue}
do not return the metric
En el ejemplo siguiente, batchGet
solo devuelve el número de páginas vistas cuyo valor es superior a 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"
}]
}]
}]
}
Expresiones
Las expresiones de las métricas son expresiones matemáticas que se definen en las métricas existentes y que funcionan como métricas calculadas dinámicamente. Puedes definir un alias que represente la expresión de una métrica. Por ejemplo:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
Clasificación
Para ordenar los resultados según el valor de la métrica:
- Indica el nombre o el alias en el campo
fieldName
. - Indica cómo quieres ordenar los resultados (
ASCENDING
oDESCENDING
) en el camposortOrder
.
En el ejemplo siguiente, batchGet
devuelve las métricas clasificadas primero por sesión y luego por número de páginas vistas, en orden descendente:
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"}
]
}
]
}
Dimensiones
Las dimensiones describen características de los usuarios, sus sesiones y sus acciones.
Por ejemplo, la dimensión Ciudad describe una característica de la sesión e indica la ciudad (por ejemplo, "París" o "Nueva York") desde la que se origina la sesión en cuestión.
En una solicitud batchGet
, puedes indicar cero o más objetos del tipo dimensión. Por ejemplo:
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"}
]
}
]
}
Filtrado
Al enviar una solicitud batchGet
, puedes indicar que solo devuelva las dimensiones que cumplan determinados criterios. Para filtrar las dimensiones, indica uno o varios objetos DimensionsFilterClause en el cuerpo de la solicitud y define uno o varios objetos DimensionsFilter en cada cláusula DimensionsFilterClause
.
En cada objeto DimensionsFilters
, indica los valores de los elementos siguientes:
dimensionName
not
operator
expressions
caseSensitive
{dimensionName}
representa la dimensión, {operator}
representa el operator
(operador) y {expressions}
representa las expressions
(expresiones). El funcionamiento del filtro es el siguiente:
if {dimensionName} {operator} {expressions}
return the dimension
Si indicas que el valor de not
es true
, el funcionamiento del filtro es el siguiente:
if {dimensionName} {operator} {expressions}
do not return the dimension
En el ejemplo siguiente, batchGet
devuelve el número de páginas vistas y las sesiones realizadas en un navegador 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"]
}
]
}
]
}
]
}
Clasificación
Para ordenar los resultados según el valor de la dimensión:
- Indica el nombre de la dimensión en el campo
fieldName
. - Indica cómo quieres ordenar los resultados (
ASCENDING
oDESCENDING
) en el camposortOrder
.
En el ejemplo siguiente, batchGet
devuelve las dimensiones clasificadas primero por país y luego por navegador:
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"}
]
}
]
}
Agrupaciones de histograma
Para entender mejor las características de las dimensiones que presentan valores enteros, se recomienda agrupar estos valores por intervalos. En el campo histogramBuckets
, define los intervalos de los grupos resultantes e indica HISTOGRAM_BUCKET
como tipo de clasificación. Por ejemplo:
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"
}
]
}
]
}
Varios periodos
Con la versión 4 de la API de informes de Google Analytics puedes obtener datos de distintos periodos con una sola solicitud. Tanto si en la solicitud indicas uno como dos periodos, los datos se devuelven en el objeto dateRangeValue. Por ejemplo:
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"}]
}
]
}
Clasificación delta
Al solicitar valores de métricas de dos periodos diferentes, puedes ordenar los resultados según la diferencia entre los valores de la métrica en cada periodo. Por ejemplo:
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"
}
]
}
]
}
Comportamiento de la dimensión según la fecha
Si solicitas una dimensión relacionada con una fecha u hora, el objeto DateRangeValue solo incluirá los valores de las fechas de los periodos correspondientes. Los demás valores que no correspondan a los periodos indicados serán 0
.
Veamos un ejemplo de solicitud de la dimensión ga:date
y la métrica ga:sessions
que incluye dos periodos: enero y febrero.
En la respuesta correspondiente a los datos solicitados de enero, los valores de febrero serán 0
, y en la respuesta correspondiente a los datos solicitados de febrero, los valores de enero serán 0
.
Informe de enero
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
Informe de febrero
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
Segmentos
Si quieres solicitar un subconjunto de tus datos de Analytics, puedes usar segmentos. Por ejemplo, puedes incluir a los usuarios de un determinado país o ciudad en un segmento y a los usuarios que visitan una sección concreta de tu sitio web en otro. Los filtros solo devuelven las filas que cumplen una condición, mientras que los segmentos devuelven un subconjunto de usuarios, sesiones o eventos que cumplen las condiciones que en ellos se indica.
Al enviar una solicitud con segmentos, ten en cuenta lo siguiente:
- Las definiciones de los segmentos de todos los objetos ReportRequest de un método
batchGet
deben ser idénticas. - Debes añadir
ga:segment
a la lista de dimensiones.
Por ejemplo:
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 varios ejemplos de solicitudes con segmentos.
ID de segmento
Usa el campo segmentId
para solicitar segmentos.
No puedes usar un campo segmentId
y un campo dynamicSegment
a la vez para solicitar segmentos.
Por ejemplo:
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"}]
}
]
}
Muestreo
El muestreo puede afectar a los resultados de los datos y es un motivo habitual por el que los valores que devuelve la API no coinciden con la interfaz web. Indica el tamaño de muestra que quieras utilizar en el campo samplingLevel
.
- Define el valor en
SMALL
si quieres obtener una respuesta rápida con un tamaño de muestra más pequeño. - Define el valor en
LARGE
si quieres obtener una respuesta más lenta, pero más precisa. - Define el valor en
DEFAULT
si quieres obtener una respuesta en la que la velocidad y la precisión estén equilibradas.
Por ejemplo:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
Si un informe contiene muestras de datos, la versión 4 de la API de informes de Analytics devuelve los campos samplesReadCounts
y samplingSpaceSizes
.
Si los resultados no son una muestra de datos, estos campos no se definen.
A continuación se incluye una respuesta de ejemplo que contiene datos de muestra de una solicitud con dos periodos distintos. Para calcular los resultados se utilizaron cerca de 500.000 muestras con un tamaño de muestra aproximado de 15 millones de sesiones:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Paginación
En la versión 4 de la API de informes de Analytics se usan los campos pageToken
y pageSize
para paginar los resultados de las respuestas que ocupan varias páginas. pageToken
se obtiene del parámetro nextPageToken
en la respuesta a la solicitud reports.batchGet
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Paso siguiente
Ahora que ya conoces los conceptos básicos para crear un informe, consulta las funciones avanzadas de la versión 4 de la API.