La API de CrUX History otorga acceso de baja latencia a seis meses de datos históricos de experiencia del usuario real en el nivel de detalle de la página y el origen.
Caso de uso común
La API de CrUX History permite consultar métricas históricas de experiencia del usuario para un URI específico, como "Obtén las tendencias históricas de 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, el uso de la API de CrUX History requiere una clave de API de Google Cloud. La misma clave se puede usar para la API diaria y la del historial.
Puedes crear una en la página Credenciales y aprovisionarla para el uso de 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 información discreta sobre una página o un 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 juntos todos los datos presentes para todas las páginas de ese origen. Por ejemplo, supongamos que el origen http://www.example.com tenía páginas según 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 pertenecen a ese origen.
URLs
Si el identificador es una URL, solo se mostrarán los datos para esa URL específica. Volvamos al 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 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 está agregando un registro. Por ejemplo, un factor de forma de PHONE indica que el registro contiene información sobre cargas que se produjeron en un dispositivo móvil.
La API de CrUX History solo está disponible para datos agregados por dimensión de factor de forma. Esta es una clase general de dispositivo dividida en PHONE, TABLET y DESKTOP.
Métrica
Informamos 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 arreglo de histograma, cada entrada de serie temporal representa el porcentaje de cargas de página en las que la métrica cayó en un intervalo, de forma proporcional a todos. Los datos se presentan en el orden de las fechas del período de recopilación que también muestra la API. El primer punto es el período más antiguo y el último punto es el más reciente.
Un histograma simple de tres contenedores 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 del historial, seguido por el 92.03%, 91.94%... Las unidades de la métrica no se encuentran en este histograma. En este caso, supondremos que son milisegundos.
Además, el 5.21% de las cargas de páginas experimentaron el valor de 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áginas experimentaron un valor superior a 4,000 ms en el primer período de recopilación en el historial.
Percentiles
Las métricas también pueden contener series temporales de percentiles que pueden ser útiles para 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. El primer punto es el período más antiguo y el último punto es el 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 discretos finales, por lo que no necesariamente coinciden con un percentil interpolado que se basa en el histograma combinado final.
Fracciones
Las métricas se pueden expresar como series temporales de fracciones etiquetadas; cada etiqueta describe una carga de página de una forma particular. Los datos se presentan en el orden de las fechas del período de recopilación que también muestra la API. El primer punto es el período más antiguo y el último punto es el 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 provino de computadoras de escritorio y el 82.88% de teléfonos.
Tipos de valores de las métricas
Como la API de CrUX History usa los mismos tipos de valores de métricas, puedes consultar la documentación de los tipos de valores de métricas diarias de la API de CrUX para obtener más detalles.
Elegibilidad de métricas
Según los criterios de elegibilidad, es posible que un origen o una URL solo sean aptas 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 de histogramTimeseries y null para las percentilesTimeseries para los períodos de recopilación que no tengan datos aptos. La razón de la diferencia es que las densidades de los histogramas son siempre 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 tiene datos aptos, se mostrará 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 no son aptos con el paso del tiempo, es posible que falten muchas entradas.
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 25 semanas anteriores, un período de recopilación por semana.
Debido a que 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, con tres semanas de datos que se incluyen en cada período posterior y una semana 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 POST.
Observa el uso de queryHistoryRecord que reemplaza el queryRecord de la API de CrUX diaria.
Un ejemplo de cuerpo es:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Por ejemplo, se puede llamar a esto 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 página están disponibles a través de la API pasando 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_shiftfirst_contentful_paintfirst_input_delayinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytenavigation_typesform_factors(solo se informa si no se especifica ningúnformFactoren 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 CrUX History para obtener más consultas de ejemplo.
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 estar 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 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, los datos de los últimos 28 días combinados.
La API de History contiene varios períodos de recopilación, cada uno de los cuales abarca estos 28 días. Debido a que 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, con tres semanas de datos que se incluyen en cada período posterior y una semana diferente.
Actualizaciones semanales
La API de History se actualiza todos los lunes a las 04:00 UTC y contiene datos hasta el sábado anterior (según el retraso estándar de 2 días). Contiene los datos de las últimas 25 semanas (aproximadamente 6 meses), un período de recopilación por semana.
No existe un acuerdo de nivel de servicio para los horarios de actualización, sino que se ejecuta según el criterio del mejor esfuerzo todos los días.
Esquema
Hay un solo extremo para la API de CrUX History que acepta solicitudes HTTP POST. La API muestra un objeto record que contiene uno o más metrics que corresponden 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 los mismos cuerpos de solicitud que la API de CrUX diaria, excepto que no admite el campo de solicitud effectiveConnectionType.
Por ejemplo, si deseas solicitar los valores de Largest Contentful Paint para computadoras de la página principal de web.dev, haz lo siguiente:
{
"origin": "https://web.dev/",
"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 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 únicas.
{
"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 |
El factor de forma es la clase de dispositivo que utilizaron todos los usuarios para acceder al sitio para este registro. Si no se especifica el factor de forma, se mostrarán los datos agregados de todos los factores de forma. |
Campo de unión url_. El patrón de URL es la URL a la que se aplica el registro. Las direcciones (url_) solo pueden ser una de las siguientes opciones: |
|
origin |
El origen especifica el origen para el que es este registro. Nota: Cuando se especifica un origen, los datos de las cargas de este origen en todas las páginas se agregan a los datos de la experiencia del usuario a nivel del origen. |
url |
Nota: Cuando se especifica una |
Métricas
Un metric es un conjunto de datos de la experiencia del usuario para una sola métrica de rendimiento web, como el primer procesamiento de imagen con contenido. Contiene un histograma resumido del uso real de Chrome como una serie de bins.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
o
"fractionTimeseries": {
object (Fractions)
}
| Campos | |
|---|---|
histogramTimeseries[] |
El histograma de series temporales de las experiencias del usuario para una métrica. El histograma de serie temporal tendrá al menos un discretización, y las densidades de todos los discretizaciones suman alrededor de 1. Los valores faltantes para ese Período de recopilación específico se marcarán como |
percentilesTimeseries |
Percentiles útiles comunes de la métrica. El tipo de valor para los percentiles será el mismo que los tipos de valor especificados para las discretizaciones de histograma. Los valores faltantes para ese Período de recopilación específico se marcarán como |
fractionTimeseries |
Este objeto contiene series temporales de fracciones etiquetadas, que suman aproximadamente 1 por entrada. Las fracciones se redondean con 4 decimales. Las entradas faltantes se expresan como “NaN”” en todas las fracciones. |
Depósito
Un bin es una porción discreta de datos que abarca de principio a fin o si no se da ningún final desde el inicio 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 ints, por lo que sus contenedores de métricas usarán int32s para sus tipos de inicio y finalización. Sin embargo, el cambio de diseño acumulado se mide en decimales sin unidades y se expone 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,
"densities": [number, number, number...etc.]
}
| Campos | |
|---|---|
start |
El inicio es el principio del depósito de datos. |
end |
El final es el final de los contenedores de datos. Si no se propaga el valor, entonces el intervalo no tiene ningún final y es válido desde el inicio hasta el +inf. |
densities |
Una serie temporal de la proporción de usuarios que experimentaron el valor de esta discretización para la métrica determinada. Las densidades se redondean con 4 decimales. |
Percentiles
Percentiles contiene valores sintéticos de una métrica en un percentil estadístico determinado. Se usan para calcular el valor de una métrica según la experiencia de un porcentaje de usuarios del total de usuarios.
{
"P75": value
}
| Campos | |
|---|---|
p75s |
Las series temporales de los valores que el 75% de las cargas de páginas tuvieron la métrica determinada con un valor igual o inferior a este. |
Fracciones
Fractions contiene series temporales de fracciones etiquetadas cuya suma es aproximadamente 1, por entrada.
Cada etiqueta describe una carga de página de alguna manera, por lo que se puede considerar que las métricas representadas de esta manera producen valores distintos en lugar de valores numéricos, y las fracciones expresan la frecuencia con la que se midió un valor distinto específico.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Al igual que los valores de densidad en las discretizaciones 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.
| Campos | |
|---|---|
p75s |
Las series temporales de los valores que el 75% de las cargas de páginas experimentaron la métrica determinada a este valor o inferior. |
UrlNormalization
Objeto que representa las acciones de normalización tomadas para normalizar una URL con el objetivo de lograr una mayor probabilidad de que la búsqueda sea exitosa Estos son cambios automáticos simples que se realizan cuando se busca el url_pattern proporcionado y se produce un error. No se administran las acciones complejas, como los siguientes redireccionamientos.
{
"originalUrl": string,
"normalizedUrl": string
}
| Campos | |
|---|---|
originalUrl |
Es la URL original solicitada antes de cualquier acción de normalización. |
normalizedUrl |
La URL después de cualquier acción de normalización. Esta es una URL de experiencia del usuario válida que podría buscarse razonablemente. |
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 API, que se ofrecen sin cargo. Puedes consultar este límite y tu uso actual en la consola de Google Cloud. Esta amplia cuota debería ser suficiente para la gran mayoría de los casos de uso, y no es posible pagar una cuota mayor.