API de CrUX

La API de CrUX brinda acceso de baja latencia a datos agregados de la experiencia del usuario real con un nivel de detalle de página y origen.

Pruébalo

Caso de uso común

La API de CrUX permite consultar las métricas de experiencia del usuario para un URI específico, como "Obtén 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 aprovisionada para el uso de Chrome UX Report API.

Adquiere y usa una clave de API

También puedes crear una en la página Credenciales.

Una vez que tienes una clave de API, puedes usar tu aplicación para adjuntar el parámetro de consulta key=yourAPIKey a todas las URL de solicitud.

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

Consulta Ejemplos de consultas.

Modelo de datos

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

Grabar

Es una información discreta sobre una página o un sitio. Un registro puede tener datos específicos para un identificador y para 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 las páginas web y los sitios web.

Origen

Cuando el identificador es un origen, todos los datos presentes para todas las páginas de ese origen se agregan juntos. Por ejemplo, supongamos que el origen http://www.example.com tiene páginas como las que se muestran 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 consulte el Informe sobre la UX de Chrome con el origen establecido en http://www.example.com, se devolverán los datos de http://www.example.com/, http://www.example.com/foo.html y http://www.example.com/bar.html, agregados, porque todas esas páginas se encuentran en ese origen.

URL

Cuando el identificador es una URL, solo se devolverán los datos de esa URL específica. Volvamos a mirar el mapa del sitio de origen http://www.example.com:

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 devolverá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, de forma implícita, la falta de especificación de esa dimensión significará que la dimensión se agrega en todos los valores. Por ejemplo, si no se especifica 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 usó el usuario final para navegar a la página. Esta es una clase general de dispositivos dividida en PHONE, TABLET y DESKTOP.

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 son dobles codificadas como una cadena, por lo que no se consideran flotantes 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 se encuentran dentro de rangos particulares para esa métrica.

Un histograma de tres discretizaciones para una métrica de ejemplo se ve de la siguiente manera:

{
  "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ágina, la métrica de ejemplo se midió entre 0 ms y 1,000 ms. Las unidades de la métrica no se incluyen en este histograma. En este caso, supondremos que son milisegundos.

Además, el 49.91% de las cargas de página registraron un valor de métrica entre 1,000 ms y 3,000 ms, y el 11.92% registró 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 valores de métricas específicos en el percentil determinado para esa métrica. Se basan en el conjunto completo de datos disponibles y no en los datos agrupados finales, por lo que no necesariamente coinciden con un percentil interpolado que se basa en el histograma agrupado final.

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

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

Fracciones

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

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

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

En este caso, el 3.77% de las cargas de página se midieron en una computadora de escritorio, el 2.88% en una tablet y el 93.35% en un teléfono, lo que da un total del 100%.

Tipos de valores de métricas

Asignación de nombres de métricas de BigQuery

Período de recopilació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 del período 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 saber si ya se actualizaron para ese día o si se muestran los mismos datos que el día anterior.

El período de recopilación también está disponible en PageSpeed Insights:

Además, el collectionPeriod siempre mostrará 28 días, incluso si los datos no corresponden a los 28 días completos (por ejemplo, si se lanzó una página hace menos de 28 días). El collectionPeriod es el período durante el cual se agregaron los datos de CrUX, no necesariamente el período que representan los datos.

Ejemplos de consultas

Las consultas se envían como objetos JSON con una solicitud POST a https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" con los datos de la consulta como un objeto JSON en el cuerpo de la solicitud 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"]}'

Los datos a nivel de la página están disponibles a través de la API si pasas 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
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (solo se informa si no se especifica formFactor en la solicitud)
• experimental_ad_count (solo se informa para las páginas incluidas en las métricas de anuncios)
• experimental_ad_density (solo se informa para las páginas incluidas en las métricas de anuncios)
• experimental_ad_cpu (solo se informa para las páginas incluidas en las métricas de anuncios)
• experimental_ad_kilobytes (solo se informa para las páginas incluidas en las métricas de anuncios)

Si no se proporciona ningún 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 a través de la API.

El promedio móvil

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

Esto es similar a la forma en que el conjunto de datos de CrUX en BigQuery agrega informes mensuales.

Actualizaciones diarias

Los datos se actualizan diariamente alrededor de las 4 a.m. (UTC). No hay un acuerdo de nivel de servicio para los tiempos de actualización; se ejecuta todos los días de la mejor manera posible.

Esquema

Hay un solo extremo para la API de CrUX que acepta solicitudes HTTP POST. La API devuelve un objeto record que contiene uno o más objetos 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 de gRPC.

Cuerpo de la solicitud

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

{
  "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.
}

Por ejemplo, para solicitar los valores de Largest Contentful Paint para computadoras de 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 devuelven 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 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 único.

{
  "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.
}

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 de resumen del uso de Chrome en el mundo real como una serie de bins, datos de percentiles específicos (como el p75) o fracciones etiquetadas.

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

o

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

Depósito

Un bin es una parte discreta de datos que abarca desde el principio hasta el final o, si no se proporciona un final, desde el principio hasta el infinito positivo.

Los valores de inicio y finalización de un intervalo 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 números enteros, por lo que sus discretizaciones de métricas usarán int32 para sus tipos de inicio y finalización. Sin embargo, los cambios de diseño acumulados se miden en decimales sin unidades y se exponen como un decimal codificado como una cadena, por lo que sus discretizaciones de métricas usarán cadenas para su tipo de valor.

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

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
}

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 se pueden considerar como si produjeran valores distintos en lugar de valores numéricos, y las fracciones expresan con qué frecuencia se midió un valor distinto en particular.

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

Al igual que los valores de densidad en los intervalos del histograma, cada fraction es un número 0.0 <= value <= 1.0, y suman aproximadamente 1.0.

UrlNormalization

Es un objeto que representa las acciones de normalización que se realizaron para normalizar una URL y aumentar las probabilidades de una búsqueda exitosa. Estos son cambios básicos y automatizados que se realizan cuando se sabe que fallará la búsqueda del url_pattern proporcionado. No se controlan las acciones complejas, como seguir redireccionamientos.

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

Límites de frecuencia

La API de CrUX está limitada a 150 consultas por minuto por proyecto de Google Cloud, que se ofrece sin cargo. Este límite y tu uso actual se pueden ver en la consola de Google Cloud. Esta generosa cuota debería ser suficiente para la gran mayoría de los casos de uso, y no es posible pagar por una cuota mayor.