Cómo crear un informe

Esta es una guía para desarrolladores de la versión 4 de la API de Analytics Reporting. Para obtener una referencia detallada de la API, consulta la referencia de la API.

Nota: Esta API no admite propiedades de Google Analytics 4 (GA4). Utilice la API de datos de Google Analytics a fin de acceder a las nuevas funciones de informes para las propiedades GA4.

Informes

La API de informes de Analytics v4 proporciona el método batchGet para acceder al recurso Informes. En las siguientes secciones, se describe la estructura del cuerpo de la solicitud para batchGet y la del cuerpo de la respuesta de batchGet.

Cuerpo de la solicitud

Para usar la API de informes de Analytics v4 a fin de solicitar datos, debes construir un objeto ReportRequest, que tiene estos 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 cuentas o usa el Explorador de cuentas. Si no se proporciona un período, el predeterminado es {"startDate": "7daysAgo", "endDate": "yesterday"}.

A continuación, se muestra 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 las mismas dateRange, viewId, segments, samplingLevel y cohortGroup.

Cuerpo de la respuesta

El cuerpo de la respuesta de la solicitud a la API es un arreglo de objetos Report. La estructura del informe se define en el objeto ColumnHeader, que describe las dimensiones y las métricas, y sus tipos de datos en el informe. Los valores de las dimensiones y métricas se especifican en el campo data.

A continuación, se muestra una respuesta de ejemplo para la solicitud de ejemplo 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"
                        ]
                    }
                ]
            }
        }
    ]
}

Nota: Cuando se analiza el cuerpo de la respuesta, si falta un campo booleano, puedes asumir que su valor es false. En la respuesta, solo se muestran campos booleanos con el valor true; por ejemplo, el campo isDataGolden estará en la respuesta si su valor es true.

Métricas

Las métricas son medidas cuantitativas; cada solicitud requiere al menos un objeto Metric.

En el siguiente ejemplo, la métrica Sessions se proporciona 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"}]
    }
  ]
}

Puede 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 uno o más MetricFilterClauses y, en cada MetricFilterClause, define uno o más MetricFilters. En cada MetricFilter, especifica los valores para lo siguiente:

• metricName
• not
• operator
• comparisonValue

Deja que {metricName} represente la métrica, {operator} la operator y {comparisonValue} la 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 métricas existentes; funciona como métricas calculadas dinámicas. Puedes definir un alias para representar la expresión de 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"
        }
      ]
    }
  ]
}

Nota: También puedes especificar los tipos de formato para las expresiones de métricas que definiste.

Orden

Para ordenar los resultados por valor de métrica, sigue estos pasos:

• Proporciona su nombre o alias en el campo fieldName.
• Especifica el orden de clasificación (ASCENDING o DESCENDING) a través del campo sortOrder.

En el siguiente ejemplo, batchGet muestra las métricas ordenadas primero por sesiones y, luego, por 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 las características de los usuarios, sus sesiones y acciones. La dimensión Ciudad, por ejemplo, describe una característica de las sesiones e indica la ciudad (París, 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 batchGet, puedes pedirle que muestre solo las dimensiones que cumplan con criterios específicos. Para filtrar las 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 para lo siguiente:

• dimensionName
• not
• operator
• expressions
• caseSensitive

Deja que {dimensionName} represente la dimensión, {operator} la operator y {expressions} la 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 páginas vistas 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"]
            }
          ]
        }
      ]
    }
  ]
}

Orden

Para ordenar los resultados por valor de dimensión, siga estos pasos:

• Proporciona su nombre en el campo fieldName.
• Especifica el orden de clasificación (ASCENDING o DESCENDING) en el campo sortOrder.

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

Para las dimensiones con valores de números enteros, es más fácil comprender sus características si agrupas sus valores en rangos. Usa el campo histogramBuckets para definir los rangos de los depósitos resultantes y especifica HISTOGRAM_BUCKET como el tipo de pedido, 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"
        }
      ]
    }
  ]
}

Nota: Consulte Request Composer para ver una aplicación de demostración en la que se usan algunas de estas funciones.

Varios períodos

La API de informes de Google Analytics 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

Cuando 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 una fecha o una hora, el objeto DateRangeValue contendrá solo valores para 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 para los datos solicitados en enero, los valores en febrero serán 0 y en la respuesta para los datos solicitados en febrero, los valores en 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 usuarios de un país o una ciudad en particular en un segmento, y 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 segmentos 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 obtener 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"}]
    }
  ]
}

Nota: El campo segmentId también admite la sintaxis de segmentos en la API de Core Reporting V3. Consulta la Guía de migración para obtener más detalles.

Muestreo

Nota: Para las cuentas de Analytics 360, considera usar la función Cuota basada en recursos para aprovechar umbrales de muestreo más altos mientras usas la API de informes de Analytics.

El muestreo puede afectar los resultados de los 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 una respuesta rápida con un tamaño de muestreo 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 equilibre la velocidad y la precisión.

Por ejemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

Nota: Cada ReportRequest dentro de un método batchGet debe contener la misma definición samplingLevel.

Si un informe contiene datos de muestra, la API de informes de Analytics v4 muestra los campos samplesReadCounts y samplingSpaceSizes. Si no se toman muestras, estos campos no se definirán.

A continuación, se muestra un ejemplo de respuesta que contiene datos de muestra de una solicitud con dos períodos. Los resultados se calcularon a partir de casi 500,000 muestras de un tamaño de espacio de muestreo de aproximadamente 15 millones de sesiones:

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

Paginación

La API de informes de Analytics 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",
  }]
}

Nota: Técnicamente, nextPageToken puede ser una string arbitraria, pero en la mayoría de los casos, es un índice de fila basado en cero. A fin de garantizar una paginación correcta, usa el valor nextPageToken para el campo pageToken.

Próximo paso

Ahora que conoces los conceptos básicos para crear un informe, observa las funciones avanzadas de la versión 4 de la API.