API de informes centrales: guía de referencia

En este documento se proporciona la referencia completa de la consulta y la respuesta de la versión 3.0 de la API de informes centrales.

Introducción

La API de informes centrales se consulta para obtener los datos de informe de Google Analytics. Cada consulta requiere un ID de vista (perfil), una fecha de inicio y finalización, y una métrica como mínimo. También se pueden suministrar parámetros de consulta adicionales, como dimensiones, filtros y segmentos, para definir mejor la consulta. Consulta la Guía Descripción general para saber cómo funcionan juntos todos estos conceptos.

Solicitud

La API proporciona un solo método para solicitar datos:

analytics.data.ga.get()

Este método se expone en varias bibliotecas de cliente y tiene interfaces específicas del lenguaje para configurar los parámetros de consulta.

La API también se puede consultar como un extremo compatible con REST:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

Cada parámetro de consulta de URL especifica un parámetro de consulta de la API que debe tener codificación de URL.

Resumen de los parámetros de consulta

En la tabla siguiente se resumen todos los parámetros de consulta aceptados por la API de informes centrales. Haz clic en cada nombre de parámetro para obtener una descripción detallada.

Nombre Valor Obligatorio Resumen
ids string ID de tabla único con el formato ga:XXXX, donde XXXX es el ID de vista (perfil) de Analytics del que la consulta recuperará los datos.
start-date string Fecha de inicio para recuperar los datos de Analytics. En las solicitudes se puede especificar una fecha de inicio con el formato AAAA-MM-DD o una fecha relativa (por ejemplo, today, yesterday o NdaysAgo donde N es un entero positivo).
end-date string Fecha de finalización para recuperar los datos de Analytics. En la solicitud se puede especificar una fecha de finalización con el formato AAAA-MM-DD o una fecha relativa (por ejemplo, today, yesterday o NdaysAgo donde N es un entero positivo).
metrics string Lista de métricas separadas por comas, como ga:sessions,ga:bounces.
dimensions string No Lista de dimensiones separadas por comas de los datos de Analytics, como ga:browser,ga:city.
sort string No Lista de dimensiones y métricas separadas por comas que indica el orden y la dirección de clasificación de los datos devueltos.
filters string No Filtros de dimensión o métrica que limitan los datos devueltos para la solicitud.
segment string No Segmenta los datos devueltos para la solicitud.
samplingLevel string No Nivel de muestreo deseado. Valores permitidos:
  • DEFAULT: devuelve una respuesta con un tamaño de muestra que equilibra velocidad y exactitud.
  • FASTER: devuelve una respuesta rápida con un tamaño de muestra menor.
  • HIGHER_PRECISION: devuelve una respuesta más exacta con un tamaño de muestra grande, pero puede provocar que la respuesta sea más lenta.
include-empty-rows boolean No Está establecido en true de forma predeterminada. Si se establece en false, las filas en las que todos los valores de métrica son cero se omiten en la respuesta.
start-index integer No Primera fila de los datos para recuperar, empezando en 1. Utiliza este parámetro como un mecanismo de paginación junto con el parámetro max-results.
max-results integer No Número máximo de filas que se incluirán en la respuesta.
output string No Tipo de salida deseado de los datos de Analytics que se devuelven en la respuesta. Los valores que se aceptan son json y dataTable. Valor predeterminado: json.
fields string No Selector que especifica un subconjunto de campos para incluirlos en la respuesta.
prettyPrint string No Muestra la respuesta con sangrados y saltos de línea. Valor predeterminado: false.
userIp string No Especifica la dirección IP del usuario final para el que se realiza la llamada de la API. Se utiliza para limitar el uso por IP.
quotaUser string No Alternativa a userIp en los casos en que se desconoce la dirección IP del usuario.
access_token string No Una forma posible de proporcionar un token de OAuth 2.0.
callback string No Nombre de la función de devolución de llamada de JavaScript que gestiona la respuesta. Se usa en solicitudes JSON-P de JavaScript.
key string No Se utiliza en la autorización de OAuth 1.0a para especificar que la aplicación obtenga la cuota. Por ejemplo:key=AldefliuhSFADSfasdfasdfASdf.

Información de los parámetros de consulta

ids

ids=ga:12345
Obligatorio.
ID único utilizado para recuperar los datos de Analytics. Este ID es la concatenación del espacio de nombres ga: con el ID de vista (perfil) de Analytics. Puedes recuperar el ID de vista (perfil) utilizando el método analytics.management.profiles.list, que proporciona el valor de id en el recurso Vista (perfil) de la API de administración de Google Analytics.

start-date

start-date=2009-04-20
Obligatorio.
Todos los datos de Analytics deben especificar un periodo. Si no incluyes los parámetros start-date y end-date en la solicitud, el servidor devuelve un error. Los valores de fecha pueden ser de una fecha específica si se usa el patrón AAAA-MM-DD o relativa mediante today, yesterday o el patrón NdaysAgo. Los valores deben coincidir con [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
El primer valor válido de start-date es 2005-01-01. No hay límite superior para start-date.
Las fechas relativas siempre son relativas a la fecha actual en el momento de la consulta y se basan en la zona horaria de la vista (perfil) especificada en la consulta.

Periodo de ejemplo de los últimos siete días (empezando desde ayer) mediante fechas relativas:

  &start-date=7daysAgo
  &end-date=yesterday

end-date

end-date=2009-05-20
Obligatorio.
Todos los datos de Analytics deben especificar un periodo. Si no incluyes los parámetros start-date y end-date en la solicitud, el servidor devuelve un error. Los valores de fecha pueden ser de una fecha específica si se usa el patrón AAAA-MM-DD o relativa mediante today, yesterday o el patrón NdaysAgo. Los valores deben coincidir con [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
El primer valor válido de end-date es 2005-01-01. No hay límite superior para end-date.
Las fechas relativas siempre son relativas a la fecha actual en el momento de la consulta y se basan en la zona horaria de la vista (perfil) especificada en la consulta.

Periodo de ejemplo de los últimos diez días (empezando desde hoy) mediante fechas relativas:

  &start-date=9daysAgo
  &end-date=today

dimensions

dimensions=ga:browser,ga:city
Opcional.
El parámetro dimensions desglosa las métricas por criterios comunes; por ejemplo, por ga:browser o ga:city. Aunque puedes solicitar el número total de páginas vistas en tu sitio, podría ser más interesante solicitar el número de páginas vistas desglosadas por navegador. Así podrás ver el número de páginas vistas desde Firefox, Internet Explorer, Chrome, etc.

Al usar dimensions en una solicitud de datos, ten en cuenta estas restricciones:

  • Puedes incluir un máximo de siete dimensiones por consulta.
  • No puedes enviar una consulta compuesta solo de dimensiones: debes combinar las dimensiones solicitadas con una métrica como mínimo.
  • Solo se pueden consultar determinadas dimensiones en la misma consulta. Utiliza la herramienta de combinación válida de la Referencia de dimensiones y métricas para saber qué dimensiones se pueden usar juntas.


metrics

metrics=ga:sessions,ga:bounces
Obligatorio.
Estadísticas acumuladas de la actividad de usuario en tu sitio, como los clics o las páginas vistas. Si una consulta no tiene el parámetro dimensions, las métricas devueltas proporcionan valores acumulados correspondientes al periodo solicitado, como el total de páginas vistas o de rebotes. Sin embargo, cuando se solicitan las dimensiones, los valores se segmentan por valor de dimensión. Por ejemplo, si se solicita ga:pageviews con ga:country, se devuelve el total de páginas vistas por país. Al solicitar métricas hay que tener en cuenta que:
  • Cualquier solicitud debe proporcionar una métrica como mínimo; una solicitud no puede constar solo de dimensiones.
  • En una consulta no se pueden incluir más de diez métricas.
  • La mayoría de las combinaciones de métricas de varias categorías se pueden usar juntas, siempre que no se especifiquen dimensiones.
  • Se puede utilizar una métrica en combinación con otras dimensiones o métricas, pero solo donde se apliquen combinaciones válidas para esa métrica. Consulta el artículo Referencia de dimensiones y métricas para obtener más información.


sort

sort=ga:country,ga:browser
Opcional.

Lista de dimensiones y métricas que indica el orden y la dirección de clasificación de los datos devueltos.

  • El orden de clasificación se especifica mediante el orden de izquierda a derecha de las métricas y las dimensiones enumeradas.
  • La dirección de ordenación predeterminada es ascendente y se puede cambiar a descendente con un prefijo de signo menos (-) en el campo solicitado.

La ordenación de los resultados de una consulta permite plantear diferentes preguntas sobre los datos. Por ejemplo, para responder a la pregunta "¿Cuáles son mis principales países y qué navegadores se usan más?" puedes crear una consulta con el parámetro siguiente. Primero ordena por ga:country y, después, por ga:browser, ambos en orden ascendente:

sort=ga:country,ga:browser

Para responder a la pregunta relacionada "¿Cuáles son mis principales navegadores y qué países los usan más?", puedes crear una consulta con el siguiente parámetro. Primero ordena por ga:browser y, después, por ga:country, ambos en orden ascendente:
sort=ga:browser,ga:country

Al usar el parámetro sort, ten en cuenta lo siguiente:

  • Ordena solo por valores de dimensiones o de métricas que hayas usado en los parámetros dimensions o metrics. Si tu solicitud se ordena por un campo que no está indicado en el parámetro dimensions o metrics, se producirá un error.
  • De forma predeterminada, las cadenas tienen orden alfabético ascendente en la configuración regional en-US.
  • Los números tienen orden numérico ascendente de forma predeterminada.
  • Las fechas aparecen en orden ascendente de forma predeterminada.

filters

filters=ga:medium%3D%3Dreferral
Opcional.

El parámetro de cadena de consulta filters limita los datos devueltos en la solicitud. Para usar el parámetro filters, indica una dimensión o una métrica por la que se filtrará, seguida de la expresión de filtro. Por ejemplo, la consulta siguiente solicita ga:pageviews y ga:browser de la vista (perfil) 12134, donde la dimensión ga:browser empieza por la cadena Firefox:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

Las consultas filtradas limitan las filas incluidas (o excluidas) en el resultado. Cada fila del resultado se prueba con el filtro: si hay concordancia, se mantiene el filtro; de lo contrario, se quita.

  • Codificación de URL: las bibliotecas de cliente de la API de Google codifican automáticamente los operadores de filtro.
  • Filtrado de dimensiones: el filtrado se realiza antes de agregar dimensiones, de forma que las métricas devueltas representen el total para las dimensiones relevantes únicamente. En el ejemplo anterior, el número de páginas vistas incluirá únicamente las páginas vistas en el navegador Firefox.
  • Filtrado de métricas: el filtrado de las métricas se realiza después de agregar las métricas.
  • Combinaciones válidas: se puede filtrar por una dimensión o métrica que no forma parte de la consulta, siempre que las dimensiones y métricas de la solicitud y el filtro sean combinaciones válidas. Por ejemplo, es recomendable consultar una lista con fechas de páginas vistas y filtrar por un determinado navegador. Consulta el artículo Referencia de dimensiones y métricas para obtener más información.

Sintaxis de filtro


Un filtro individual usa la forma siguiente:

ga:name operator expression

En esta sintaxis:

  • nombre: nombre de la dimensión o métrica por la que se va a filtrar. Por ejemplo, ga:pageviews filtra por la métrica de páginas vistas.
  • operador: define el tipo de concordancia de filtro que se debe usar. Los operadores son específicos de dimensiones o métricas.
  • expresión: especifica los valores que se incluirán en los resultados o se excluirán de ellos. En las expresiones se utiliza sintaxis de expresiones regulares.

Operadores de filtro


Hay seis operadores de filtro para las dimensiones y otros seis para las métricas. Los operadores deben codificarse en URL para incluirlos en las cadenas de consulta URL.

Consejo: utiliza el Explorador de consultas de feed de datos para diseñar filtros que necesiten la codificación de URL, ya que el Explorador de consultas codifica automáticamente las URL que contienen cadenas y espacios.

Filtros de métricas
Operador Descripción Forma codificada en URL Ejemplos
== Es igual a %3D%3D Devuelve resultados en los que el tiempo en la página es de exactamente 10 segundos:
filters=ga:timeOnPage%3D%3D10
!= No es igual a !%3D Devuelve resultados en los que el tiempo en la página no es 10 segundos:
filters=ga:timeOnPage!%3D10
> Mayor que %3E Devuelve resultados en los que el tiempo en la página es estrictamente mayor que 10 segundos:
filters=ga:timeOnPage%3E10
< Menor que %3C Devuelve resultados en los que el tiempo en la página es estrictamente menor que 10 segundos:
filters=ga:timeOnPage%3C10
>= Superior o igual a %3E%3D Devuelve resultados en los que el tiempo en la página es de 10 segundos o más:
filters=ga:timeOnPage%3E%3D10
<= Inferior o igual a %3C%3D Devuelve resultados en los que el tiempo en la página es de 10 segundos o menos:
filters=ga:timeOnPage%3C%3D10

Filtros de dimensiones
Operador Descripción Forma codificada en URL Ejemplo
== Concordancia exacta %3D%3D Agrega métricas en las que la ciudad es Irvine:
filters=ga:city%3D%3DIrvine
!= No coincide exactamente !%3D Agrega métricas en las que la ciudad no es Irvine:
filters=ga:city!%3DIrvine
=@ Contiene cadena secundaria %3D@ Agrega métricas en las que la ciudad contiene York:
filters=ga:city%3D@York
!@ No contiene cadena secundaria !@ Agrega métricas en las que la ciudad no contiene York:
filters=ga:city!@York
=~ Contiene una concordancia para la expresión regular %3D~ Agrega métricas en las que la ciudad empieza por New:
filters=ga:city%3D~%5ENew.*
(%5E es la forma codificada en URL del carácter ^ que delimita un patrón al principio de la cadena.)
!~ No coincide con la expresión regular !~ Agrega métricas en las que la ciudad no empieza por New:
filters=ga:city!~%5ENew.*

Expresiones de filtro

Hay un par de reglas importantes para las expresiones de filtro:

  • Caracteres reservados de URL: los caracteres como & deben codificarse en la URL de la manera habitual.
  • Caracteres reservados: el punto y coma y la coma deben ir precedidas de una barra diagonal inversa cuando aparecen en una expresión.
    • punto y coma \;
    • coma \,
  • Expresiones regulares: también puedes usar expresiones regulares en las expresiones de filtro mediante los operadores =~ y !~. Su sintaxis es similar a las expresiones regulares de Perl y tienen estas reglas adicionales:
    • Longitud máxima de 128: las expresiones regulares de más de 128 caracteres provocan que el servidor devuelva el código de estado 400 Bad Request.
    • Distinguir mayúsculas de minúsculas: la búsqueda de concordancias de expresiones regulares no distingue mayúsculas de minúsculas.

Combinar filtros

Los filtros se pueden combinar con los operadores booleanos OR y AND. Esto permite ampliar de forma efectiva el límite de 128 caracteres de una expresión de filtro.

O

El operador OR se define mediante una coma (,). Tiene prioridad sobre el operador Y. No se puede usar para combinar dimensiones y métricas en la misma expresión.

Ejemplos: (cada uno debe estar codificado en URL)

El país puede ser (Estados Unidos o Canadá):
ga:country==United%20States,ga:country==Canada

Usuarios de Firefox en sistemas operativos (Windows o Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

AND

El operador Y se define mediante un punto y coma (;). El operador O tiene prioridad y se puede usar para combinar dimensiones y métricas en la misma expresión.

Ejemplos: (cada uno debe estar codificado en URL)

El país es Estados Unidos y el navegador es Firefox:
ga:country==United%20States;ga:browser==Firefox

El país es Estados Unidos y el idioma no empieza por "en":
ga:country==United%20States;ga:language!~^en.*

El sistema operativo es (Windows o Macintosh) y el navegador es (Firefox o Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

El país es Estados Unidos y las sesiones son más de cinco:
ga:country==United%20States;ga:sessions>5



segment

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
Opcional.

Para obtener información completa sobre cómo solicitar un segmento en la API de informes centrales, consulta la Guía para programadores de segmentos.

En Referencia de la función de segmentos y Segmentos en el Centro de ayuda puedes consultar una descripción general conceptual de los segmentos.

Dimensiones y métricas permitidas en los segmentos.
En los segmentos no se pueden usar todas las dimensiones y métricas. En Explorador de dimensiones y métricas puedes consultar las dimensiones y las métricas que se permiten en los segmentos.


samplingLevel

samplingLevel=DEFAULT
Opcional.
Utiliza este parámetro para configurar el nivel de muestreo (es decir, el número de sesiones que se usan para calcular el resultado) de una consulta de informe. Los valores permitidos son coherentes con la interfaz web e incluyen:
  • DEFAULT: devuelve una respuesta con un tamaño de muestra que equilibra velocidad y exactitud.
  • FASTER: devuelve una respuesta rápida con un tamaño de muestra menor.
  • HIGHER_PRECISION: devuelve una respuesta más exacta con un tamaño de muestra grande, pero puede provocar que la respuesta sea más lenta.
Si no se indica, se usará el nivel de muestreo DEFAULT.
Consulta en la sección Muestreo la información sobre cómo calcular el porcentaje de sesiones que se han usado para una consulta.

include-empty-rows

include-empty-rows=true
Opcional.
Está establecido en true de forma predeterminada. Si se establece en false, las filas en las que todos los valores de métrica son cero se omiten en la respuesta. Por ejemplo, si incluyes más de una métrica en una consulta, las filas solo se quitan si todos los valores de métrica son cero. Esto puede ser útil al crear una solicitud en la que se espera que el número de filas válidas sea mucho menor que el número de valores de dimensión esperados.

start-index

start-index=10
Opcional.
Si no se proporciona, el índice inicial es 1. Los índices de resultado se basan en 1, es decir, la primera es la 1, no la 0. Utiliza este parámetro como un mecanismo de paginación con el parámetro max-results para los casos en los que totalResults sea superior a 10.000 y quieras recuperar filas indexadas a partir de 10.001.

max-results

max-results=100
Opcional.
Número máximo de filas que se incluirán en la respuesta. Lo puedes usar junto con start-index para recuperar un subconjunto de elementos, o usarlo solo para restringir el número de elementos devueltos, empezando por el primero. Si no se proporciona max-results, la consulta devuelve el máximo predeterminado de 1.000 filas.
La API de informes centrales devuelve un máximo de 10.000 filas por solicitud, independientemente de lo que se haya solicitado. También puede devolver menos filas de las solicitadas, si hay menos segmentos de dimensión de los previstos. Por ejemplo, hay menos de 300 valores posibles para ga:country, por lo que, al segmentar solo por el país, no se pueden obtener más de 300 filas, aunque se haya configurado max-results como un valor más alto.

output

output=dataTable
Opcional.
Utiliza este parámetro para configurar el tipo de salida de los datos de Analytics devueltos en la respuesta. Los valores permitidos son:
  • json: envía la propiedad rows predeterminada en la respuesta, que contiene un objeto JSON.
  • dataTable: envía la propiedad dataTable en la respuesta, que contiene un objeto de tabla de datos object. Este objeto de tabla de datos se puede usar directamente con las visualizaciones de Google Charts.
Si no se indica, se usará la respuesta JSON predeterminada.

fields

fields=rows,columnHeaders(name,dataType)
Opcional.

Especifica los campos que se devolverán en una respuesta parci Si solo utilizas un subconjunto de los campos en la respuesta de la API, puedes usar el parámetro fields para especificar los campos que se incluirán.

El formato del valor del parámetro de solicitud fields se basa libremente en la sintaxis XPath. A continuación se resume la sintaxis admitida.

  • Utiliza una lista separada por comas para seleccionar varios campos.
  • Utiliza a/b para seleccionar un campo b anidado en el campo a; utiliza a/b/c para seleccionar un campo c anidado en b.
  • Utiliza un selector secundario para solicitar un conjunto de campos secundarios específicos de matrices o de objetos incluyendo las expresiones entre paréntesis "( )".
    Por ejemplo, fields=columnHeaders(name,dataType) devuelve solo los campos name y dataType en la matriz columnHeaders. También puedes especificar un campo secundario individual, donde fields=columnHeader(name) equivale a fields=columnHeader/name.

prettyPrint

prettyPrint=false
Opcional.

Devuelve la respuesta con un formato legible si el valor es true. Valor predeterminado: false.


quotaUser

quotaUser=4kh4r2h4
Opcional.

Te permite aplicar cuotas por usuario desde una aplicación orientada al servidor, incluso en aquellos casos en los que no se conoce la dirección IP del usuario. Esto puede ocurrir, por ejemplo, con aplicaciones que ejecutan trabajos cron en App Engine en nombre de un usuario. Puedes elegir cualquier cadena arbitraria que identifique de forma exclusiva a un usuario, pero se limita a 40 caracteres.

Anula userIp si se proporcionan ambos.


Respuesta

Si esta solicitud se realiza correctamente, el cuerpo de respuesta tendrá la siguiente estructura JSON que se define más adelante. Si el parámetro output está configurado como dataTable, la solicitud devuelve un cuerpo de respuesta con la estructura JSON (tabla de datos) definida a continuación.

Nota: El término "resultados" hace referencia a todo el conjunto de filas que coinciden con la consulta, mientras que "respuesta" hace referencia al conjunto de filas devuelto en la página de resultados actual. Pueden ser distintos si el número total de resultados es mayor que el tamaño de página de la respuesta actual, tal como se explica en itemsPerPage.

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Campos de respuesta

Las propiedades de la estructura del cuerpo de respuesta se definen del siguiente modo:

Nombre de propiedad Valor Descripción
kind string Tipo de recurso. El valor es "analytics#gaData".
id string ID de esta respuesta de datos.
query object Este objeto contiene todos los valores que se han pasado como parámetros a la consulta. El significado de cada campo se explica en la descripción de su parámetro de consulta correspondiente.
query.start-date string Fecha de inicio.
query.end-date string Fecha de finalización.
query.ids string ID de tabla único.
query.dimensions[] list Lista de las dimensiones de Analytics.
query.metrics[] list Lista de las métricas de Analytics.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Tiene el valor true de forma predeterminada. Si se le da el valor false, las filas en las que todos los valores de métrica son cero se omiten en la respuesta.
query.sort[] list Lista de métricas o dimensiones por las que se ordenan los datos.
query.filters string Lista separada por comas de filtros de métricas o dimensiones.
query.segment string Segmento de Analytics.
query.start-index integer Índice de inicio.
query.max-results integer Máximo de resultados por página.
startIndex integer Índice inicial de las filas especificadas por el parámetro de consulta start-index. El valor predeterminado es 1.
itemsPerPage integer Número máximo de filas que puede contener la respuesta, independientemente del número real de filas devueltas. Si se especifica el parámetro de consulta max-results, el valor de itemsPerPage es el menor de max-results o de 10.000. El valor predeterminado de itemsPerPage es 1000.
totalResults integer Número total de filas del resultado de consulta, independientemente del número de filas devueltas en la respuesta. En el caso de las consultas que generan un gran número de filas, totalResults puede ser mayor que itemsPerPage. Consulta en Paginación una explicación de totalResults y itemsPerPage para consultas grandes.
startDate string Fecha de inicio de la consulta de datos, tal como se especifica mediante el parámetro start-date.
endDate string Fecha de finalización de la consulta de datos, tal como se especifica mediante el parámetro end-date.
profileInfo object Información sobre la vista (perfil) de la que se han solicitado los datos. Los datos de vista (perfil) están disponibles mediante la API de administración de Google Analytics.
profileInfo.profileId string ID de vista (perfil), como 1174.
profileInfo.accountId string ID de actualización al que pertenece esta vista (perfil), como 30481.
profileInfo.webPropertyId string ID de propiedad web al que pertenece esta vista (perfil), como UA-30481-1.
profileInfo.internalWebPropertyId string ID interno de la propiedad web a la que pertenece esta vista (perfil), como UA-30481-1.
profileInfo.profileName string Nombre de la vista (perfil).
profileInfo.tableId string ID de tabla de la vista (perfil), que consta de "ga:" seguido del ID de vista (perfil).
containsSampledData boolean "True" si la respuesta contiene datos muestreados.
sampleSize string Número de muestras usado para calcular los datos muestreados.
sampleSpace string Tamaño de espacio de muestreo total. Indica el espacio de muestreo disponible total del que se han seleccionado las muestras.
columnHeaders[] list Encabezados de columna en los que se enumeran los nombres de dimensión seguidos de los nombres de métrica. El orden de las dimensiones y las métricas es el mismo que el especificado en la solicitud mediante los parámetros metrics y dimensions. El número de encabezados es el número de dimensiones más el número de métricas.
columnHeaders[].name string Nombre de la dimensión o métrica.
columnHeaders[].columnType string Tipo de columna. Puede ser "DIMENSION" o "METRIC".
columnHeaders[].dataType string Tipo de datos. Los encabezados de columna de dimensión solo tienen el tipo de datos STRING. Los encabezados de columna de métrica tienen tipos de datos para valores de métrica como INTEGER, PERCENT, TIME, CURRENCY, FLOAT, etc. Consulta en la respuesta de la API de metadatos todos los tipos de datos posibles.
totalsForAllResults object Valores totales de las métricas solicitadas, como pares clave-valor de los nombres y los valores de las métricas. El orden de los totales de métricas es el mismo que el orden de métricas especificado en la solicitud.
rows[] list Filas de datos de Analytics, donde cada fila contiene una lista de valores de dimensión seguidos de los valores de métrica. El orden de las dimensiones y las métricas es el mismo que el especificado en la solicitud. Cada fila tiene una lista de N campos, donde N es el número de dimensiones más el número de métricas.
JSON (tabla de datos)
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Campos de respuesta

Las propiedades de la estructura del cuerpo de respuesta se definen del siguiente modo:

Nombre de propiedad Valor Descripción
kind string Tipo de recurso. El valor es "analytics#gaData".
id string ID de esta respuesta de datos.
query object Este objeto contiene todos los valores que se han pasado como parámetros a la consulta. El significado de cada campo se explica en la descripción de su parámetro de consulta correspondiente.
query.start-date string Fecha de inicio.
query.end-date string Fecha de finalización.
query.ids string ID de tabla único.
query.dimensions[] list Lista de las dimensiones de Analytics.
query.metrics[] list Lista de las métricas de Analytics.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean Tiene el valor true de forma predeterminada. Si se le da el valor false, las filas en las que todos los valores de métrica son cero se omiten en la respuesta.
query.sort[] list Lista de métricas o dimensiones por las que se ordenan los datos.
query.filters string Lista separada por comas de filtros de métricas o dimensiones.
query.segment string Segmento de Analytics.
query.start-index integer Índice de inicio.
query.max-results integer Máximo de resultados por página.
startIndex integer Índice inicial de las filas especificadas por el parámetro de consulta start-index. El valor predeterminado es 1.
itemsPerPage integer Número máximo de filas que puede contener la respuesta, independientemente del número real de filas devueltas. Si se especifica el parámetro de consulta max-results, el valor de itemsPerPage es el menor de max-results o de 10.000. El valor predeterminado de itemsPerPage es 1000.
totalResults integer Número total de filas del resultado de consulta, independientemente del número de filas devueltas en la respuesta. En el caso de las consultas que generan un gran número de filas, totalResults puede ser mayor que itemsPerPage. Consulta en Paginación una explicación de totalResults y itemsPerPage para consultas grandes.
startDate string Fecha de inicio de la consulta de datos, tal como se especifica mediante el parámetro start-date.
endDate string Fecha de finalización de la consulta de datos, tal como se especifica mediante el parámetro end-date.
profileInfo object Información sobre la vista (perfil) de la que se han solicitado los datos. Los datos de vista (perfil) están disponibles mediante la API de administración de Google Analytics.
profileInfo.profileId string ID de vista (perfil), como 1174.
profileInfo.accountId string ID de actualización al que pertenece esta vista (perfil), como 30481.
profileInfo.webPropertyId string ID de propiedad web al que pertenece esta vista (perfil), como UA-30481-1.
profileInfo.internalWebPropertyId string ID interno de la propiedad web a la que pertenece esta vista (perfil), como UA-30481-1.
profileInfo.profileName string Nombre de la vista (perfil).
profileInfo.tableId string ID de tabla de la vista (perfil), que consta de "ga:" seguido del ID de vista (perfil).
containsSampledData boolean "True" si la respuesta contiene datos muestreados.
sampleSize string Número de muestras usado para calcular los datos muestreados.
sampleSpace string Tamaño de espacio de muestreo total. Indica el espacio de muestreo disponible total del que se han seleccionado las muestras.
columnHeaders[] list Encabezados de columna en los que se enumeran los nombres de dimensión seguidos de los nombres de métrica. El orden de las dimensiones y las métricas es el mismo que el especificado en la solicitud mediante los parámetros metrics y dimensions. El número de encabezados es el número de dimensiones más el número de métricas.
columnHeaders[].name string Nombre de la dimensión o métrica.
columnHeaders[].columnType string Tipo de columna. Puede ser "DIMENSION" o "METRIC".
columnHeaders[].dataType string Tipo de datos. Los encabezados de columna de dimensión solo tienen el tipo de datos STRING. Los encabezados de columna de métrica tienen tipos de datos para valores de métrica como INTEGER, PERCENT, TIME, CURRENCY, FLOAT, etc. Consulta en la respuesta de la API de metadatos todos los tipos de datos posibles.
totalsForAllResults object Valores totales de las métricas solicitadas, como pares clave-valor de los nombres y los valores de las métricas. El orden de los totales de métricas es el mismo que el orden de métricas especificado en la solicitud.
dataTable object Objeto de tabla de datos que se puede usar con Google Charts.
dataTable.cols[] list Lista de descriptores de columna de las dimensiones seguidas de las métricas. El orden de las dimensiones y las métricas es el mismo que el especificado en la solicitud mediante los parámetros metrics y dimensions. El número de columnas es el número de dimensiones más el número de métricas.
dataTable.cols[].id string ID que se puede usar para hacer referencia a una columna específica (como una alternativa a usar los índices de columna). El ID de dimensión o métrica se utiliza para configurar este valor.
dataTable.cols[].label string Etiqueta de la columna (que se puede mostrar mediante una visualización). El ID de dimensión o métrica se utiliza para configurar este valor.
dataTable.cols[].type string Tipo de datos de esta columna.
dataTable.rows[] list Filas de datos de Analytics con formato de tabla de datos, donde cada fila es un objeto que contiene una lista de valores de celda de las dimensiones seguidas de las métricas. El orden de las dimensiones y las métricas es el mismo que el especificado en la solicitud. Cada celda tiene una lista de N campos, donde N es el número de dimensiones más el número de métricas.

Códigos de error

La API de informes centrales devuelve un código de estado HTTP 200 si una solicitud se realiza correctamente. Si se produce un error durante el procesamiento de una consulta, la API devuelve un código de error y una descripción. Cada aplicación que usa la API de Analytics debe implementar la lógica correcta para la gestión de errores. En la guía de referencia de respuestas de error puedes encontrar información sobre los códigos de error y cómo gestionarlos.

Pruébalo

Puedes probar las consultas de la API de informes centrales.

  • Para ver una lista de combinaciones válidas de métricas y dimensiones en una consulta, introduce valores de muestra correspondientes a los parámetros en el Explorador de consultas. Los resultados de la consulta de muestra se presentan como una tabla con valores para todas las métricas y dimensiones especificadas.

  • Para realizar una solicitud de datos activos y ver la respuesta en formato JSON, prueba el método analytics.data.ga.get en el Explorador de APIs de datos de Google.

Muestreo

Google Analytics calcula ciertas combinaciones de dimensiones y métricas de forma dinámica. Para devolver los datos en un tiempo razonable, es posible que Google Analytics solo procese una muestra de los datos.

Para especificar el nivel de muestreo que se usará en una solicitud, configura el parámetro samplingLevel.

Si una respuesta de la API de informes centrales contiene datos muestreados, el campo de respuesta containsSampledData será true. Además, dos propiedades proporcionan información sobre el nivel de muestreo de la consulta: sampleSize y sampleSpace. Con estos dos valores puedes calcular el porcentaje de sesiones que se han usado para la consulta. Por ejemplo, si sampleSize es 201.000 y sampleSpace es 220.000, el informe se basa en (201.000 / 220.000) * 100 = 91,36% de sesiones.

En Muestreo puedes consultar la descripción general del muestreo y cómo se usa en Google Analytics.


Gestionar resultados con muchos datos

Si prevés que tu consulta devolverá un conjunto de resultados grande, sigue las directrices que se indican a continuación para optimizar tu consulta de la API, evitar errores y minimizar los desbordamientos de la cuota. Ten en cuenta que configuramos una línea base de rendimiento al permitir un máximo de siete dimensiones y de diez métricas en una solicitud de la API. Aunque algunas consultas que especifican grandes cantidades de métricas y dimensiones pueden tardar más en procesarse que otras, es posible que limitar el número de las métricas solicitadas no sea suficiente para mejorar el rendimiento de las consultas. En lugar de ello, puedes utilizar las técnicas siguientes para optimizar el rendimiento.

Reducir las dimensiones por consulta

La API permite especificar un máximo de siete dimensiones en una solicitud. Muchas veces, Google Analytics debe calcular los resultados de estas consultas complejas de forma dinámica. Esta operación puede requerir mucho tiempo si el número de filas resultantes es alto. Por ejemplo, consultar palabras clave por ciudad y hora puede devolver millones de filas de datos. Puedes mejorar el rendimiento reduciendo el número de filas que Google Analytics debe procesar mediante la limitación del número de dimensiones de la consulta.

Dividir la consulta por periodo

En lugar de paginar los resultados con clave de fecha de un periodo grande, considera la posibilidad de crear consultas independientes para una semana (o incluso para un día) cada vez. Como es lógico, en el caso de un conjunto de datos grande, incluso la solicitud de los datos de un solo día podría devolver más resultados de los indicados en max-results, en cuyo caso, no se puede evitar la paginación. Pero, en cualquier caso, si el número de filas coincidentes de la consulta es mayor que max-results, la división del periodo puede reducir el tiempo total para recuperar los resultados. Este planteamiento puede mejorar el rendimiento en consultas de un solo proceso y paralelas.

Paginación

La paginación de los resultados puede ser una forma útil de descomponer grandes conjuntos de resultados en subconjuntos manejables. Con el campo totalResults se indica cuántas filas coincidentes hay, y con itemsPerPage se indica el número máximo de filas que se pueden devolver en el resultado. Si hay una proporción elevada de totalResults e itemsPerPage, es posible que las consultas individuales tarden más de lo necesario. Si solo necesitas un número de filas reducido, por ejemplo, para mostrarlas, puede resultar más práctico configurar un límite explícito en el tamaño de la respuesta mediante el parámetro max-results. No obstante, si tu aplicación necesita procesar un conjunto de resultados grande por completo, solicitar el máximo de filas permitido puede ser más eficaz.

Usar gzip

Una forma sencilla y cómoda de reducir el ancho de banda necesario para cada solicitud consiste en habilitar la compresión gzip. Aunque esto requiere tiempo de CPU adicional para descomprimir los resultados, la compensación con los costes de red normalmente hace que merezca la pena. Para recibir una respuesta con codificación gzip debes hacer dos cosas: establecer un encabezado Accept-Encoding y modificar tu user-agent para que incluya la cadena gzip. A continuación, te mostramos un ejemplo de encabezados HTTP con formato correcto para habilitar la compresión .gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)