A API CrUX History oferece acesso de baixa latência a seis meses de dados históricos de experiências reais do usuário em granularidade de página e origem.
Caso de uso comum
A API CrUX History permite consultar métricas históricas de experiência do usuário em busca de um URI específico, como "Ver as tendências históricas de UX da origem https://example.com".
A API History segue a mesma estrutura da API CrUX diária, mas os valores são fornecidos em uma matriz e as chaves são rotuladas com nomes no plural (por exemplo, histogramTimeseries em vez de histogram ou p75s em vez de p75).
Chave de API do CrUX
Assim como a API diária, o uso da API CrUX History exige uma chave de API do Google Cloud. A mesma chave pode ser usada para a API diária e a de histórico.
É possível criar uma na página Credenciais e provisioná-la para uso no Chrome UX Report API.
Quando você está com uma chave de API, seu aplicativo pode anexar o parâmetro de consulta key=[YOUR_API_KEY] a todos os URLs das solicitações. Consulte Exemplos de consultas.
A chave de API é segura para ser incorporada a URLs sem precisar de codificação.
Modelo de dados
Esta seção detalha a estrutura de dados em solicitações e respostas.
Gravar
Uma informação discreta sobre uma página ou um site. Um registro pode ter dados específicos para um identificador e para uma combinação específica de dimensões. Um registro pode conter dados para uma ou mais métricas.
Identificadores
Os identificadores especificam quais registros devem ser consultados. No CrUX, esses identificadores são páginas da Web e sites.
Origem
Quando o identificador é uma origem, todos os dados presentes em todas as páginas dessa origem são agregados. Por exemplo, digamos que a origem http://www.example.com tenha páginas conforme disposto por este sitemap:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Isso significa que, ao consultar o Chrome UX Report com a origem definida como http://www.example.com, os dados de http://www.example.com/, http://www.example.com/foo.html e http://www.example.com/bar.html seriam retornados agregados, porque essas são todas as páginas dessa origem.
URLs
Quando o identificador for um URL, somente os dados desse URL específico serão retornados. Procurando novamente o sitemap de origem http://www.example.com:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Se o identificador estiver definido como um URL com o valor http://www.example.com/foo.html, somente os dados dessa página serão retornados.
Dimensões
As dimensões identificam um grupo específico de dados em que um registro está sendo agregado. Por exemplo, um formato PHONE indica que o registro contém informações sobre carregamentos que ocorreram em um dispositivo móvel.
A API CrUX History só está disponível agregada por dimensão de formato. Essa é uma classe geral de dispositivo dividida em PHONE, TABLET e DESKTOP.
Métrica
Informamos métricas em séries temporais de agregações estatísticas, que são histogramas, percentis e frações.
Histogramas
Quando as métricas são expressas em uma matriz de histograma, cada entrada de série temporal representa a porcentagem de carregamentos de página em que a métrica se enquadra em um intervalo, proporcionalmente a todos. Os pontos de dados são apresentados na ordem das datas do período de coleta que também são retornadas pela API. O primeiro ponto é o período mais antigo e o ponto final é o período de coleta mais recente.
Um histograma simples de três barras para uma métrica de exemplo fica assim:
{
"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]
}
],
}
Esses dados indicam que 91,90% dos carregamentos de página tiveram o valor da métrica de exemplo entre 0 ms e 2.500 ms no primeiro período de coleta do histórico, seguido por 92,03%, 91,94%... As unidades da métrica não estão contidas neste histograma. Neste caso, vamos considerar milissegundos.
Além disso, 5,21% dos carregamentos de página tiveram o valor da métrica do exemplo entre 2.500 ms e 4.000 ms no primeiro período de coleta do histórico, e 2,88% dos carregamentos de página tiveram um valor maior que 4.000 ms no primeiro período de coleta do histórico.
Percentis
As métricas também podem conter séries temporais de percentis que podem ser úteis para análises adicionais.
Os pontos de dados são apresentados na ordem das datas do período de coleta que também são retornadas pela API. O primeiro ponto é o período mais antigo e o ponto final é o período de coleta mais recente.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Esses percentis podem mostrar valores específicos de métricas em um determinado percentil. Eles são baseados no conjunto completo de dados disponíveis e não nos dados agrupados por classes. Portanto, eles não correspondem necessariamente a um percentil interpolado baseado no histograma final agrupado por classes.
Frações
As métricas podem ser expressas como séries temporais de frações rotuladas. Cada rótulo descreve um carregamento de página de uma maneira específica. Os pontos de dados são apresentados na ordem das datas do período de coleta que também são retornadas pela API. O primeiro ponto é o período mais antigo e o ponto final é o período de coleta mais recente.
Exemplo:
{
"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]}
}
}
Neste exemplo, o ponto de dados mais recente indica que 14,21% dos carregamentos de página vieram de computadores e 82,88% vieram de smartphones.
Tipos de valor de métrica
Como a API CrUX History usa os mesmos tipos de valor de métrica, consulte a documentação sobre os tipos de valor da métrica diária da API CrUX para mais detalhes.
Qualificação da métrica
Com base nos critérios de qualificação, uma origem ou um URL pode ser qualificado apenas para alguns dos períodos de coleta cobertos pela API CrUX History. Nesses casos, a API CrUX History vai retornar "NaN" para as densidades de histogramTimeseries e null para o percentilesTimeseries para os períodos de coleta que não têm dados qualificados. A razão para a diferença é que as densidades do histograma são sempre números, enquanto os percentis podem ser números ou strings (a CLS usa strings, mesmo que pareçam números).
Por exemplo, se o segundo período não tiver dados qualificados, as informações vão aparecer da seguinte forma:
{
"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]
},
}
Para URLs ou origens que se enquadram ou não na qualificação ao longo do tempo, você pode notar muitas entradas ausentes.
Períodos de coleta
A API CrUX History contém um objeto collectionPeriods com uma matriz de campos firstDate e endDate que representam as datas de início e término de cada janela de agregação. Exemplo:
"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 }
}
]
Esses períodos estão em ordem crescente e representam o intervalo de datas de cada um dos pontos de dados nas outras seções da resposta.
A API History é atualizada toda segunda-feira e contém dados até o sábado anterior (de acordo com o atraso padrão de dois dias). Ele contém os dados das últimas 25 semanas, um período de coleta por semana.
Como cada período de coleta contém os dados agregados dos últimos 28 dias e os períodos de coleta são semanais, os períodos de coleta se sobrepõem. Elas são semelhantes a uma média móvel de dados, com três semanas de dados sendo incluídas em cada período subsequente e uma semana sendo diferente.
Exemplos de consultas
As consultas são enviadas como objetos JSON usando uma solicitação POST para https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" com os dados da consulta como um objeto JSON no corpo do POST.
Observe o uso de queryHistoryRecord substituindo o queryRecord da API CrUX diária.
Um corpo de exemplo é:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Por exemplo, isso pode ser chamado em curl com a seguinte linha de comando (substituindo API_KEY pela sua chave):
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"]}'
Os dados no nível da página estão disponíveis pela API transmitindo uma propriedade url na consulta, em vez de origin:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Se a propriedade metrics não for definida, todas as métricas disponíveis serão retornadas:
cumulative_layout_shiftfirst_contentful_paintfirst_input_delayinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytenavigation_typesround_trip_timeform_factors(informado somente se nenhumformFactorfor especificado na solicitação)
Se nenhum valor formFactor for fornecido, os valores serão agregados em todos os formatos.
Confira o guia Como usar a CrUX History API para ver mais exemplos de consulta.
Pipeline de dados
O conjunto de dados CrUX é processado por um pipeline para consolidar, agregar e filtrar os dados antes de serem disponibilizados pela API.
A média contínua
Os dados do Chrome UX Report são uma média contínua de 28 dias de métricas agregadas. Isso significa que os dados apresentados no Chrome UX Report são, na verdade, os dados dos últimos 28 dias agregados.
A API History contém vários períodos de coleta, cada um abrangendo 28 dias. Como cada período de coleta contém os dados agregados dos últimos 28 dias e os períodos de coleta são semanais, os períodos de coleta se sobrepõem. Elas são semelhantes a uma média móvel de dados, com três semanas de dados sendo incluídas em cada período subsequente e uma semana sendo diferente.
Atualizações semanais
A API History é atualizada toda segunda-feira por volta das 04:00 UTC e contém dados até o sábado anterior (de acordo com o atraso padrão de dois dias). Ele contém as últimas 25 semanas (aproximadamente 6 meses) de dados, um período de coleta por semana.
Não há contrato de nível de serviço para horários de atualização. Ele é executado na medida do possível todos os dias.
Esquema
Há um único endpoint para a API CrUX History que aceita solicitações HTTP POST. A API retorna um record que contém um ou mais metrics correspondentes aos dados de desempenho sobre a origem ou página solicitada.
Solicitação HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord
O URL usa a sintaxe de transcodificação gRPC.
Corpo da solicitação
A API CrUX History usa os mesmos corpos de solicitação que a API CrUX diária, com a exceção de não oferecer suporte ao campo de solicitação effectiveConnectionType.
Por exemplo, para solicitar os valores de Largest Contentful Paint para computador para a página inicial web.dev:
{
"origin": "https://web.dev/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Corpo da resposta
As solicitações bem-sucedidas retornam respostas com um objeto record e urlNormalizationDetails na seguinte estrutura:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Por exemplo, a resposta para o corpo da solicitação na solicitação anterior poderia ser:
{
"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 }
}, {
...
}
]
}
}
Chave
Key define todas as dimensões que identificam esse registro como exclusivo.
{
"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 |
O formato é a classe de dispositivo que todos os usuários usaram para acessar o site nesse registro. Se o formato não for especificado, os dados agregados de todos os formatos serão retornados. |
Campo de união url_. O padrão de URL é o URL ao qual o registro se aplica. url_ só pode ser de um dos seguintes tipos: |
|
origin |
Origin especifica a origem deste registro. Observação: ao especificar uma origem, os dados dos carregamentos nessa origem em todas as páginas são agregados aos dados de experiência do usuário no nível da origem. |
url |
Observação: ao especificar um |
Métricas
Um metric é um conjunto de dados de experiência do usuário para uma única métrica de desempenho da Web, como a First Contentful Paint. Ela contém um histograma resumido do uso real do Chrome como uma série de bins.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
ou
"fractionTimeseries": {
object (Fractions)
}
| Campos | |
|---|---|
histogramTimeseries[] |
O histograma de série temporal das experiências do usuário para uma métrica. O histograma de série temporal terá pelo menos um agrupamento, e as densidades de todos os agrupamentos serão somadas a ~1. Os valores ausentes no período de coleta específico serão marcados como |
percentilesTimeseries |
Percentis úteis comuns da métrica. O tipo de valor para os percentis será o mesmo que os tipos de valor fornecidos para os agrupamentos do histograma. Os valores ausentes no período de coleta específico serão marcados como |
fractionTimeseries |
Este objeto contém séries temporais de frações rotuladas, que somam cerca de 1 por entrada. As frações são arredondadas para quatro casas decimais. As entradas ausentes são expressas como"NaN" em todas as frações. |
Agrupamento
Um bin é uma parte discreta de dados que abrange do início ao fim, ou se nenhuma extremidade for informada do início ao infinito positivo.
Os valores inicial e final de um agrupamento são fornecidos no tipo de valor da métrica que ele representa. Por exemplo, a First Contentful Paint é medida em milissegundos e exposta como ints. Portanto, os agrupamentos de métricas vão usar int32s para os tipos inicial e final. No entanto, a mudança cumulativa de layout é medida em decimais sem unidade e exposta como um decimal codificado como uma string. Portanto, os agrupamentos de métricas vão usar strings para o tipo de valor.
{
"start": value,
"end": value,
"densities": [number, number, number...etc.]
}
| Campos | |
|---|---|
start |
Start é o início do compartimento de dados. |
end |
Fim é o fim do compartimento de dados. Se end não for preenchido, o agrupamento não terá fim e será válido do início até +inf. |
densities |
Uma série temporal da proporção de usuários que tiveram o valor desse agrupamento para a métrica especificada. As densidades são arredondadas para quatro casas decimais. |
Percentis
Percentiles contém valores sintéticos de uma métrica em um determinado percentil estatístico. Elas são usadas para estimar o valor de uma métrica conforme a experiência por uma porcentagem de usuários em relação ao número total de usuários.
{
"P75": value
}
| Campos | |
|---|---|
p75s |
Séries temporais dos valores em que 75% dos carregamentos de página foram afetados pela métrica especificada com esse valor ou inferior a esse. |
Frações
Fractions contém séries temporais de frações rotuladas que somam cerca de 1 por entrada.
Cada rótulo descreve um carregamento de página de alguma forma. Assim, as métricas representadas dessa maneira podem ser consideradas como produzindo valores distintos em vez de valores numéricos, e as frações expressam a frequência com que um determinado valor distinto foi medido.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Assim como os valores de densidade nas barras do histograma, cada fraction é um número
0.0 <= value <= 1.0 e somam aproximadamente 1, 0. Quando a métrica não estiver disponível para um período de coleta específico, a entrada correspondente será "NaN" em todas as matrizes de frações.
| Campos | |
|---|---|
p75s |
Séries temporais dos valores em que 75% dos carregamentos de página foram afetados pela métrica especificada com esse valor ou inferior a esse. |
UrlNormalization
Objeto que representa as ações de normalização realizadas para normalizar um URL e aumentar as chances de uma pesquisa bem-sucedida. Essas são simples mudanças automatizadas que são realizadas na pesquisa do url_pattern fornecido e falhariam. Ações complexas, como seguir redirecionamentos, não são tratadas.
{
"originalUrl": string,
"normalizedUrl": string
}
| Campos | |
|---|---|
originalUrl |
O URL original solicitado antes de qualquer ação de normalização. |
normalizedUrl |
O URL após qualquer ação de normalização. Esse é um URL de experiência do usuário válido que poderia ser procurado. |
Limitações de taxa
A API CrUX History compartilha o mesmo limite com a API CrUX de 150 consultas por minuto por projeto do Google Cloud para qualquer uma das APIs, que é oferecida sem custo financeiro. Esse limite e seu uso atual podem ser consultados no Console do Google Cloud. Essa cota generosa deve ser suficiente para a grande maioria dos casos de uso e não é possível pagar por uma cota maior.