Esta es una guía para desarrolladores sobre la versión 4 de la API de Analytics Reporting. Para obtener una referencia detallada de la API, consulta la Referencia de la API.
Informes
La API de Analytics Reporting v4 proporciona el método batchGet
para acceder al recurso Reports.
En las siguientes secciones, se describe la estructura del cuerpo de la solicitud de batchGet
y la del cuerpo de la respuesta de batchGet
.
Cuerpo de la solicitud
Si deseas usar la API de Analytics Reporting v4 para solicitar datos, debes crear un objeto ReportRequest, que tenga los siguientes requisitos mínimos:
- Un ID de vista válido para el campo viewId.
- Al menos una entrada válida en el campo dateRanges.
- Al menos una entrada válida en el campo metrics.
Para encontrar un ID de vista, consulta el método de resúmenes de la cuenta o usa el Explorador de cuentas.
Si no se proporciona un período, el predeterminado es {"startDate": "7daysAgo", "endDate": "yesterday"}
.
Esta es una solicitud de ejemplo con los campos obligatorios mínimos:
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
acepta un máximo de cinco objetos ReportRequest. Todas las solicitudes deben tener el mismo dateRange
, viewId
, segments
, samplingLevel
y cohortGroup
.
Cuerpo de la respuesta
El cuerpo de la respuesta de la solicitud a la API es un array de objetos Report. La estructura del informe se define en el objeto ColumnHeader, que describe las dimensiones, las métricas y sus tipos de datos en el informe. Los valores de las dimensiones y métricas se especifican en el campo datos.
A continuación, se muestra una respuesta de muestra de la solicitud de muestra 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 requiere al menos un objeto Metric.
En el siguiente ejemplo, se proporciona la métrica Sessions
al método batchGet
para obtener la cantidad total de sesiones en el período especificado:
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.
Filtros
Cuando envías una solicitud batchGet
, puedes pedirle que muestre solo métricas que cumplan con criterios específicos. Para filtrar métricas, en el cuerpo de la solicitud, especifica una o más MetricFilterClauses y, en cada MetricFilterClause
, define uno o más MetricFilters.
En cada MetricFilter
, especifica los valores de lo siguiente:
metricName
not
operator
comparisonValue
Deja que {metricName}
represente la métrica, {operator}
el operator
y {comparisonValue}
el comparisonValue
. Luego, el filtro funciona de la siguiente manera:
if {metricName} {operator} {comparisonValue}
return the metric
Si especificas true
para not
, el filtro funciona de la siguiente manera:
if {metricName} {operator} {comparisonValue}
do not return the metric
En el siguiente ejemplo, batchGet
solo muestra las páginas vistas cuyo valor es mayor que 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
Una expresión de métrica es una expresión matemática que defines en las métricas existentes; funciona como métricas calculadas dinámicas. Puedes definir un alias para representar la expresión de la 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"
}
]
}
]
}
Pedidos
Para ordenar los resultados según un valor de métrica, sigue estos pasos:
- Proporciona su nombre o alias a través del campo
fieldName
. - Especifica el orden de clasificación (
ASCENDING
oDESCENDING
) a través del camposortOrder
.
En el siguiente ejemplo, batchGet
muestra las métricas ordenadas primero por sesiones y, luego, por vistas de página 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 las características de tus usuarios, sus sesiones y acciones.
La dimensión Ciudad, por ejemplo, describe una característica de las sesiones y especifica la ciudad ("París" o "Nueva York") donde se originó cada sesión.
En una solicitud batchGet
, puedes especificar cero o más objetos de 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"}
]
}
]
}
Filtros
Cuando envías una solicitud de batchGet
, puedes pedirle que solo muestre dimensiones que cumplan con criterios específicos. Para filtrar dimensiones, en el cuerpo de la solicitud, especifica una o más DimensionsFilterClauses y, en cada DimensionsFilterClause
, define uno o más DimensionsFilters.
En cada DimensionsFilters
, especifica los valores de lo siguiente:
dimensionName
not
operator
expressions
caseSensitive
Deja que {dimensionName}
represente la dimensión, {operator}
el operator
y {expressions}
el expressions
. Luego, el filtro funciona de la siguiente manera:
if {dimensionName} {operator} {expressions}
return the dimension
Si especificas true
para not
, el filtro funciona de la siguiente manera:
if {dimensionName} {operator} {expressions}
do not return the dimension
En el siguiente ejemplo, batchGet
muestra vistas de páginas y sesiones 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"]
}
]
}
]
}
]
}
Pedidos
Para ordenar los resultados por un valor de dimensión, sigue estos pasos:
- Proporciona su nombre a través del campo
fieldName
. - Especifica el orden de clasificación (
ASCENDING
oDESCENDING
) a través del camposortOrder
.
Por ejemplo, el siguiente batchGet
muestra las dimensiones ordenadas 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"}
]
}
]
}
Depósitos de histogramas
En el caso de las dimensiones con valores de números enteros, es más fácil comprender sus características mediante el agrupamiento de sus valores en rangos. Usa el campo histogramBuckets
para definir los rangos de los buckets resultantes y especifica HISTOGRAM_BUCKET
como el tipo de orden, 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 períodos
La API de Google Analytics Reporting v4 te permite obtener datos en varios períodos en una sola solicitud. Si tu solicitud especifica uno o dos períodos, los datos se muestran 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"}]
}
]
}
Orden delta
Si solicitas valores de métricas en dos períodos, puedes ordenar los resultados según la diferencia entre los valores de la métrica en los períodos, 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 de fecha
Si solicitas una dimensión relacionada con la fecha o la hora, el objeto DateRangeValue solo contendrá los valores de las fechas que se encuentran dentro de los rangos respectivos. Todos los demás valores que no estén en los períodos especificados serán 0
.
Por ejemplo, considera una solicitud para la dimensión ga:date
y la métrica ga:sessions
en dos períodos: enero y febrero.
En la respuesta de los datos solicitados de enero, los valores de febrero serán 0
. En la respuesta de 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
Para solicitar un subconjunto de tus datos de Analytics, usa segmentos. Por ejemplo, puedes definir a los usuarios de un país o una ciudad en particular en un segmento y a los usuarios que visitan una parte específica de tu sitio en otro. Los filtros solo muestran filas que satisfacen una condición, mientras que los segmentos muestran un subconjunto de usuarios, sesiones o eventos que cumplen con las condiciones que contienen los segmentos.
Cuando realices una solicitud con segmentos, asegúrate de lo siguiente:
- Cada ReportRequest dentro de un método
batchGet
debe contener definiciones de segmento idénticas. - Agrega
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 Muestras para ver más solicitudes de ejemplo con segmentos.
ID del segmento
Usa el campo segmentId
para solicitar segmentos.
No puedes usar segmentId
y dynamicSegment
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 los resultados de tus datos y es un motivo común por el que los valores que muestra la API no coinciden con la interfaz web. Usa el campo samplingLevel
para establecer el tamaño de muestra deseado.
- Establece el valor en
SMALL
para obtener una respuesta rápida con un tamaño de muestra más pequeño. - Establece el valor en
LARGE
para obtener una respuesta más precisa, pero más lenta. - Establece el valor en
DEFAULT
para una respuesta que equilibra la velocidad y la exactitud.
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 una muestra de datos, la API de Analytics Reporting v4 mostrará los campos
samplesReadCounts
y samplingSpaceSizes
.
Si los resultados no se muestrean, estos campos no se definirán.
A continuación, se incluye un ejemplo de respuesta que contiene datos muestreados de una solicitud con dos períodos. Los resultados se calcularon a partir de casi 500,000 muestras de un espacio de muestra de aproximadamente 15 millones de sesiones:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Paginación
La API de Analytics Reporting v4 usa los campos
pageToken
y pageSize
para paginar los resultados de respuesta que abarcan varias
páginas. Obtienes pageToken
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",
}]
}
Próximo paso
Ahora que cubres los conceptos básicos de la creación de un informe, revisa las funciones avanzadas de la versión 4 de la API.