Cómo crear un informe

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.

Nota: Esta API no es compatible con las propiedades Google Analytics 4 (GA4). Usa la API de datos de Google Analytics para acceder a las nuevas funciones de informes para las propiedades GA4.

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"
                        ]
                    }
                ]
            }
        }
    ]
}

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

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"
        }
      ]
    }
  ]
}

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

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 o DESCENDING) a través del campo sortOrder.

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 o DESCENDING) a través del 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

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"
        }
      ]
    }
  ]
}

Nota: Consulta Request Composer para obtener una aplicación de demostración que use algunas de estas funciones.

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"}]
    }
  ]
}

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

Muestreo

Nota: En el caso de las cuentas de Analytics 360, considera usar la función Cuota basada en recursos para aprovechar umbrales de muestreo más altos mientras utilizas la API de Analytics Reporting.

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"
    }
  ]
}

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

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",
  }]
}

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

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.