En este documento, se proporciona la referencia completa para la consulta y la respuesta de la API de informes de embudos multicanales.
Introducción
La API de Multi-Channel Funnels Reporting te permite solicitar datos de informes de Embudos multicanales de Google Analytics. Cada informe consta de estadísticas derivadas de los datos que el código de seguimiento envía a Analytics, organizadas como dimensiones y métricas. Si eliges tus propias combinaciones de dimensiones y métricas, puedes usar la API de Reporting para crear informes personalizados que se adapten a tus propias especificaciones.
La API contiene un solo método que solicita datos de informes: report.get. Con este método, proporcionas el ID de la tabla que corresponde a la vista (perfil) de la que deseas recuperar datos. Además, debes especificar lo siguiente:
- Una combinación de dimensiones y métricas.
- Un período.
- Un conjunto de parámetros de opción que controla qué datos se muestran
La API permite que el método report.get esté disponible en un extremo de REST: https://www.googleapis.com/analytics/v3/data/mcf. En la siguiente sección, se muestra una solicitud de muestra y se describe cada uno de los parámetros.
Solicitud
La API proporciona un método único para solicitar datos:
analytics.data.mcf.get()
La API también se puede consultar como un extremo de REST:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
Cada parámetro de consulta de URL especifica un parámetro de consulta de la API que debe estar codificado como URL.
Todas las solicitudes a la API de informes de embudos multicanales se deben autorizar, preferentemente a través de OAuth 2.0.
Resumen de los parámetros de consulta
En la siguiente tabla, se resumen todos los parámetros de consulta que acepta la API de informes de embudos multicanales. 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 mcf:totalConversions,mcf:totalConversionValue.
Una consulta válida debe especificar al menos una métrica. |
dimensions |
string |
no | Una lista de dimensiones separadas por comas para tu informe de Embudos multicanales, como mcf:source,mcf:keyword. |
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. |
samplingLevel |
string |
no | Indica el nivel de muestreo deseado. Valores permitidos:
|
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 | Número máximo de filas que se va a incluir en la respuesta. |
Detalles de los parámetros de consulta
ids
ids=ga:12345
ga: con el ID de vista (perfil) del informe. Puedes recuperar el ID de vista (perfil) de tu informe 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=2011-10-01
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).
start-date válido más antiguo es 2011-01-01.
No hay una restricción de límite máximo para un start-date.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=2011-10-31
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).
end-date válido más antiguo es 2005-01-01. No hay una restricción de límite superior para un end-date. 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=mcf:source,mcf:keyword
El parámetro de dimensiones define las claves de datos principales para tu informe de Embudos multicanales, como mcf:source o mcf:medium.
Utilice dimensiones para segmentar sus métricas de conversión. Por ejemplo, si bien puedes consultar la cantidad total de conversiones de tu sitio, podría ser más interesante preguntar la cantidad de conversiones segmentadas por medio.
En este caso, verás la cantidad de conversiones orgánicas, de referencia, de correo electrónico, 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.
Valores no disponibles
Cuando no se puede determinar el valor de la dimensión, Analytics utiliza la string especial (sin establecer).
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
Son las estadísticas globales de la actividad de los usuarios en tu sitio, como el recuento de conversiones totales o el valor de conversión total.
Si una consulta no tiene un parámetro dimensions, las métricas que se muestran proporcionan valores agregados para el período solicitado, como el valor total de conversión. Sin embargo, cuando se solicitan dimensiones, los valores se segmentan según ese valor.
Por ejemplo, si mcf:totalConversions solicitado con mcf:source muestra las conversiones totales por fuente.
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.
sort
sort=mcf:source,mcf:medium
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 fuentes de conversiones principales y a través de qué medios?”
puedes realizar una consulta con el siguiente parámetro. Primero, se ordena por mcf:source y, luego, por mcf:medium, ambos en orden ascendente:
sort=mcf:source,mcf:medium
Para responder a la pregunta relacionada “¿Cuáles son mis medios de conversión principales y cuáles son mis fuentes?”, puedes realizar una consulta con el siguiente parámetro. Primero, se ordena por mcf:medium y, luego, por mcf:source, ambos en orden ascendente:
sort=mcf:medium,mcf:source
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
dimensionsometrics. 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=mcf:medium%3D%3Dreferral
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 mcf:totalConversions y mcf:source para la vista (perfil) 12134, en la que la dimensión mcf:medium es la string referral:
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
Lee la referencia de la API de Core Reporting para obtener más detalles.
samplingLevel
samplingLevel=DEFAULT
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.
DEFAULT.max-results
max-results=100
Cantidad máxima de filas que se incluirán 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 Multi-Channel Funnels Reporting muestra un máximo de 10,000 filas
por solicitud, independientemente de la cantidad que solicites. 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 mcf:medium, por lo que, cuando segmentas solo por medio, no podrás obtener más de 300 filas, incluso si configuras max-results en un valor más alto.
Respuesta
Si se ejecuta de forma correcta, esta solicitud muestra un cuerpo de respuesta con la estructura JSON 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.
Formato de la respuesta
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
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#mcfData". |
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.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.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
El índice inicial de las filas. El valor predeterminado es 1. |
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.
|
selfLink |
string |
Vínculo a esta página de resultados para esta consulta de datos. |
previousLink |
string |
Vínculo a la página anterior de resultados de esta consulta de datos. |
nextLink |
string |
Vínculo a la página siguiente de los resultados de esta consulta de datos. |
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" o "MCF_SEQUENCE" como tipo de datos.
Los encabezados de las columnas de métricas tienen tipos de datos para los valores de métricas, como "INTEGER", "DOUBLE", "CURRENCY", etcétera. |
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 informes, en las que cada fila contiene una lista de objetos Un objeto Un
{
"primitiveValue": "2183"
}
Un
{
"conversionPathValue": [
{
"interactionType" : "CLICK",
"nodeValue" : "google"
},
{
"interactionType" : "CLICK",
"nodeValue" : "google"
}
]
}
|
Códigos de error
La API de Multi-Channel Funnels 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
Usa el Explorador de APIs que aparece a continuación para llamar a este método con los datos en tiempo real y ver la respuesta.
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 informes de MCF contiene datos de 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)