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 |
Sí | 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 |
Sí |
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 |
Sí |
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 |
Sí |
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:
|
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
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 id
en el recurso Vista (perfil) de la API de administración de Google Analytics.
start-date
start-date=2009-04-20
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)
.
start-date
es 2005-01-01
.
No hay límite superior para start-date.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
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)
.
end-date
es 2005-01-01
. No hay límite superior para end-date
. 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
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
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
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 los países desde donde más visitan mi sitio web y cuáles son los navegadores que más usan para visitarlo?", 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 "¿Desde qué navegadores recibe más visitas mi sitio web y qué países los usan más para acceder?", puedes crear una consulta con el parámetro siguiente. 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
ometrics
. 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
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.
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 |
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
\,
- punto y coma
- Expresiones regulares: también puedes usar expresiones regulares en las de filtro con 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.
- Longitud máxima de 128: las expresiones regulares de más de 128 caracteres provocan que el servidor devuelva el código de estado
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
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
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.
DEFAULT
.include-empty-rows
include-empty-rows=true
start-index
start-index=10
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
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.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
json
: envía la propiedadrows
predeterminada en la respuesta, que contiene un objeto JSON.dataTable
: envía la propiedaddataTable
en la respuesta, que contiene un objeto de tabla de datos object. Este objeto detabla de datos
se puede usar directamente con las visualizaciones de Google Charts.
fields
fields=rows,columnHeaders(name,dataType)
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; utilizaa/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 camposname
ydataType
en la matrizcolumnHeaders
. También puedes especificar un campo secundario individual, dondefields=columnHeader(name)
equivale afields=columnHeader/name
.
prettyPrint
prettyPrint=false
Devuelve la respuesta con un formato legible si el valor es true
.
Valor predeterminado: false
.
quotaUser
quotaUser=4kh4r2h4
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.
{
"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 . |
selfLink |
string |
Enlace a esta página de resultados correspondiente a esta consulta de datos. |
previousLink |
string |
Enlace a la página de resultados anterior correspondiente a esta consulta de datos. |
nextLink |
string |
Enlace a la página de resultados siguiente correspondiente a esta consulta de datos. |
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. |
{
"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 . |
selfLink |
string |
Enlace a esta página de resultados correspondiente a esta consulta de datos. |
previousLink |
string |
Enlace a la página de resultados anterior correspondiente a esta consulta de datos. |
nextLink |
string |
Enlace a la página de resultados siguiente correspondiente a esta consulta de datos. |
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.
Paginar
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 el formato correcto para habilitar la compresión .gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)