API de Core Reporting: Guía de referencia

En este documento, se proporciona la referencia completa para la consulta y la respuesta de la versión 3.0 de la API de Core Reporting.

Introducción

Consultas la API de Core Reporting para obtener datos de informes de Google Analytics. Cada consulta requiere un ID de vista (perfil), una fecha de inicio y finalización, y al menos una métrica. También puedes proporcionar parámetros de consulta adicionales, como dimensiones, filtros y segmentos, para definir mejor tu consulta. Consulta la Guía de descripción general para comprender cómo funcionan todos estos conceptos en conjunto.

Solicitud

La API proporciona un método único para solicitar datos:

analytics.data.ga.get()

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

La API también se puede consultar como un extremo de 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 estar codificado como URL.

Resumen de los parámetros de consulta

En la siguiente tabla, se resumen todos los parámetros de consulta que acepta la API de Core Reporting. Haz clic en el nombre de cada parámetro para obtener una descripción detallada.

Nombre Valor Obligatorio Resumen
ids string sí El ID de tabla único con el formato ga:XXXX, en el que XXXX es el ID de vista (perfil) de Analytics del que la consulta recuperará los datos.
start-date string sí Fecha de inicio para recuperar los datos de Analytics. Las solicitudes pueden especificar una fecha de inicio con el formato YYYY-MM-DD o como una fecha relativa (p.ej., today, yesterday o NdaysAgo, donde N es un número entero positivo).
end-date string sí Fecha de finalización para recuperar los datos de Analytics. La solicitud puede especificar una fecha de finalización con el formato YYYY-MM-DD o como una fecha relativa (p.ej., today, yesterday o NdaysAgo, donde N es un número entero positivo).
metrics string sí Una lista de métricas separadas por comas, como ga:sessions,ga:bounces.
dimensions string no Una lista de dimensiones separadas por comas para tus datos de Analytics, como ga:browser,ga:city.
sort string no Una lista de dimensiones y métricas separadas por comas que indica el orden y la dirección de ordenamiento de los datos que se muestran.
filters string no Filtros de dimensión o métrica que restringen los datos que se muestran para tu solicitud.
segment string no Segmenta los datos que se muestran para tu solicitud.
samplingLevel string no Indica el nivel de muestreo deseado. Valores permitidos:
  • DEFAULT: Muestra una respuesta con un tamaño de muestra que equilibra la velocidad y la exactitud.
  • FASTER: Muestra una respuesta rápida con un tamaño de muestra más pequeño.
  • HIGHER_PRECISION: Muestra una respuesta más precisa con un tamaño de muestra grande, pero esto puede hacer que la respuesta sea más lenta.
include-empty-rows boolean no El valor predeterminado es verdadero. Si se configura como falso, las filas en las que todos los valores de la métrica son cero se omitirán de la respuesta.
start-index integer no Primera fila de datos para recuperar, a partir de 1. Utiliza este parámetro como un mecanismo de paginación junto con el parámetro max-results.
max-results integer no La cantidad máxima de filas que se deben incluir en la respuesta.
output string no El tipo de salida deseado para los datos de Analytics que se muestran en la respuesta. Los valores aceptables son json y dataTable. Valor predeterminado: json.
fields string no Selector que especifica un subconjunto de campos para incluir en la respuesta.
prettyPrint string no Muestra una respuesta con sangrías y saltos de línea. false predeterminado.
userIp string no Especifica la dirección IP del usuario final para el que se realiza la llamada a la API. Se usa para limitar el uso por IP.
quotaUser string no Alternativa a userIp en los casos en que la dirección IP del usuario es desconocida.
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 maneja la respuesta Se usa en las solicitudes JSON-P de JavaScript.
key string no Se usa en la autorización de OAuth 1.0a para especificar que tu aplicación obtenga cuota. Por ejemplo: key=AldefliuhSFADSfasdfasdfASdf.

Detalles de los parámetros de consulta

ids

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

fecha de inicio

start-date=2009-04-20
Obligatorio.
Todas las solicitudes de datos de Analytics deben especificar un período. Si no incluyes los parámetros start-date y end-date en la solicitud, el servidor muestra un error. Los valores de fecha pueden ser para una fecha específica mediante el patrón YYYY-MM-DD o relativos 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 start-date válido más antiguo es 2005-01-01. No hay una restricción de límite superior para una fecha de inicio.
Las fechas relativas siempre se relacionan con la fecha actual en el momento de la consulta y se basan en la zona horaria de la vista (perfil) especificada en la consulta.

Ejemplo de período para los últimos 7 días (a partir de ayer) que usa fechas relativas:

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

fecha de finalización

end-date=2009-05-20
Obligatorio.
Todas las solicitudes de datos de Analytics deben especificar un período. Si no incluyes los parámetros start-date y end-date en la solicitud, el servidor muestra un error. Los valores de fecha pueden ser para una fecha específica mediante el patrón YYYY-MM-DD o relativos 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 end-date válido más antiguo es 2005-01-01. No hay una restricción de límite superior para un end-date.
Las fechas relativas siempre se relacionan con la fecha actual en el momento de la consulta y se basan en la zona horaria de la vista (perfil) especificada en la consulta.

Ejemplo de período para los últimos 10 días (a partir de hoy) que usa fechas relativas:

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

dimensions

dimensions=ga:browser,ga:city
Opcional.
El parámetro dimensions desglosa las métricas según criterios comunes, por ejemplo, por ga:browser o ga:city. Si bien puedes consultar la cantidad total de vistas de página de tu sitio, sería más interesante solicitar la cantidad de páginas vistas desglosadas por navegador. En este caso, verás la cantidad de páginas vistas desde Firefox, Internet Explorer, Chrome, etcétera.

Cuando uses dimensions en una solicitud de datos, ten en cuenta las siguientes restricciones:

  • Puedes proporcionar un máximo de 7 dimensiones en cualquier consulta.
  • No puedes enviar una consulta que solo contenga dimensiones; debes combinar cualquier dimensión solicitada con, al menos, una métrica.
  • Solo se pueden consultar ciertas dimensiones en la misma consulta. Usa la herramienta de combinación válida en la Referencia de dimensiones y métricas para ver qué dimensiones se pueden usar en conjunto.

metrics

metrics=ga:sessions,ga:bounces
Obligatorio.
Son las estadísticas globales de la actividad de los usuarios en tu sitio, como los clics o las vistas de página. Si una consulta no tiene un parámetro dimensions, las métricas que se muestran proporcionan valores agregados para el período solicitado, como vistas de página generales o rebotes totales. Sin embargo, cuando se solicitan dimensiones, los valores se segmentan según su valor. Por ejemplo, si ga:pageviews se solicita con ga:country, se muestra el total de vistas de página por país. Cuando solicites métricas, ten en cuenta lo siguiente:
  • Todas las solicitudes deben proporcionar al menos una métrica; una solicitud no puede constar solo de dimensiones.
  • Puedes proporcionar un máximo de 10 métricas para cualquier consulta.
  • La mayoría de las combinaciones de métricas de varias categorías se pueden usar en conjunto, siempre que no se especifiquen dimensiones.
  • Se puede usar una métrica en combinación con otras dimensiones o métricas, pero solo cuando se apliquen combinaciones válidas para esa métrica. Consulta la Referencia de dimensiones y métricas para obtener más detalles.

sort

sort=ga:country,ga:browser
Opcional.

Una lista de métricas y dimensiones que indica el orden y la dirección de ordenamiento de los datos mostrados.

  • El orden de orden se especifica de izquierda a derecha de las métricas y dimensiones enumeradas.
  • La direction de orden se establece de forma predeterminada en ascendente y se puede cambiar a descendente usando un prefijo de signo menos (-) en el campo solicitado.

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

sort=ga:country,ga:browser

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

Cuando uses el parámetro sort, ten en cuenta lo siguiente:

  • Ordena solo por dimensiones o valores de métricas que hayas usado en los parámetros dimensions o metrics. Si tu solicitud ordena un campo que no se indica en el parámetro de dimensiones o métricas, recibirás un error.
  • De forma predeterminada, las cadenas se ordenan en orden alfabético ascendente, según la configuración regional en-US.
  • De forma predeterminada, los números se muestran en orden ascendente.
  • De forma predeterminada, las fechas se ordenan de forma ascendente por fecha.

filtros

filters=ga:medium%3D%3Dreferral
  1. Sintaxis de filtros
  2. Operadores de filtrado
  3. Cómo filtrar expresiones
  4. Filtros combinados
Opcional.

El parámetro de cadena de consulta filters restringe los datos que muestra la solicitud. Para usar el parámetro filters, proporciona una dimensión o métrica para filtrar, seguida de la expresión de filtro. Por ejemplo, la siguiente consulta solicita ga:pageviews y ga:browser para la vista (perfil) 12134, en la que la dimensión ga:browser comienza con la string 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 restringen las filas que se incluyen (o no) en el resultado. Cada fila del resultado se prueba con el filtro: si el filtro coincide, la fila se conserva y, si no coincide, se descarta la fila.

  • Codificación de URL: Las bibliotecas cliente de la API de Google codifican automáticamente los operadores de filtro.
  • Filtrado de dimensiones: El filtrado se produce antes de que se agreguen las dimensiones, de modo que las métricas que se muestran representen el total solo para las dimensiones relevantes. En el ejemplo anterior, el número de vistas de página sería solo aquellas en las que Firefox es el navegador.
  • Filtrado de métricas: El filtrado de las métricas se produce después de que se agregan.
  • Combinaciones válidas: Puedes filtrar por una dimensión o métrica que no forme parte de la consulta, siempre y cuando todas las dimensiones o métricas de la solicitud y el filtro sean combinaciones válidas. Por ejemplo, es posible que quieras consultar una lista con fecha de las vistas de página y filtrar en un navegador en particular. Consulta la Referencia de dimensiones y métricas para obtener más información.

Sintaxis del filtro


Un solo filtro usa la siguiente forma:

ga:name operator expression

En esta sintaxis:

  • name: Es el nombre de la dimensión o métrica que se usará para filtrar. Por ejemplo: ga:pageviews filtros en la métrica de vistas de página.
  • operador: Define el tipo de coincidencia de filtro que se usará. Los operadores son específicos de las dimensiones o métricas.
  • expresión: Indica los valores que se incluirán o excluirán de los resultados. Las expresiones usan la sintaxis de expresiones regulares.

Operadores de filtro


Hay seis operadores de filtro para dimensiones y seis operadores de filtro para métricas. Los operadores deben estar codificados en formato URL para que se los incluya en las cadenas de consulta de URL.

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

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

Filtros de dimensiones
Operador Descripción Formulario de URL codificada Ejemplo
== Concordancia exacta %3D%3D Métricas agregadas en las que la ciudad es Irvine:
filters=ga:city%3D%3DIrvine
!= No coincide !%3D Métricas agregadas en las que la ciudad no es Irvine:
filters=ga:city!%3DIrvine
=@ Contiene subcadena %3D@ Métricas agregadas en las que la ciudad contiene York:
filters=ga:city%3D@York
!@ No contiene substring !@ Métricas agregadas en las que la ciudad no contiene York:
filters=ga:city!@York
=~ Contiene una coincidencia para la expresión regular. %3D~ Métricas agregadas en las que la ciudad comienza con New:
filters=ga:city%3D~%5ENew.*
(%5E es la URL codificada a partir del carácter ^ que ancla un patrón al principio de la cadena).
!~ No coincide con la expresión regular !~ Métricas agregadas en las que la ciudad no comienza con New:
filters=ga:city!~%5ENew.*

Filtrar expresiones

Existen dos reglas importantes para las expresiones de filtro:

  • Caracteres reservados para URL: Los caracteres como & deben estar codificados en formato URL de la manera habitual.
  • Caracteres reservados: El punto y coma y la coma deben tener un escape de barra inversa cuando aparezcan en una expresión:
    • punto y coma \;
    • coma \,
  • Expresiones regulares: También puedes usar expresiones regulares en expresiones de filtro con los operadores =~ y !~. Su sintaxis es similar a las expresiones regulares de Perl y tienen las siguientes reglas adicionales:
    • Longitud máxima de 128 caracteres: las expresiones regulares de más de 128 caracteres dan como resultado un código de estado 400 Bad Request que muestra el servidor.
    • Distinción entre mayúsculas y minúsculas: La coincidencia de expresiones regulares no distingue entre mayúsculas y minúsculas.

Combinación de filtros

Los filtros se pueden combinar con la lógica booleana OR y AND. Esto te permite extender de manera efectiva el límite de 128 caracteres de una expresión de filtro.

O

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

Ejemplos: (cada uno debe tener codificación 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 AND se define con punto y coma (;). Está precedido por el operador OR y puede usarse para combinar dimensiones y métricas en la misma expresión.

Ejemplos: (cada uno debe tener codificación 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 comienza con "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 mayores que 5:
ga:country==United%20States;ga:sessions>5


segmento

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

Para obtener detalles completos sobre cómo solicitar un segmento en la API de Core Reporting, consulta la Guía para desarrolladores de segmentos.

Para obtener una descripción general conceptual de los segmentos, consulta la Referencia de la función de segmentos y los Segmentos en el Centro de ayuda.

Dimensiones y métricas permitidas en los segmentos.
No todas las dimensiones y métricas se pueden utilizar en los segmentos. Para consultar qué dimensiones y métricas se permiten en los segmentos, visita el Explorador de dimensiones y métricas.

samplingLevel

samplingLevel=DEFAULT
Opcional.
Usa este parámetro para establecer el nivel de muestreo (es decir, la cantidad de sesiones que se usan para calcular el resultado) de una consulta de informes. Los valores permitidos son coherentes con la interfaz web y abarcan lo siguiente:
  • DEFAULT: Muestra una respuesta con un tamaño de muestra que equilibra la velocidad y la exactitud.
  • FASTER: Muestra una respuesta rápida con un tamaño de muestra más pequeño.
  • HIGHER_PRECISION: Muestra una respuesta más precisa con un tamaño de muestra grande, pero esto puede hacer que la respuesta sea más lenta.
Si no se proporciona, se usará el nivel de muestreo DEFAULT.
Consulta la sección Muestreo para obtener detalles sobre cómo calcular el porcentaje de sesiones que se usaron para una consulta.

incluir-filas-vacías

include-empty-rows=true
Opcional.
El valor predeterminado es verdadero. Si se configura como falso, las filas en las que todos los valores de la métrica son cero se omitirán de 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 la métrica son cero. Esto puede ser útil cuando se realiza una solicitud en la que se espera que la cantidad de filas válidas sea mucho menor que la cantidad de valores de dimensión esperados.

start-index

start-index=10
Opcional.
Si no se proporciona, el índice de inicio es 1. (Los índices de resultados se basan en 1; Es decir, la primera fila es la fila 1, no la fila 0). Usa este parámetro como un mecanismo de paginación junto con el parámetro max-results para situaciones en las que totalResults supere las 10,000 y desees recuperar las filas indexadas en 10,001 o más.

max-results

max-results=100
Opcional.
Cantidad máxima de filas que se incluyen en esta respuesta. Puedes combinarlo con start-index para recuperar un subconjunto de elementos, o bien usarlo solo para restringir la cantidad de elementos que se muestran, comenzando por el primero. Si no se proporciona max-results, la consulta muestra el máximo predeterminado de 1,000 filas.
La API de Analytics Core Reporting muestra un máximo de 10,000 filas por solicitud, sin importar cuántas tengas. También puede mostrar menos filas de las solicitadas si no hay tantos segmentos de dimensión como esperas. Por ejemplo, hay menos de 300 valores posibles para ga:country, por lo que, cuando segmentas solo por país, no puedes obtener más de 300 filas, incluso si configuras max-results en un valor más alto.

salida

output=dataTable
Opcional.
Usa este parámetro para configurar el tipo de salida de los datos de Analytics que se muestran en la respuesta. Los valores permitidos son los siguientes:
  • json: Genera la propiedad rows predeterminada en la respuesta, que contiene un objeto JSON.
  • dataTable: Genera una propiedad dataTable en la respuesta, que contiene un objeto Tabla de datos. Este objeto Data Table se puede usar directamente con las visualizaciones de Gráficos de Google.
Si no se proporciona, se usará la respuesta JSON predeterminada.

campos

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

Especifica qué campos se deben mostrar en una respuesta parcial. Si solo usas un subconjunto de los campos en la respuesta de la API, puedes usar el parámetro fields para especificar qué campos incluir.

El formato del valor del parámetro de solicitud de campos se basa de manera general en la sintaxis de XPath. A continuación, se resume la sintaxis admitida.

  • Usa una lista separada por comas para seleccionar varios campos.
  • Usa a/b si quieres seleccionar un campo b anidado dentro del campo a; usa a/b/c para seleccionar un campo c anidado dentro de b.
  • Puedes usar un subselector para solicitar un conjunto de subcampos específicos de objetos o arrays si colocas las expresiones entre paréntesis "( )".
    Por ejemplo: fields=columnHeaders(name,dataType) solo muestra los campos name y dataType en el array columnHeaders. También puedes especificar un solo subcampo, en el que fields=columnHeader(name) equivale a fields=columnHeader/name.

prettyPrint

prettyPrint=false
Opcional.

Muestra la respuesta en un formato legible si es true. Valor predeterminado false.

quotaUser

quotaUser=4kh4r2h4
Opcional.

Te permite aplicar cuotas por usuario desde una aplicación del servidor, incluso cuando se desconoce 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 única a un usuario, pero debe tener un límite de 40 caracteres.

Esto anula userIp si se proporcionan ambos.

Respuesta

Si se ejecuta de forma correcta, esta solicitud muestra un cuerpo de respuesta con la estructura JSON definida a continuación. Si el parámetro de resultado se establece en dataTable, la solicitud muestra un cuerpo de respuesta con la estructura JSON (tabla de datos) definida a continuación.

Nota: El término "resultados" hace referencia al conjunto completo de filas que coinciden con la consulta, mientras que "respuesta" hace referencia al conjunto de filas que se muestran en la página actual de resultados. Pueden ser diferentes si la cantidad total de resultados es mayor que el tamaño de la página para la respuesta actual, 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 la respuesta se definen de la siguiente manera:

Nombre de la propiedad Valor Descripción
kind string Tipo de recurso. El valor es "analytics#gaData".
id string Un ID para esta respuesta de datos.
query object Este objeto contiene todos los valores pasados como parámetros a la consulta. El significado de cada campo se explica en la descripción del 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 dimensiones de Analytics.
query.metrics[] list Lista de métricas de estadísticas.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean El valor predeterminado es verdadero. Si se configura como falso, las filas en las que todos los valores de la métrica son cero se omitirán de la respuesta.
query.sort[] list Es la lista de métricas o dimensiones en las que se ordenan los datos.
query.filters string Lista de filtros de métricas o dimensiones separados por comas.
query.segment string segmento de Analytics.
query.start-index integer Índice de inicio.
query.max-results integer Cantidad máxima de resultados por página.
startIndex integer El índice inicial de las filas que especifica el parámetro de consulta start-index. El valor predeterminado es 1.
itemsPerPage integer La cantidad máxima de filas que puede contener la respuesta, sin importar la cantidad real de filas que se muestran. Si se especifica el parámetro de consulta max-results, el valor de itemsPerPage es el menor de max-results o 10,000. El valor predeterminado de itemsPerPage es 1,000.
totalResults integer El número total de filas en el resultado de la consulta, sin importar el número de filas que se muestran en la respuesta. En el caso de las consultas que generan una gran cantidad de filas, totalResults puede ser mayor que itemsPerPage. Consulta Paging para obtener más explicaciones sobre totalResults y itemsPerPage para consultas grandes.
startDate string Es la fecha de inicio de la consulta de datos, como se especifica en el parámetro start-date.
endDate string Fecha de finalización de la consulta de datos, como se especifica en el parámetro end-date.
profileInfo object Información sobre la vista (perfil) para la que se solicitaron los datos. Los datos de vista (perfil) están disponibles a través de la API de Google Analytics Management.
profileInfo.profileId string ID de vista (perfil), como 1174.
profileInfo.accountId string Es el ID de la cuenta a la que pertenece esta vista (perfil), como 30481.
profileInfo.webPropertyId string Es el ID de propiedad web al que pertenece esta vista (perfil), como UA-30481-1.
profileInfo.internalWebPropertyId string Es el 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 la tabla para la vista (perfil), que consta de "ga:" seguido del ID de la vista (perfil).
containsSampledData boolean Es verdadero si la respuesta contiene datos muestreados.
sampleSize string La cantidad de muestras que se usan para calcular los datos muestreados.
sampleSpace string Indica el tamaño total del espacio de muestreo. Esto indica el tamaño total del espacio de muestras disponible en el que se seleccionaron las muestras.
columnHeaders[] list Encabezados de columna que enumeran los nombres de las dimensiones seguidos de los nombres de las métricas. El orden de las dimensiones y métricas es el mismo que el que se especifica en la solicitud a través de los parámetros metrics y dimensions. La cantidad de encabezados es la cantidad de dimensiones más la cantidad de métricas.
columnHeaders[].name string Es el 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 las columnas de dimensión solo tienen STRING como tipo de datos. Los encabezados de las columnas de métricas tienen tipos de datos para valores de métricas como INTEGER, PERCENT, TIME, CURRENCY, FLOAT, etc. Consulta la respuesta de la API de metadatos para conocer todos los tipos de datos posibles.
totalsForAllResults object Valores totales para las métricas solicitadas como pares clave-valor de nombres y valores de métricas. El orden de los totales de las métricas es el mismo que se especifica en la solicitud.
rows[] list Filas de datos de Analytics, en las que cada fila contiene una lista de valores de dimensión seguidos de los valores de la métrica El orden de las dimensiones y métricas es el mismo que se especifica en la solicitud. Cada fila tiene una lista de N campos, en la que N = la cantidad de dimensiones + la cantidad 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 la respuesta se definen de la siguiente manera:

Nombre de la propiedad Valor Descripción
kind string Tipo de recurso. El valor es "analytics#gaData".
id string Un ID para esta respuesta de datos.
query object Este objeto contiene todos los valores pasados como parámetros a la consulta. El significado de cada campo se explica en la descripción del 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 dimensiones de Analytics.
query.metrics[] list Lista de métricas de estadísticas.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean El valor predeterminado es verdadero. Si se configura como falso, las filas en las que todos los valores de la métrica son cero se omitirán de la respuesta.
query.sort[] list Es la lista de métricas o dimensiones en las que se ordenan los datos.
query.filters string Lista de filtros de métricas o dimensiones separados por comas.
query.segment string segmento de Analytics.
query.start-index integer Índice de inicio.
query.max-results integer Cantidad máxima de resultados por página.
startIndex integer El índice inicial de las filas que especifica el parámetro de consulta start-index. El valor predeterminado es 1.
itemsPerPage integer La cantidad máxima de filas que puede contener la respuesta, sin importar la cantidad real de filas que se muestran. Si se especifica el parámetro de consulta max-results, el valor de itemsPerPage es el menor de max-results o 10,000. El valor predeterminado de itemsPerPage es 1,000.
totalResults integer El número total de filas en el resultado de la consulta, sin importar el número de filas que se muestran en la respuesta. En el caso de las consultas que generan una gran cantidad de filas, totalResults puede ser mayor que itemsPerPage. Consulta Paging para obtener más explicaciones sobre totalResults y itemsPerPage para consultas grandes.
startDate string Es la fecha de inicio de la consulta de datos, como se especifica en el parámetro start-date.
endDate string Fecha de finalización de la consulta de datos, como se especifica en el parámetro end-date.
profileInfo object Información sobre la vista (perfil) para la que se solicitaron los datos. Los datos de vista (perfil) están disponibles a través de la API de Google Analytics Management.
profileInfo.profileId string ID de vista (perfil), como 1174.
profileInfo.accountId string Es el ID de la cuenta a la que pertenece esta vista (perfil), como 30481.
profileInfo.webPropertyId string Es el ID de propiedad web al que pertenece esta vista (perfil), como UA-30481-1.
profileInfo.internalWebPropertyId string Es el 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 la tabla para la vista (perfil), que consta de "ga:" seguido del ID de la vista (perfil).
containsSampledData boolean Es verdadero si la respuesta contiene datos muestreados.
sampleSize string La cantidad de muestras que se usan para calcular los datos muestreados.
sampleSpace string Indica el tamaño total del espacio de muestreo. Esto indica el tamaño total del espacio de muestras disponible en el que se seleccionaron las muestras.
columnHeaders[] list Encabezados de columna que enumeran los nombres de las dimensiones seguidos de los nombres de las métricas. El orden de las dimensiones y métricas es el mismo que el que se especifica en la solicitud a través de los parámetros metrics y dimensions. La cantidad de encabezados es la cantidad de dimensiones más la cantidad de métricas.
columnHeaders[].name string Es el 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 las columnas de dimensión solo tienen STRING como tipo de datos. Los encabezados de las columnas de métricas tienen tipos de datos para valores de métricas como INTEGER, PERCENT, TIME, CURRENCY, FLOAT, etc. Consulta la respuesta de la API de metadatos para conocer todos los tipos de datos posibles.
totalsForAllResults object Valores totales para las métricas solicitadas como pares clave-valor de nombres y valores de métricas. El orden de los totales de las métricas es el mismo que se especifica en la solicitud.
dataTable object Un objeto de tabla de datos que se puede usar con gráficos de Google.
dataTable.cols[] list Una lista de descriptores de columna para las dimensiones seguidas de métricas. El orden de las dimensiones y métricas es el mismo que el que se especifica en la solicitud a través de los parámetros metrics y dimensions. La cantidad de columnas es la cantidad de dimensiones más la cantidad de métricas.
dataTable.cols[].id string Un ID, que se puede usar para hacer referencia a una columna específica (como alternativa al uso de índices de columna). El ID de la dimensión o métrica se usa para establecer este valor.
dataTable.cols[].label string Una etiqueta para la columna (que podría mostrarse mediante una visualización). El ID de la dimensión o métrica se usa para establecer este valor.
dataTable.cols[].type string El tipo de datos para esta columna.
dataTable.rows[] list Filas de datos de Analytics en formato de tabla de datos, en las que cada fila es un objeto que contiene una lista de valores de celdas para las dimensiones seguidas de métricas. El orden de las dimensiones y métricas es el mismo que se especifica en la solicitud. Cada celda tiene una lista de N campos, en la que N = la cantidad de dimensiones + la cantidad de métricas.

Códigos de error

La API de Core Reporting muestra 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 muestra un código de error y una descripción. Cada aplicación que usa la API de Analytics debe implementar la lógica adecuada de manejo de errores. Para obtener detalles sobre los códigos de error y cómo manejarlos, lee la guía de referencia de respuestas de error.

Pruébalo

Puedes probar las consultas a la API de Core Reporting.

  • Si deseas ver las combinaciones válidas de métricas y dimensiones en una consulta, ingresa valores de muestra para los parámetros en el Explorador de consultas. Los resultados de la consulta de muestra se muestran como una tabla con valores de todas las métricas y dimensiones especificadas.

  • Para realizar una solicitud en datos en vivo 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 sobre la marcha. Para mostrar los datos en un tiempo razonable, Google Analytics solo puede procesar una muestra de ellos.

Puedes especificar el nivel de muestreo que se usará en una solicitud mediante la configuración del parámetro samplingLevel.

Si una respuesta de la API de Core Reporting contiene datos de una muestra, el campo de respuesta containsSampledData será true. Además, 2 propiedades proporcionarán información sobre el nivel de muestreo de la consulta: sampleSize y sampleSpace. Con estos 2 valores, puedes calcular el porcentaje de sesiones que se usaron 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 las sesiones.

Consulta Muestreo para obtener una descripción general del muestreo y su uso en Google Analytics.


Maneja resultados de datos de gran tamaño

Si esperas que tu consulta muestre un conjunto de resultados grande, usa los siguientes lineamientos para optimizar tu consulta a la API, evitar errores y minimizar los excesos de cuota. Ten en cuenta que para establecer un modelo de referencia de rendimiento permitimos un máximo de 7 dimensiones y 10 métricas en cualquier solicitud a la API. Aunque algunas consultas que especifican una gran cantidad de métricas y dimensiones pueden tardar más en procesarse que otras, limitar la cantidad de métricas solicitadas puede no ser suficiente para mejorar el rendimiento de las consultas. En su lugar, puedes usar las siguientes técnicas para obtener el mejor rendimiento.

Cómo reducir las dimensiones por consulta

La API permite especificar hasta 7 dimensiones en cualquier solicitud. Muchas veces, Google Analytics debe calcular los resultados de estas consultas complejas sobre la marcha. Esto puede llevar mucho tiempo si la cantidad de filas resultantes es alta. Por ejemplo, realizar consultas de palabras clave y por hora puede coincidir con millones de filas de datos. Para mejorar el rendimiento, reduce la cantidad de filas que Google Analytics debe procesar. Para ello, limita la cantidad de dimensiones en tu consulta.

Divide la consulta por período

En lugar de desplazarte por los resultados con fecha de un período largo, considera formar consultas separadas para una semana (o incluso un día) a la vez. Por supuesto, para un conjunto de datos grande, incluso una solicitud de los datos de un solo día puede mostrar más de max-results, en cuyo caso no se puede evitar la paginación. Sin embargo, en cualquier caso, si la cantidad de filas coincidentes para tu consulta es mayor que max-results, dividir el período puede disminuir el tiempo total para recuperar los resultados. Este enfoque puede mejorar el rendimiento en consultas de un solo subproceso y en paralelo.

Paging

La paginación de los resultados puede ser una manera útil de dividir los conjuntos de resultados grandes en fragmentos administrables. El campo totalResults indica cuántas filas coincidentes existen, y itemsPerPage indica la cantidad máxima de filas que se pueden mostrar en el resultado. Si hay una proporción alta de totalResults a itemsPerPage, es posible que las consultas individuales estén tardando más de lo necesario. Si solo necesitas una cantidad limitada de filas, por ejemplo, para fines de visualización, puede resultarte conveniente establecer un límite explícito en el tamaño de la respuesta mediante el parámetro max-results. Sin embargo, si la aplicación necesita procesar un conjunto grande de resultados en su totalidad, solicitar el máximo de filas permitidas podría ser más eficiente.

Usa gzip

Una forma fácil y conveniente de reducir el ancho de banda necesario para cada solicitud es habilitar la compresión gzip. Aunque esto requiere tiempo de CPU adicional para descomprimir los resultados, la compensación con los costos de red suele hacer que valga la pena. Si quieres recibir una respuesta codificada en gzip, debes establecer un encabezado Accept-Encoding y modificar tu usuario-agente para que contenga la string gzip. A continuación, se muestra un ejemplo de encabezados HTTP formados correctamente para habilitar la compresión gzip:

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