API de CrUX

La API de CrUX brinda acceso de baja latencia a los datos agregados de la experiencia de usuarios reales con el nivel de detalle de la página y el origen.

Caso de uso común

La API de CrUX permite consultar las métricas de la experiencia del usuario para un URI específico, como "Obtener métricas para el origen https://example.com".

Clave de API de CrUX

Para usar la API de CrUX, se requiere una clave de API de Google Cloud. Puedes crear una en la página Credenciales y aprovisionarla para que la use Chrome UX Report API.

Una vez que tengas una clave de API, tu aplicación podrá agregar el parámetro de consulta key=[YOUR_API_KEY] a todas las URLs de solicitud. Consulta Consultas de ejemplo.

La clave de API en las URL se incorpora de manera segura, por lo que no necesita codificación.

Modelo de datos

En esta sección, se detalla la estructura de los datos en las solicitudes y respuestas.

Registro

Es un fragmento discreto de información sobre una página o sitio. Un registro puede tener datos específicos para un identificador y una combinación específica de dimensiones. Un registro puede contener datos de una o más métricas.

Identificadores

Los identificadores especifican qué registros se deben buscar. En CrUX, estos identificadores son páginas web y sitios web.

Origen

Si el identificador es un origen, se agregan todos los datos presentes en todas las páginas de ese origen. Por ejemplo, supongamos que el origen http://www.example.com tenía páginas como se indica en este mapa del sitio:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Esto significa que, cuando se consulta el Informe de UX de Chrome con el origen establecido en http://www.example.com, se muestran los datos de http://www.example.com/, http://www.example.com/foo.html y http://www.example.com/bar.html, en conjunto, porque todas esas páginas corresponden a ese origen.

URLs

Si el identificador es una URL, solo se mostrarán los datos de esa URL específica. Si vuelves a observar el mapa del sitio de origen http://www.example.com, haz lo siguiente:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Si el identificador se establece en URL con el valor de http://www.example.com/foo.html, solo se mostrarán los datos de esa página.

Dimensiones

Las dimensiones identifican un grupo específico de datos con el que se agrega un registro. Por ejemplo, un factor de forma de PHONE indica que el registro contiene información sobre las cargas que se realizaron en un dispositivo móvil. Cada dimensión tendrá una cierta cantidad de valores y, implícitamente, la falta de especificación de esa dimensión hará que esta se agregue a todos los valores. Por ejemplo, si no especificas ningún factor de forma, se indica que el registro contiene información sobre las cargas que se realizaron en cualquier factor de forma.

Factor de forma

Es la clase de dispositivo que el usuario final usó para navegar a la página. Esta es una clase general de dispositivo dividida en PHONE, TABLET y DESKTOP.

Tipo de conexión real

Tipo de conexión real es la calidad de conexión estimada del dispositivo cuando se navega a la página. Esta es una clase general dividida en offline, slow-2G, 2G, 3G y 4G.

Métrica

Informamos las métricas como agregaciones estadísticas, en histogramas, percentiles y fracciones.

Los valores de punto flotante se redondean a 4 decimales (ten en cuenta que las métricas cumulative_layout_shift se codifican como doble como cadena, por lo que no se consideran números de punto flotante y se informan con 2 decimales dentro de la cadena).

Histograma

Cuando las métricas se expresan en un histograma, mostramos los porcentajes de cargas de página que corresponden a rangos particulares para esa métrica.

Un histograma simple de tres discretizaciones para una métrica de ejemplo se ve así:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Estos datos indican que, para el 38.18% de las cargas de páginas, la métrica de ejemplo se midió entre 0 ms y 1,000 ms. Las unidades de la métrica no se encuentran en este histograma, en este caso, supondremos que son milisegundos.

Además, el 49.91% de las cargas de páginas vieron un valor de métrica de entre 1,000 ms y 3,000 ms, y el 11.92% vio un valor superior a 3,000 ms.

Percentiles

Las métricas también pueden contener percentiles que pueden ser útiles para análisis adicionales. Informamos los valores de métricas específicas en el percentil determinado para esa métrica. Se basan en el conjunto completo de datos disponibles y no en los datos discretizados finales, por lo que no coinciden necesariamente con un percentil interpolado que se basa en el histograma discreto final.

{
  "percentiles": {
    "p75": 2063
  }
}

En este ejemplo, al menos el 75% de las cargas de páginas se midieron con el valor de métrica <= 2063.

Nota: Los valores de cada percentil se derivan de forma sintética, lo que no implica que ningún usuario haya experimentado realmente el valor indicado, sino solo que algunos porcentajes de las cargas de páginas experimentaron un valor de métrica inferior al valor especificado.

Fracciones

Las fracciones indican los porcentajes de cargas de páginas que se pueden etiquetar de una manera determinada. En este caso, los valores de las métricas son estas etiquetas.

Por ejemplo, la métrica form_factors consta de un objeto fractions que enumera el desglose de factores de forma (o dispositivos) que abarca la consulta proporcionada:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

En este caso, el 3.77% de las cargas de páginas se midieron en una computadora de escritorio, el 2.88% en una tablet y el 93.35% en un teléfono, es decir, el 100% en total.

Tipos de valores de métricas

Nombre de la métrica de la API de CrUX	Tipo de datos	Unidades métricas	Agregaciones estadísticas	Documentación
cumulative_layout_shift	2 decimales, con codificación doble como cadena	sin unidades	histograma con tres discretizaciones, percentiles con p75	cls
first_contentful_paint	int	milésimas de segundo	histograma con tres discretizaciones, percentiles con p75	FFC
first_input_delay (obsoleto)	int	milésimas de segundo	histograma con tres discretizaciones, percentiles con p75	FD
interaction_to_next_paint	int	milésimas de segundo	histograma con tres discretizaciones, percentiles con p75	inp
largest_contentful_paint	int	milésimas de segundo	histograma con tres discretizaciones, percentiles con p75	lcp
experimental_time_to_first_byte	int	milésimas de segundo	histograma con tres discretizaciones, percentiles con p75	ttfb
form_factors	Doble posición de 4 decimales	porcentaje	asignación del factor de forma a la fracción	factores de forma
navigation_types	Doble posición de 4 decimales	porcentaje	asignación del tipo de navegación a fracción	tipos de navegación
round_trip_time	int	milésimas de segundo	percentiles con p75	rtt

Asignación de nombres de métricas de BigQuery

Nombre de la métrica de la API de CrUX	Nombre de la métrica de BigQuery
cumulative_layout_shift	layout_instability.cumulative_layout_shift
first_contentful_paint	first_contentful_paint
first_input_delay	first_input.delay
interaction_to_next_paint	interaction_to_next_paint
largest_contentful_paint	largest_contentful_paint
experimental_time_to_first_byte	experimental.time_to_first_byte
navigation_types	navigation_types
form_factors	N/A
round_trip_time	N/A

Nota: En BigQuery de CrUX, las densidades de histogramas suman un 100% por origen en todos los factores de forma, por lo que la métrica form_factors que admitimos en la API se expresa como las densidades de histogramas de first_contentful_paint.

Período de recolección

A partir de octubre de 2022, la API de CrUX contiene un objeto collectionPeriod con los campos firstDate y endDate que representan las fechas de inicio y finalización de la ventana de agregación. Por ejemplo:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

Esto permite comprender mejor los datos y determinar si aún se actualizaron para ese día o si muestran los mismos datos de ayer.

Ten en cuenta que la API de CrUX tiene aproximadamente dos días de retraso con respecto a la fecha de hoy, ya que espera a que se completen los datos del día, y requiere un tiempo de procesamiento para estar disponible en la API. Se utiliza la zona horaria estándar del Pacífico (PST) sin cambios para el horario de verano.

Consultas de ejemplo

Las consultas se envían como objetos JSON mediante una solicitud POST a https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" con datos de consulta como un objeto JSON en el cuerpo de POST:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Por ejemplo, se puede llamar desde curl con la siguiente línea de comandos (reemplaza API_KEY por tu clave):

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

Nota: El ejemplo anterior es para sistemas basados en macOS o Linux, incluida la shell de Git BASH para Windows. Otros sistemas pueden requerir pequeñas modificaciones. Por ejemplo, la línea de comandos cmd.exe no permite comillas simples para parámetros, ni las continuaciones de línea (\), por lo que requiere el uso de comillas dobles (escapar las comillas internas según corresponda con \") y, además, usar una sola línea.

Los datos a nivel de la página están disponibles a través de la API si se pasa una propiedad url en la consulta, en lugar de origin:

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Si no se establece la propiedad metrics, se mostrarán todas las métricas disponibles:

• cumulative_layout_shift
• first_contentful_paint
• first_input_delay (obsoleto)
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (solo se informa si no se especifica formFactor en la solicitud)

Si no se proporciona un valor de formFactor, los valores se agregarán en todos los factores de forma.

Consulta Cómo usar la API de Chrome UX Report para ver más ejemplos de consultas.

Canalización de datos

El conjunto de datos de CrUX se procesa a través de una canalización para consolidar, agregar y filtrar los datos antes de que estén disponibles con la API.

El promedio móvil

Los datos del Informe sobre la UX de Chrome son un promedio móvil de 28 días de métricas agregadas. Esto significa que los datos que se presentan en el Informe de UX de Chrome en un momento dado son, en realidad, datos de los últimos 28 días agregados.

Esto es similar a cómo el conjunto de datos de CrUX en BigQuery agrega los informes mensuales.

Actualizaciones diarias

Los datos se actualizan diariamente alrededor de las 4:00 a.m. UTC. No existe un Acuerdo de Nivel de Servicio para los horarios de actualización. Se ejecuta sobre la base del mejor esfuerzo todos los días.

Precaución: Los datos no diferirán en el mismo día después de que se hayan actualizado alrededor de las 4:00 UTC; las llamadas repetidas producirán los mismos resultados.

Esquema

Hay un solo extremo para la API de CrUX que acepta solicitudes HTTP POST. La API muestra un record que contiene uno o más metrics correspondientes a los datos de rendimiento sobre el origen o la página solicitados.

Solicitud HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

La URL usa la sintaxis de la transcodificación gRPC.

Cuerpo de la solicitud

El cuerpo de la solicitud debe contener datos con la siguiente estructura:

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

Campos
effectiveConnectionType	string El tipo de conexión efectiva es una dimensión de consulta que especifica la clase de red efectiva a la que deben pertenecer los datos del registro. Este campo usa los valores ["offline", "slow-2G", "2G", "3G", "4G"] que se especifican en la especificación de la API de Network Information Nota: Si no se especifica un tipo de conexión eficaz, se mostrará un registro especial con datos agregados de todos los tipos de conexiones efectivas.
formFactor	enum (FormFactor) El factor de forma es una dimensión de consulta que especifica la clase de dispositivo a la que deben pertenecer los datos del registro. En este campo, se usan los valores DESKTOP, PHONE o TABLET. Nota: Si no se especifica ningún factor de forma, se mostrará un registro especial con datos agregados de todos los factores de forma.
metrics[]	string Las métricas que se deben incluir en la respuesta. Si no se especifica ninguna, se mostrarán las métricas encontradas. Valores permitidos: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Campo de unión url_pattern. El url_pattern es el identificador principal para una búsqueda de registro. Puede ser solo una de las siguientes opciones:
origin	string El "origen" url_pattern hace referencia a un patrón de URL que es el origen de un sitio web. Ejemplos: "https://example.com", "https://cloud.google.com"
url	string El url_pattern url hace referencia a un patrón de URL que es cualquier URL arbitraria. Ejemplos: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Por ejemplo, para solicitar los valores de procesamiento de imagen con contenido más grandes en computadoras para la página principal de la documentación para desarrolladores de Chrome, haz lo siguiente:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Cuerpo de la respuesta

Las solicitudes exitosas muestran respuestas con un objeto record y urlNormalizationDetails en la siguiente estructura:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

Por ejemplo, la respuesta al cuerpo de la solicitud de la solicitud anterior podría ser la siguiente:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

Clave

Key define todas las dimensiones que identifican este registro como únicas.

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

Campos
formFactor	enum (FormFactor) El factor de forma es la clase de dispositivo que usaron todos los usuarios para acceder al sitio con este registro. Si no se especifica el factor de forma, se mostrarán los datos agregados de todos los factores de forma.
effectiveConnectionType	string El tipo de conexión efectiva es la clase de conexión general que experimentaron todos los usuarios para este registro. Este campo usa los valores ["offline", "slow-2G", "2G", "3G", "4G"], como se especifica en: https://wicg.github.io/netinfo/#effective-connection-types Si no se especifica el tipo de conexión efectiva, se mostrarán los datos agregados de todos los tipos de conexiones efectivas.
Campo de unión url_pattern. El patrón de URL es la URL a la que se aplica el registro. Las direcciones (url_pattern) solo pueden ser una de las siguientes opciones:
origin	string origin especifica el origen para el que se utiliza este registro. Nota: Cuando se especifica un origin, los datos de las cargas con este origen en todas las páginas se agregan a los datos de la experiencia del usuario a nivel del origen.
url	string url especifica una URL específica para la que es este registro. Nota: Cuando se especifica un url, solo se agregan los datos de esa URL específica.

Métricas

Un metric es un conjunto de datos agregados de la experiencia del usuario para una sola métrica de rendimiento web, como el primer procesamiento de imagen con contenido. Puede contener un histograma resumido del uso real de Chrome como una serie de bins, datos de percentiles específicos (como p75) o fracciones etiquetadas.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

o

{
  "fractions": {
    object (Fractions)
  }
}

Campos
histogram[]	object (Bin) Es el histograma de las experiencias del usuario para una métrica. El histograma tendrá al menos un intervalo y las densidades de todos los discretizaciones sumarán ~1.
percentiles	object (Percentiles) Percentiles comunes útiles de la métrica. El tipo de valor de los percentiles será el mismo que el de las discretizaciones de histogramas.
fractions	object (Fractions) Este objeto contiene fracciones etiquetadas, que suman ~1. Las fracciones se redondean con 4 decimales.

Depósito

Una bin es una parte discreta de los datos que se extiende de principio a fin, o si no se proporciona ningún final desde el principio hasta el infinito positivo.

Los valores de inicio y finalización de una discretización se proporcionan en el tipo de valor de la métrica que representa. Por ejemplo, el primer procesamiento de imagen con contenido se mide en milisegundos y se expone como int., por lo tanto, sus discretizaciones métricas usarán int32s para sus tipos de inicio y finalización. Sin embargo, el cambio de diseño acumulativo se mide en decimales sin unidades y se expone como un decimal codificado como una cadena. Por lo tanto, sus discretizaciones métricas usarán cadenas para su tipo de valor.

{
  "start": value,
  "end": value,
  "density": number
}

Campos
start	(integer | string) El inicio es el comienzo de la discretización de datos.
end	(integer | string) Fin es el final de la discretización de datos. Si el final no se propaga, la discretización no tiene fin y es válida desde el principio hasta +inf.
density	number Es la proporción de usuarios que experimentaron el valor de esta discretización para la métrica determinada. Las densidades se redondean a 4 decimales.

Percentiles

Percentiles contiene valores sintéticos de una métrica en un percentil estadístico determinado. Se usan para estimar el valor de una métrica según la experiencia de un porcentaje de usuarios del total de usuarios.

{
  "P75": value
}

Campos
p75	(integer | string) El 75% de las cargas de páginas experimentaron esta métrica con este valor o menos.

Fracciones

Fractions contiene fracciones etiquetadas que suman ~1. Cada etiqueta describe una carga de página de alguna manera, por lo que las métricas representadas de esta manera pueden pensar que producen valores distintos en lugar de valores numéricos, y las fracciones expresan la frecuencia con la que se midió un valor distinto particular.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Al igual que los valores de densidad en discretizaciones de histogramas, cada fraction es un número 0.0 <= value <= 1.0 y suman alrededor de 1.0.

UrlNormalization

Es un objeto que representa las acciones de normalización que se realizan para normalizar una URL y aumentar las probabilidades de que la búsqueda se realice correctamente. Estos son cambios automáticos simples que se realizan cuando se sabe que falla el url_pattern proporcionado. No se controlan acciones complejas, como seguir redireccionamientos.

{
  "originalUrl": string,
  "normalizedUrl": string
}

Campos
originalUrl	string Es la URL original solicitada antes de cualquier acción de normalización.
normalizedUrl	string La URL después de cualquier acción de normalización. Esta es una URL de experiencia del usuario válida que se podría buscar razonablemente.

Límites de frecuencia

La API de CrUX tiene un límite de 150 consultas por minuto y por proyecto de Google Cloud, lo que se ofrece de forma gratuita. Puedes consultar este límite y tu uso actual en la consola de Google Cloud. Esta cuota generosa debería ser suficiente para la gran mayoría de los casos de uso y no es posible pagar por una cuota mayor.