Publicado el 7 de febrero de 2023. Última actualización el 11 de abril de 2025.
En esta guía, se presenta el extremo de la API de History del Informe de UX de Chrome (CrUX) , que proporciona series temporales de datos de rendimiento web. Estos datos se actualizan semanalmente y te permiten ver aproximadamente 6 meses de historial, con 40 puntos de datos separados por una semana.
Cuando se usa con las actualizaciones diarias del extremo de la API de CrUX, ahora puedes ver rápidamente los datos más recientes y lo que sucedió anteriormente, lo que la convierte en una herramienta poderosa para ver los cambios en las páginas web a lo largo del tiempo.
Prueba la API en esta página
Consulta la API de CrUX diaria
Para resumir un artículo anterior sobre la API de CrUX, puedes obtener una instantánea de los datos de campo para un origen determinado de la siguiente manera:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
Esta instantánea incluye valores de densidad de histograma y valores de percentiles para un período de recopilación determinado de 28 días, en este caso, del 27 de diciembre de 2022 al 23 de enero de 2023.
Consulta la API de History de CrUX
Para llamar al extremo del historial, cambia queryRecord en la URL por queryHistoryRecord en el comando curl. Usar la misma
clave de API de CrUX que para la llamada anterior funcionará.
collectionPeriodCount especifica la cantidad de entradas de series temporales que se mostrarán; el máximo es 40. Si no se especifica, el valor predeterminado es 25.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'
La forma general de una respuesta es similar, pero hay muchos más datos. En lugar de un solo punto de datos, ahora hay series temporales para los campos que contienen el percentil 75 (p75) y los valores de densidad del histograma.
{
"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 }
}
]
}
}
En este ejemplo, la serie temporal densities para el bucket de 0 a 2,500 ms de la
métrica de Largest Contentful Paint (LCP) es
[0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Cada una de estas densidades se
observó durante la entrada collectionPeriods correspondiente. Por ejemplo, la quinta densidad, 0.9183, fue la densidad del quinto período de recopilación, que finalizó el 3 de septiembre de 2022, y 0.9187 fue la densidad en el período que finalizó la semana siguiente.
En otras palabras, al interpretar las últimas entradas de series temporales en el ejemplo de web.dev, se descubrió que, del 14 de agosto de 2022 al 10 de septiembre de 2022, el 91.87% de las cargas de página tenían valores de LCP inferiores a 2,500 ms, el 5.27% tenía valores entre 2,500 ms y 4,000 ms, y el 2.85% tenía valores superiores a 4,000 ms.
Del mismo modo, hay una serie temporal para los valores de p75: el LCP p75 del 14 de agosto de 2022 al 10 de septiembre de 2022 fue 1377. Esto significa que, para este período de recopilación, el 75% de las experiencias del usuario tenían un LCP inferior a 1,377 ms y el 25% de las experiencias del usuario tenían un LCP superior a 1,377 ms.
Si bien el ejemplo solo muestra 6 entradas de series temporales y períodos de recopilación,
las respuestas de la API proporcionan 25 entradas de series temporales de forma predeterminada y un máximo de
40, cuando se especifica "collectionPeriodCount": 40 en la solicitud. Dado que las
fechas de finalización de cada uno de estos períodos de recopilación son sábados que están separados por 7 días
con "collectionPeriodCount": 40, esto abarca 10 meses.
En cualquier respuesta determinada, la longitud de la serie temporal para las densidades de los buckets del histograma y para los valores de p75 será exactamente la misma que la longitud del array en el campo collectionPeriods. Hay una correspondencia uno a uno basada en el índice de estos arrays.
Consulta datos a nivel de la página
Además de los datos a nivel del origen, la API de History de CrUX permite acceder a datos históricos a nivel de la página. Si bien los datos a nivel del origen estaban disponibles anteriormente con el conjunto de datos de CrUX en BigQuery, los datos históricos a nivel de la página solo estaban disponibles si los sitios recopilaban y almacenaban los datos por sí mismos. La nueva API ahora desbloquea esos datos históricos a nivel de la página.
Los datos a nivel de la página se pueden consultar de la misma manera, pero usando url en lugar de origin en la carga útil:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
Los datos históricos a nivel de la página (y del origen) están sujetos a
los mismos requisitos de elegibilidad que el
resto de CrUX, por lo que es posible que las páginas en particular no tengan un registro histórico
completo. En estos casos, los datos "faltantes" se representarán con "NaN" para las
histogramTimeseries densidades y null para percentilesTimeseries. 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).
Visualiza los datos
La forma más sencilla de visualizar los datos es a través de CrUX Vis, una herramienta creada específicamente para demostrar el poder de la API de History de CrUX. Obtén más información en la documentación de CrUX Vis.
Para generar gráficos similares por tu cuenta, creamos un ejemplo Colab. Colab, o Colaboratory, te permite escribir y ejecutar código de Python desde tu navegador. El Colab de la API de History de CrUX (fuente) usa Python para realizar llamadas a la API y graficar los datos.
Este Colab te permite crear gráficos de p75, gráficos de tres buckets, obtener datos en formato tabular y ver el par de solicitud y respuesta para la API de CrUX, completando un breve formulario. No es necesario que seas programador para usarlo, pero puedes consultar el código de Python y modificarlo para crear algo increíble.
Este es solo un ejemplo de cómo usar esta nueva API. Como extremo HTTP basado en JSON, se puede consultar la API desde cualquier tecnología.
Conclusión
Antes de la introducción del endpoint de API de History de CrUX, los propietarios de sitios tenían limitaciones en la información histórica que podían obtener de CrUX. Los datos mensuales a nivel del origen estaban disponibles con BigQuery, pero no los datos semanales ni los datos históricos a nivel de la página. Los propietarios de sitios podían registrar estos datos por sí mismos con la API diaria, pero, a menudo, la necesidad de esto solo se descubría después de una regresión en las métricas.
El objetivo de la introducción de esta API de History de CrUX es que permita a los propietarios de sitios comprender mejor sus métricas cambiantes del sitio y como herramienta de diagnóstico cuando surjan problemas. Si usas la nueva API, puedes enviar comentarios al grupo de Google Chrome UX Report (Discussions).