Crear informes

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 o DESCENDING) en el campo sortOrder.

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 o DESCENDING) en el campo sortOrder.

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.