API de informes de embudos multicanal: guía de referencia

En este documento se proporciona la referencia completa de la consulta y la respuesta de la API de informes de embudos multicanal.

Introducción

Con la API de informes de embudos multicanal puedes solicitar datos del informe de embudos multicanal de Google Analytics. Cada informe consta de estadísticas derivadas de los datos que el código de seguimiento devuelve a Analytics organizados como dimensiones y métricas. Si eliges tus propias combinaciones de dimensiones y métricas, puedes usar la API de informes para crear informes personalizados que se ajusten a tus especificaciones.

La API contiene un solo método que solicita los datos de informe: report.get. Con este método, debes proporcionar el ID de tabla que corresponde a la vista (perfil) de la que quieres recuperar los datos. Además, debes especificar lo siguiente:

  • Una combinación de dimensiones y métricas
  • Un periodo
  • Un conjunto de parámetros de opción que controlan qué datos se devuelven.

La API pone el método report.get a dispositivo de un extremo REST: https://www.googleapis.com/analytics/v3/data/mcf. En la sección siguiente se muestra una solicitud de ejemplo y se describe cada uno de los parámetros.

Solicitud

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

analytics.data.mcf.get()

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

Todas las solicitudes a la API de informes de embudos multicanal deben estar autorizadas, preferiblemente mediante OAuth 2.0.

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 de embudos multicanal. Haz clic en cada nombre de parámetro para obtener una descripción detallada.

Nombre Valor Obligatorio Resumen
ids string ID de tabla único con el formato ga:XXXX, donde XXXX es el ID de vista (perfil) de Analytics del que la consulta recuperará los datos.
start-date string Fecha de inicio para recuperar los datos de Analytics. En las solicitudes se puede especificar una fecha de inicio con el formato AAAA-MM-DD o una fecha relativa (por ejemplo, today, yesterday o NdaysAgo donde N es un entero positivo).
end-date string Fecha de finalización para recuperar los datos de Analytics. En la solicitud se puede especificar una fecha de finalización con el formato AAAA-MM-DD o una fecha relativa (por ejemplo, today, yesterday o NdaysAgo donde N es un entero positivo).
metrics string Lista de métricas separadas por comas, como mcf:totalConversions,mcf:totalConversionValue. En una consulta válida se debe especificar al menos una métrica.
dimensions string No Lista de dimensiones separadas por comas del informe de embudos multicanal, como mcf:source,mcf:keyword.
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.
samplingLevel string No Nivel de muestreo deseado. Valores permitidos:
  • DEFAULT: devuelve una respuesta con un tamaño de muestra que equilibra velocidad y exactitud.
  • FASTER: devuelve una respuesta rápida con un tamaño de muestra menor.
  • HIGHER_PRECISION: devuelve una respuesta más exacta con un tamaño de muestra grande, pero puede provocar que la respuesta sea más lenta.
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.

Información de los parámetros de consulta

ids

ids=ga:12345
Obligatorio.
ID único utilizado para recuperar los datos de los embudos multicanal. Este ID es la concatenación del espacio de nombres ga: con el ID de vista (perfil) del informe. Puedes recuperar el ID de vista (perfil) de tu informe 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.

Volver al principio


start-date

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

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

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

Volver al principio


end-date

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

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

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

Volver al principio


dimensions

dimensions=mcf:source,mcf:keyword
Opcional.

El parámetro dimensions define los datos principales keys del informe de embudos multicanal, como mcf:source o mcf:medium. Con el parámetro dimensions puedes segmentar las métricas de conversión. Por ejemplo, aunque puedes solicitar el número total de conversiones en tu sitio, podría ser más interesante solicitar el número de conversiones segmentadas por medio. En este caso, aparecerá el número de conversiones de búsqueda orgánica, referencias, correo electrónico, 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:

Valores no disponibles

Cuando no se puede determinar el valor de la dimensión, Analytics usa la cadena especial (not set).

Volver al principio


metrics

metrics=mcf:totalConversions,mcf:totalConversionValue
Obligatorio.

Estadísticas acumuladas de la actividad de los usuarios en tu sitio, como el número total de conversiones o el valor total de las conversiones. Si una consulta no tiene el parámetro dimensions, las métricas devueltas proporcionan valores acumulados correspondientes al periodo solicitado, como el valor total de las conversiones. Sin embargo, cuando se solicitan las dimensiones, los valores se segmentan por valor de dimensión. Por ejemplo, si se solicita mcf:totalConversions con mcf:source, se devuelve el total de conversiones por fuente.

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.

Volver al principio


sort

sort=mcf:source,mcf:medium
Opcional.

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

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

La ordenación de los resultados de una consulta permite plantear diferentes preguntas sobre los datos. Por ejemplo, para responder a la pregunta "¿Cuáles son mis principales fuentes de conversión y a través de qué medios?" puedes crear una consulta con el parámetro siguiente. Primero ordena por mcf:source y, después, por mcf:medium, ambos en orden ascendente:

sort=mcf:source,mcf:medium

Para responder a la pregunta relacionada "¿Cuáles son mis principales medios de conversión y de qué fuentes provienen?", puedes crear una consulta con el siguiente parámetro. Primero ordena por mcf:medium y, después, por mcf:source, ambos en orden ascendente:

sort=mcf:medium,mcf:source

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

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

Volver al principio


filters

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

El parámetro de cadena de consulta filters limita los datos devueltos en la solicitud. Para usar el parámetro filters, indica una dimensión o una métrica por la que se filtrará, seguida de la expresión de filtro. Por ejemplo, la consulta siguiente solicita mcf:totalConversions y mcf:source de la vista (perfil) 12134, donde la dimensión mcf:medium es la cadena 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

Consulta la Referencia de la API de informes centrales para obtener información.

Volver al principio


samplingLevel

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

Volver al principio


max-results

max-results=100
Opcional.

Número máximo de filas que se incluirán en la respuesta. Lo puedes usar junto con start-index para recuperar un subconjunto de elementos, o usarlo solo para restringir el número de elementos devueltos, empezando por el primero. Si no se proporciona max-results, la consulta devuelve el máximo predeterminado de 1000 filas.

La API de informes de embudos multicanal devuelve un máximo de 10.000 filas por solicitud, independientemente de lo que se haya solicitado. También puede devolver menos filas de las solicitadas, si hay menos segmentos de dimensión de los previstos. Por ejemplo, hay menos de 300 valores posibles para mcf:medium, por lo que, al segmentar solo por el medio, no se pueden obtener más de 300 filas, aunque se haya configurado max-results como un valor más alto.

Volver al principio


Respuesta

Si esta solicitud se realiza correctamente, el cuerpo de respuesta tendrá la siguiente estructura JSON que se define más adelante.

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.

Formato de respuesta

JSON
{
  "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
    ]
  ],
}

Volver al principio

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#mcfData".
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.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.samplingLevel string Requested sampling level.
query.start-index integer Índice inicial de filas. El valor predeterminado es 1.
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 e itemsPerPage para consultas grandes.
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" o "MCF_SEQUENCE". Los encabezados de columna de métrica tienen tipos de datos para los valores de métrica como "INTEGER", "DOUBLE", "CURRENCY", etc.
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 informe, donde cada fila contiene una lista de objetos Mcf.Rows. Esta lista interna representa los valores de dimensión seguidos de los valores de métrica en el mismo orden 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.

Un objeto Mcf.Rows incluye otro objeto que puede ser del tipo primitiveValue o conversionPathValue. Los valores de dimensión pueden ser de cualquiera de los dos tipos, mientras que todos los valores de métrica son del tipo primitiveValue.

Un primitiveValue es una cadena incluida en un objeto. Por ejemplo:


{
  "primitiveValue": "2183"
}

Un conversionPathValue es un objeto incluido en una matriz de objetos, donde cada uno contiene una cadena nodeValue y una cadena interactionType opcional. Por ejemplo:


{
  "conversionPathValue": [
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    },
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    }
  ]
}

Volver al principio

Códigos de error

La API de informes de embudos multicanal 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.

Volver al principio

Pruébalo

Puedes probar las consultas de la API de informes de embudos multicanal.

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

Volver al principio

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 de embudos multicanal 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.

Volver al principio

Procesamiento de resultados con muchos datos

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

Reducir las dimensiones por consulta

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

Dividir la consulta por periodo

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

Paginación

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

Usar gzip

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

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