API de historial de CrUX

La API de CrUX History brinda acceso de baja latencia a seis meses de datos históricos de la 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 "Obtener las tendencias históricas de UX para el origen de 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, para usar la API de CrUX History, se requiere una clave de API de Google Cloud. Se puede usar la misma clave para la API diaria y de History.

Puedes crear una en la página Credenciales y aprovisionarla para que la use 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 un fragmento discreto de información sobre una página o 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 todos los datos presentes en todas las páginas de ese origen. Por ejemplo, supongamos que el origen http://www.example.com tenía páginas como se indica 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 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 corresponden a ese origen.

URLs

Si el identificador es una URL, solo se mostrarán los datos de esa URL específica. Si vuelves a observar el mapa del sitio de origen http://www.example.com, haz lo siguiente:

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.

La API de CrUX History solo está disponible de forma agregada 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 array de histograma, cada entrada de serie temporal representa el porcentaje de cargas de página en las que la métrica se encuentra 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. 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 simple de tres discretizaciones para una métrica de ejemplo se ve así:

{
  "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áginas experimentaron el valor de métrica de ejemplo entre 0 ms y 2,500 ms durante el primer período de recopilación del historial, seguido del 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 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áginas 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 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 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íficas en el percentil determinado para esa métrica. Se basan en el conjunto completo de datos disponibles y no en los datos discretizados finales, por lo que no coinciden necesariamente con un percentil interpolado que se basa en el histograma discreto 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. 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 la página provino de computadoras de escritorio y el 82.88% de los teléfonos.

Tipos de valores de métricas

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

Elegibilidad de métricas

Según los criterios de elegibilidad, un origen o una URL solo pueden ser aptos para algunos de los períodos de recopilación que cubre la API de CrUX History. En estos casos, la API de CrUX History mostrará "NaN" para las densidades de histogramTimeseries y null para percentilesTimeseries para los períodos de recopilación que no tengan datos aptos. El motivo de la diferencia es que las densidades de 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 ningún dato apto, 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 ya no son aptos o no con el paso del tiempo, es posible que falten muchas entradas.

Períodos de recolecció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 período 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 últimas 25 semanas, es decir, un período de recopilación por semana.

Como cada período de recopilación contiene los datos agregados de los últimos 28 días, y los períodos de recopilación son por semana, esto significa que se superpondrán. Son similares a un promedio móvil de datos, con datos de tres semanas que se incluyen en cada período posterior, 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 datos de 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 cuerpo de ejemplo 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 si se 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 establece la propiedad metrics, se mostrarán todas las métricas disponibles:

  • cumulative_layout_shift
  • first_contentful_paint
  • first_input_delay
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • 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 CrUX History para ver 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 que estén disponibles a través de la API.

El promedio móvil

Los datos del Informe sobre la 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, datos de los últimos 28 días agregados.

La API de History contiene varios períodos de recopilación, cada uno de esos 28 días. Como cada período de recopilación contiene los datos agregados de los últimos 28 días, y los períodos de recopilación son por semana, esto significa que se superpondrán. Son similares a un promedio móvil de datos, con datos de tres semanas que se incluyen en cada período posterior, y una semana es diferente.

Actualizaciones semanales

La API de History se actualiza todos los lunes alrededor de 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) y un período de recopilación por semana.

No existe un Acuerdo de Nivel de Servicio para los horarios de actualización. Se ejecuta sobre la base 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 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 los mismos cuerpos de solicitud que la API de CrUX diaria, con la excepción de no admitir el campo de solicitud effectiveConnectionType.

Por ejemplo, para solicitar los valores de Largest Contentful Paint en computadoras de escritorio para 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 de 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

enum (FormFactor)

El factor de forma es la clase de dispositivo que usaron todos los usuarios para acceder al sitio con 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_pattern. El patrón de URL es la URL a la que se aplica el registro. Las direcciones (url_pattern) solo pueden ser una de las siguientes opciones:
origin

string

Origin especifica el origen para el que se creó este registro.

Nota: Cuando se especifica un origen, los datos de las cargas correspondientes a este origen en todas las páginas se agregan a los datos de la experiencia del usuario a nivel del origen.

url

string

url especifica una URL específica para la que es este registro.

Nota: Cuando se especifica un url, solo se agregan los datos de esa URL específica.

Métricas

Un elemento metric es un conjunto de datos sobre 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[]

object (Bin)

El histograma de serie temporal de las experiencias de los usuarios para una métrica. El histograma de serie temporal tendrá al menos una discretización y las densidades de todas las discretizaciones sumarán ~1.

Los valores faltantes para ese período de recolección en particular se marcarán como "NaN".

percentilesTimeseries

object (Percentiles)

Percentiles comunes útiles de la métrica. El tipo de valor de los percentiles será el mismo que el de las discretizaciones de histogramas.

Los valores faltantes para ese período de recolección en particular se marcarán como null.

fractionTimeseries

object (Fractions)

Este objeto contiene series temporales de fracciones etiquetadas, que suman alrededor de 1 por entrada.

Las fracciones se redondean con 4 decimales.

Las entradas faltantes se expresan como “NaN”` en todas las fracciones.

Depósito

Una bin es una parte discreta de los datos que se extiende de principio a fin, o si no se proporciona ningún final desde el principio 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 int., por lo tanto, sus discretizaciones métricas usarán int32s 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 discretizaciones métricas usarán cadenas para su tipo de valor.

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

(integer | string)

El inicio es el comienzo de la discretización de datos.

end

(integer | string)

Fin es el final de la discretización de datos. Si el final no se propaga, la discretización no tiene fin y es válida desde el principio hasta +inf.

densities

array[number]

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 a 4 decimales.

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
}
Campos
p75s

array[(integer | string)]

Series temporales de los valores que el 75% de las cargas de páginas experimentaron la métrica determinada con este valor o menos.

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 pueden considerarse que producen 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 discretizaciones de histogramas, 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 arreglos de fracciones.

Campos
p75s

array[(integer | string)]

Series temporales de los valores que el 75% de las cargas de páginas experimentaron la métrica determinada a este valor o a un valor menor.

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 automáticos simples que se realizan cuando se sabe que falla el url_pattern proporcionado. No se controlan acciones complejas, como seguir redireccionamientos.

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

string

Es la URL original solicitada antes de cualquier acción de normalización.

normalizedUrl

string

La URL después de cualquier acción de normalización. Esta es una URL de experiencia del usuario válida que se podría buscar razonablemente.

Límites de frecuencia

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