Fecha de publicación: 7 de febrero de 2023; última actualización: 11 de abril de 2025
En esta guía, se presenta el extremo de la API de Chrome UX Report (CrUX) History, que proporciona series temporales de datos de rendimiento web. Estos datos se actualizan semanalmente y te permiten ver el historial de aproximadamente 6 meses, con 40 puntos de datos separados por una semana.
Cuando se usa con las actualizaciones diarias del endpoint de la API de CrUX original, 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
Como se mencionó en un artículo anterior sobre la API de CrUX, puedes obtener una instantánea de los datos de campo para un origen en particular 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 del histograma y valores de percentiles para un período de recopilación específico de 28 días, en este caso, del 27 de diciembre de 2022 al 23 de enero de 2023.
Consulta la API de CrUX History
Para llamar al extremo del historial, cambia queryRecord en la URL por queryHistoryRecord en el comando curl. Usar la misma clave de la API de CrUX que para la llamada anterior funcionará.
collectionPeriodCount especifica la cantidad de entradas de series temporales que se devolverá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 intervalo de 0 a 2,500 ms de la métrica 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 del período que finalizó la semana siguiente.
En otras palabras, al interpretar las últimas entradas de la serie temporal en el ejemplo de https://web.dev, se descubrió que, desde el 14 de agosto de 2022 hasta el 10 de septiembre de 2022, el 91.87% de las cargas de página tuvieron valores de LCP inferiores a 2,500 ms, el 5.27% tuvo valores entre 2,500 ms y 4,000 ms, y el 2.85% tuvo valores superiores a 4,000 ms.
Del mismo modo, hay una serie temporal para los valores del percentil 75: el LCP del percentil 75 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 tuvieron un LCP inferior a 1,377 ms y el 25% de las experiencias del usuario tuvieron un LCP superior a 1,377 ms.
Si bien el ejemplo solo enumera 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 con 7 días de diferencia, con "collectionPeriodCount": 40 se cubren 10 meses.
En cualquier respuesta, la longitud de la serie temporal para las densidades de discretización del histograma y para los valores de p75 será exactamente la misma que la longitud del array en el campo collectionPeriods: Existe 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 CrUX History permite acceder a los datos históricos a nivel de la página. Si bien los datos a nivel del origen ya estaban disponibles 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 su cuenta. 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 densidades de histogramTimeseries y con null para el 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 CrUX History. Obtén más información en la documentación de CrUX Vis.
Para generar gráficos similares por tu cuenta, creamos un Colab de ejemplo. Un Colab, o "Colaboratory", te permite escribir y ejecutar código de Python desde tu navegador. El notebook de Colab de la API de CrUX History (fuente) usa Python para realizar llamadas a la API y generar gráficos con los datos.
En este Colab, puedes crear gráficos de p75 y de tres intervalos, obtener datos en formato tabular y ver el par de solicitud y respuesta de la API de CrUX completando un breve formulario. No es necesario que seas programador para usarlo, pero, sin duda, puedes analizar el código de Python y modificarlo para crear algo increíble. Disfruta de la experiencia y no dudes en enviar comentarios sobre lo que encuentres.
Por supuesto, no estás limitado a Colab o Python, y 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 extremo de la API de CrUX History, los propietarios de sitios tenían acceso limitado a la información histórica que podían obtener de CrUX. Los datos mensuales a nivel del origen estaban disponibles a través de BigQuery, pero no los datos semanales ni los datos históricos a nivel de la página. Los propietarios de sitios podrían registrar estos datos por sí mismos con la API diaria, pero, a menudo, la necesidad de hacerlo solo se descubrió después de una regresión en las métricas.
Con la introducción de esta API de CrUX History, esperamos que los propietarios de sitios puedan comprender mejor las métricas cambiantes de sus sitios y que la usen como herramienta de diagnóstico cuando surjan problemas. Si usas la nueva API, puedes enviar comentarios al grupo de Google de Chrome UX Report (Discussions).
Agradecimientos
Imagen de encabezado de Dave Herring en Unsplash