En este documento, se describen varias funciones avanzadas de la versión 1 de la API de datos de Google Analytics. Para obtener una referencia detallada de la API, consulta la Referencia de la API.
Enumerar definiciones personalizadas y crear informes
La API de datos puede crear informes sobre dimensiones personalizadas y métricas personalizadas registradas. Puedes usar el método de API de metadatos para enumerar los nombres de API de las definiciones personalizadas registradas de tu propiedad. Estos nombres de API se pueden usar, por ejemplo, en las solicitudes de informes al método runReport.
En las siguientes secciones, se muestran ejemplos para cada tipo de definición personalizada. En estos ejemplos, reemplaza GA4_PROPERTY_ID
por tu ID de propiedad.
Dimensiones personalizadas centradas en el evento
Paso 1: Consulta el método de la API de metadatos con tu ID de propiedad.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Paso 2: Busca la dimensión personalizada centrada en el evento sobre la que te interesa crear informes a partir de la respuesta. Si la dimensión no está presente, debes registrarla.
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
Paso 3: Incluye la dimensión personalizada en una solicitud de informe. La siguiente es una solicitud de ejemplo para el método runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [{ "name": "customEvent:achievement_id" }],
"metrics": [{ "name": "eventCount" }]
}
Dimensiones personalizadas centradas en el usuario
Paso 1: Consulta el método de la API de metadatos con tu ID de propiedad.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Paso 2: Busca la dimensión personalizada centrada en el usuario sobre la que te interesa crear informes a partir de la respuesta. Si la dimensión no está presente, debes registrarla.
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
Paso 3: Incluye la dimensión personalizada en una solicitud de informe. La siguiente es una solicitud de ejemplo para el método runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"entity": { "propertyId": "GA4_PROPERTY_ID" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "customUser:last_level" }],
"metrics": [{ "name": "activeUsers" }]
}
Métricas personalizadas centradas en el evento
Paso 1: Consulta el método de la API de metadatos con tu ID de propiedad.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Paso 2: Busca en la respuesta la métrica personalizada centrada en el evento sobre la que te interesa crear informes. Si la métrica no está presente, debes registrarla.
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Paso 3: Incluye la métrica personalizada en una solicitud de informe. La siguiente es una solicitud de ejemplo para el método runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "customEvent:credits_spent" }]
}
Métricas de tasa de eventos clave para un evento clave
Paso 1: Consulta el método de la API de metadatos con tu ID de propiedad.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Paso 2: Busca la métrica de tasa de eventos clave para un evento clave sobre el que te interesa crear informes a partir de la respuesta. Si el evento clave no está presente, debes configurarlo.
"metrics": [
...
{
"apiName": "sessionKeyEventRate:add_to_cart",
"uiName": "Session key event rate for add_to_cart",
"description": "The percentage of sessions in which a specific key event was triggered",
},
...
],
Paso 3: Incluye la métrica de tasa de eventos clave en una solicitud de informe. La siguiente es una solicitud de ejemplo para el método runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}
Medias de las métricas personalizadas centradas en el evento
Paso 1: Consulta el método de la API de metadatos con tu ID de propiedad.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Paso 2: En la respuesta, busca el promedio de métricas personalizadas centradas en el evento sobre el que te interesa crear informes. Si la métrica no está presente, debes registrarla.
"metrics": [
...
{
"apiName": "averageCustomEvent:credits_spent",
"uiName": "Average Credits Spent",
"description": "The average of an event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Paso 3: Incluye el promedio de la métrica personalizada en una solicitud de informe. La siguiente es una solicitud de ejemplo para el método runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}
Ejemplos de informes de cohorte
Los informes de cohorte crean una serie temporal de retención de usuarios para la cohorte. Para obtener documentación detallada de cada campo de la API, consulta la referencia de REST para CohortSpec.
Cómo crear un informe de cohorte
Este es un informe de cohorte de muestra en el que ocurre lo siguiente:
- La cohorte está compuesta por usuarios con un
firstSessionDate
de2020-12-01
, que se configura con el objetocohorts
. Las dimensiones y métricas de la respuesta del informe solo se basarán en los usuarios de la cohorte. - El informe de cohorte mostrará tres columnas, que se configuran según los objetos de dimensiones y métricas.
- La dimensión
cohort
es el nombre de la cohorte. - La dimensión
cohortNthDay
es la cantidad de días desde2020-12-01
. - La métrica
cohortActiveUsers
es la cantidad de usuarios que aún están activos.
- La dimensión
- El objeto
cohortsRange
especifica que el informe debe contener datos de eventos que comiencen en2020-12-01
y finalicen en2020-12-06
para esta cohorte.- Cuando se usa un nivel de detalle de
DAILY
, se recomienda la dimensióncohortNthDay
para mantener la coherencia.
- Cuando se usa un nivel de detalle de
La solicitud de informe de la cohorte es la siguiente:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
"metrics": [{ "name": "cohortActiveUsers" }],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "DAILY"
}
},
}
Para esta solicitud, este es un ejemplo de respuesta de informe:
{
"dimensionHeaders": [
{ "name": "cohort" }, { "name": "cohortNthDay" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "293" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "143" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "123" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "92" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
"metricValues": [{ "value": "86" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "83" }]
}
],
"metadata": {},
"rowCount": 6
}
A partir de la respuesta del informe, aparece un gráfico para el Informe de cohorte a continuación. Una estadística de este informe es que la disminución más grande de usuarios activos en esta cohorte ocurre entre el primer y el segundo día.
Varias cohortes y fracción de retención de usuarios
La adquisición y retención de usuarios son formas de hacer crecer tu sitio web o app. Los informes de cohortes se centran en la retención de usuarios. En este ejemplo, el informe muestra que esta propiedad mejoró su retención de usuarios de 4 días en un 10% en el transcurso de dos semanas.
Para crear este informe, especificamos tres cohortes: la primera con un firstSessionDate
de 2020-11-02
, la segunda con un firstSessionDate
de 2020-11-09
y la tercera con un firstSessionDate
de 2020-11-16
. Dado que
la cantidad de usuarios en tu propiedad será diferente durante estos tres días,
comparamos la métrica de fracción de retención de usuarios de la cohorte, que es cohortActiveUsers/cohortTotalUsers
,
en lugar de usar la métrica directa
cohortActiveUsers
.
La solicitud de informe para estas cohortes es la siguiente:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metrics": [
{
"name": "cohortRetentionFraction",
"expression": "cohortActiveUsers/cohortTotalUsers"
}
],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
}
],
"cohortsRange": {
"endOffset": 4,
"granularity": "DAILY"
}
},
}
Para esta solicitud, este es un ejemplo de respuesta de informe:
{
"dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metricHeaders": [{
"name": "cohortRetentionFraction",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
"metricValues": [{ "value": "0.308" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
"metricValues": [{ "value": "0.272" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
"metricValues": [{ "value": "0.257" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "0.248" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
"metricValues": [{ "value": "0.235" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
"metricValues": [{ "value": "0.211" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
"metricValues": [{ "value": "0.198" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "0.172" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
"metricValues": [{ "value": "0.167" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
"metricValues": [{ "value": "0.155" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "0.141" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "0.118" }]
}
],
"metadata": {},
"rowCount": 15
}
A partir de la respuesta del informe, aparece un gráfico para el Informe de cohorte a continuación. Una estadística de este informe es que la retención de usuarios de 4 días aumentó un 10% en el transcurso de dos semanas. La cohorte posterior con firstSessionDate
de 2020-11-16
supera la retención de la cohorte anterior con un firstSessionDate
de 2020-11-02
.
Cohortes semanales y uso de cohortes con otras funciones de la API
Para quitar la variación diaria en el comportamiento de los usuarios, usa cohortes semanales. En los informes de cohorte semanales, todos los usuarios con firstSessionDate
en la misma semana forman la cohorte. Las semanas comienzan el domingo y terminan el sábado. Además, en este informe, dividimos la cohorte para comparar a los usuarios con actividad en Rusia con los usuarios con actividad en México. Esta segmentación usa la dimensión country
y un dimensionFilter
para considerar solo los dos países.
La solicitud de informe para estas cohortes es la siguiente:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dimensions": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metrics": [{ "name": "cohortActiveUsers" }],
"dimensionFilter": {
"filter": {
"fieldName": "country",
"inListFilter": {
"values": [ "Russia", "Mexico" ]
}
}
},
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": {
"startDate": "2020-10-04",
"endDate": "2020-10-10"
}
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "WEEKLY"
}
},
}
Para esta solicitud, este es un ejemplo de respuesta de informe:
{
"dimensionHeaders": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
],
"metricValues": [{ "value": "105" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "98" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "35" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "24" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
],
"metricValues": [{ "value": "23" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "17" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
],
"metricValues": [{ "value": "3" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
}
],
"metadata": {},
"rowCount": 11
}
A partir de la respuesta al informe, se muestra un gráfico de este Informe de cohorte. Según este informe, esta propiedad retiene a los usuarios con actividad en México mejor que los usuarios que tienen actividad en Rusia.
Comparaciones
Las comparaciones te permiten evaluar subconjuntos de tus datos en paralelo. Puedes definir comparaciones si especificas el campo comparisons
en una definición de informe. La función de comparaciones de la API de datos es similar a la comparaciones en el frontend de Google Analytics.
Para obtener documentación detallada sobre cada campo de la API, consulta la referencia de REST para la comparación.
Crea una comparación
Puedes crear una comparación independiente para cada conjunto de datos que desees comparar. Por ejemplo, si quieres comparar los datos web y de apps, puedes crear una comparación para los datos de iOS y Android y otra para los de la Web.
A continuación, se incluye un informe de muestra que define dos comparaciones y muestra los usuarios activos desglosados por país.
La primera comparación llamada "Tráfico de apps" usa inListFilter
para hacer coincidir la dimensión platform
con los valores "iOS" y "Android". En la segunda comparación llamada "Tráfico web", se usa stringFilter
para hacer coincidir la dimensión de platform
con la dimensión "web".
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"comparisons": [
{
"name": "App traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"inListFilter": {
"values": [
"iOS",
"Android"
]
}
}
}
},
{
"name": "Web traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"stringFilter": {
"matchType": "EXACT",
"value": "web"
}
}
}
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
],
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
]
}
Para todas las solicitudes que usan la función de comparaciones, el campo comparison
se agrega automáticamente al informe generado. Este campo contiene el nombre de la comparación proporcionada en la solicitud.
A continuación, se muestra un ejemplo de fragmento de una respuesta que contiene comparaciones:
{
"dimensionHeaders": [
{
"name": "comparison"
},
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "638572"
}
]
},
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "376578"
}
]
},
{
"dimensionValues": [
{
"value": "App traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "79527"
}
]
},
...
],
...
}