API de historial de CrUX

Fecha de publicación: 7 de febrero de 2023; Última actualización: 11 de abril de 2025

La API de CrUX History proporciona acceso de baja latencia a seis meses de datos históricos de la experiencia del usuario real a nivel de la página y el origen.

Pruébalo

Caso de uso común

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

La API de History sigue la misma estructura que la API de CrUX diaria, excepto que los valores se proporcionan en un array y las claves se etiquetan con nombres en plural (por ejemplo, histogramTimeseries en lugar de histogram o p75s en lugar de p75).

Clave de API de CrUX

Al igual que la API diaria, usar la API de CrUX History requiere una clave de API de Google Cloud aprovisionada para el uso de Chrome UX Report API. Se puede usar la misma clave para las APIs de historial y diarias.

Adquiere y usa una clave de API

O bien crea 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 un dato discreto 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 páginas web y sitios web.

Origen

Cuando el identificador es un origen, todos los datos presentes para todas las páginas de ese origen se agregan. Por ejemplo, supongamos que el origen http://www.example.com tenía páginas como las que se describen 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 de UX de Chrome con el origen establecido en http://www.example.com, se mostrarán los datos de http://www.example.com/, http://www.example.com/foo.html y http://www.example.com/bar.html agregados, ya que todas son páginas de ese origen.

URL

Cuando el identificador sea una URL, solo se mostrarán los datos de esa URL específica. Volvamos a ver el mapa del sitio de origen de 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 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.

Factor de forma

La API de CrUX History solo está disponible agregada por dimensión de factor de forma. Esta es una clase general de dispositivos dividida en PHONE, TABLET y DESKTOP.

Métrica

Registramos las métricas en series temporales de agregaciones estadísticas, que son histogramas, percentiles y fracciones.

Histogramas

Cuando las métricas se expresan en un array de histograma, cada entrada de serie temporal representa el porcentaje de cargas de página para las que la métrica cayó en un intervalo, de forma proporcional a todas. Los datos se presentan en el orden de las fechas del período de recopilación que también muestra la API, en las que el primer punto es el período más antiguo y el último es el período de recopilación más reciente.

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

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
}

Estos datos indican que el 91.90% de las cargas de página experimentaron el valor de la métrica de ejemplo entre 0 ms y 2,500 ms para el primer período de recopilación en el historial, seguido del 92.03%, 91.94%… Las unidades de la métrica no se incluyen en este histograma. En este caso, suponemos que son milisegundos.

Además, el 5.21% de las cargas de página experimentaron el valor de la métrica de ejemplo entre 2,500 ms y 4,000 ms en el primer período de recopilación del historial, y el 2.88% de las cargas de página experimentaron un valor superior a 4,000 ms en el primer período de recopilación del historial.

Percentiles

Las métricas también pueden contener series temporales de percentiles que pueden ser útiles para realizar análisis adicionales.

Los datos se presentan en el orden de las fechas del período de recopilación que también muestra la API, en las que el primer punto es el período más antiguo y el último es el período de recopilación más reciente.

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

Estos percentiles pueden mostrar 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 finales agrupados, por lo que no coinciden necesariamente con un percentil interpolado que se basa en el histograma agrupado final.

Fracciones

Las métricas se pueden expresar como series temporales de fracciones etiquetadas. Cada etiqueta describe una carga de página de una manera particular. Los datos se presentan en el orden de las fechas del período de recopilación que también muestra la API, en las que el primer punto es el período más antiguo y el último es el período de recopilación más reciente.

Ejemplo:

{    
  "fractionTimeseries": {
    "desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
    "phone": {"fractions": [0.6295, 0.7544, 0.8288]},
    "tablet": {"fractions": [0.051, 0.0341, 0.029]}
  }
}

En este ejemplo, el dato más reciente indica que el 14.21% de las cargas de página provinieron de computadoras de escritorio y el 82.88% provinieron de teléfonos.

Tipos de valores de métricas

Como la API de CrUX History usa los mismos tipos de valores de métricas, puedes consultar la documentación diaria de tipos de valores de métricas de la API de CrUX para obtener más detalles.

Elegibilidad de las métricas

Según los criterios de elegibilidad, es posible que un origen o una URL solo sean aptos para algunos de los períodos de recopilación que abarca la API de CrUX History. En estos casos, la API de CrUX History mostrará "NaN" para las densidades histogramTimeseries y null para el percentilesTimeseries de los períodos de recopilación que no tienen datos aptos. El motivo de la diferencia es que las densidades del histograma siempre son números, mientras que los percentiles pueden ser números o cadenas (CLS usa cadenas, incluso si parecen números).

Por ejemplo, si el segundo período no tuviera datos aptos, se mostraría de la siguiente manera:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
  "percentilesTimeseries": {
    "p75s": [1362, null, 1344, 1356, 1366, 1377]
  },
}

En el caso de las URLs o los orígenes que cambian de estado de elegibilidad con el tiempo, es posible que notes muchas entradas faltantes.

Períodos de recopilación

La API de CrUX History contiene un objeto collectionPeriods con un array de campos firstDate y endDate que representan las fechas de inicio y finalización de cada ventana de agregación. Por ejemplo:

    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]

Estos períodos de recopilación están en orden ascendente y representan el período de cada uno de los datos en las otras secciones de la respuesta.

La API de History se actualiza todos los lunes y contiene datos hasta el sábado anterior (según el retraso estándar de 2 días). Contiene los datos de las 40 semanas anteriores (un período de recopilación por semana). De forma predeterminada, se devuelven 25 períodos de recopilación. Para cambiar este comportamiento, establece "collectionPeriodCount" en la solicitud en un número entre 1 y 40.

Como cada período de recopilación contiene los datos agregados de los 28 días anteriores y los períodos de recopilación son semanales, esto significa que se superpondrán. Son similares a un promedio móvil de datos, ya que se incluyen tres semanas de datos en cada período subsiguiente y una semana es diferente.

Consultas de ejemplo

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

Ten en cuenta que se usa queryHistoryRecord en lugar de queryRecord de la API de CrUX diaria.

Un ejemplo de cuerpo es el siguiente:

{
  "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:queryHistoryRecord?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. Para ello, 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 configura 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)

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

Consulta la guía Cómo usar la API de History de CrUX 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 informe de UX de Chrome son un promedio móvil de 28 días de las métricas agregadas. Esto significa que los datos que se presentan en el informe de UX de Chrome en un momento determinado son, en realidad, datos de los últimos 28 días agregados.

La API de History contiene una serie de períodos de recopilación, cada uno de los cuales abarca estos 28 días. Como cada período de recopilación contiene los datos agregados de los 28 días anteriores y los períodos de recopilación son semanales, esto significa que se superpondrán. Son similares a un promedio móvil de datos, ya que se incluyen tres semanas de datos en cada período subsiguiente y una semana es diferente.

Actualizaciones semanales

La API de History se actualiza todos los lunes alrededor de las 04:00 a.m. (UTC) y contiene datos hasta el sábado anterior (según el retraso estándar de 2 días). Contiene los datos de las 40 semanas anteriores (aproximadamente 10 meses), un período de recopilación por semana. Ten en cuenta que, de forma predeterminada, mostramos 25 entradas por serie temporal, pero esto se puede anular si especificas el parámetro de solicitud collectionPeriodCount.

No hay un acuerdo de nivel de servicio para los tiempos de actualización; se ejecuta todos los días según el criterio del mejor esfuerzo.

Esquema

Hay un solo extremo para la API de CrUX History 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:queryHistoryRecord

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

Cuerpo de la solicitud

La API de CrUX History usa cuerpos de solicitud similares a los de la API de CrUX diaria, con un campo "collectionPeriodCount" adicional y opcional:

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

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

Por ejemplo, para solicitar los valores de Largest Contentful Paint para computadoras de la página principal de web.dev, haz lo siguiente:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Esta solicitud similar incluye el campo opcional collectionPeriodCount y generaría 40 entradas de series temporales que proporcionan aproximadamente 10 meses de historial de rendimiento web para el origen https://web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ],
  "collectionPeriodCount": 40
}

Cuerpo de la respuesta

Las solicitudes correctas 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 en la solicitud anterior podría ser la siguiente:

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187, ...
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527, ...
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285, ...
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377, ...
          ]
        }
      }
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }, {
        ...
      }
    ]
  }
}

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 de experiencia del usuario para una sola métrica de rendimiento web, como el primer procesamiento de imagen con contenido. Contiene un histograma de resumen del uso real de Chrome como una serie de bins.

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

o

"fractionTimeseries": {
  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 int, por lo que sus intervalos de métricas usarán int32 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 intervalos de métricas usarán cadenas para su tipo de valor.

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

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 lo experimentó un porcentaje de usuarios de la cantidad total de usuarios.

{
  "P75": value
}

Fracciones

Fractions contiene series temporales de fracciones etiquetadas que suman alrededor de 1 por entrada. 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 valores distintos en lugar de valores numéricos, y las fracciones expresan la frecuencia con la que se midió un valor distinto en particular.

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

Al igual que los valores de densidad en los intervalos de histograma, cada fraction es un número 0.0 <= value <= 1.0 y suman alrededor de 1.0. Cuando la métrica no esté disponible para un período de recopilación en particular, la entrada correspondiente será “NaN” en todos los arrays de fracciones.

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 básicos y automatizados que se realizan cuando se busca el url_pattern proporcionado que se sabe que fallará. No se controlan las acciones complejas, como seguir redireccionamientos.

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

Límites de frecuencia

La API de CrUX History comparte el mismo límite con la API de CrUX para 150 consultas por minuto por proyecto de Google Cloud para cualquiera de las APIs, que se ofrece sin cargo. Puedes ver 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.