Publicado em: 7 de fevereiro de 2023, última atualização: 11 de abril de 2025
Este guia apresenta o endpoint da API CrUX History, que fornece séries temporais de dados de desempenho da Web. Esses dados são atualizados semanalmente e permitem que você veja cerca de seis meses de histórico, com 40 pontos de dados espaçados por uma semana.
Quando usado com as atualizações diárias do endpoint da API CrUX, agora você pode ver rapidamente os dados mais recentes e o que aconteceu anteriormente, tornando essa uma ferramenta poderosa para observar as mudanças nas páginas da Web ao longo do tempo.
Testar a API nesta página
Consultar a API CrUX diária
Para recapitular um artigo anterior sobre a API CrUX, você pode receber um snapshot dos dados de campo de uma origem específica desta forma:
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 }
}
}
}
Esse snapshot inclui valores de densidade de histograma e percentis para um período de coleta específico de 28 dias, neste caso, de 27 de dezembro de 2022 a 23 de janeiro de 2023.
Consultar a API CrUX History
Para chamar o endpoint do histórico, mude queryRecord no URL para queryHistoryRecord no comando curl. Usar a mesma
chave da API CrUX da chamada anterior vai funcionar.
collectionPeriodCount especifica o número de entradas de série temporal a serem retornadas. O máximo é 40. Se não for especificado, o padrão será 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}'
O formato geral de uma resposta é semelhante, mas há muito mais dados. Em vez de um único ponto de dados, agora há séries temporais para os campos que contêm o 75º percentil (p75) e valores de densidade de 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 }
}
]
}
}
Neste exemplo, a série temporal densities para o bucket de 0 a 2.500 ms da
Largest Contentful Paint (LCP) métrica é
[0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Cada uma dessas densidades foi
observada durante a entrada collectionPeriods correspondente. Por exemplo, a quinta densidade, 0,9183, foi a densidade do quinto período de coleta, que terminou em 3 de setembro de 2022, e 0,9187 foi a densidade no período que terminou na semana seguinte.
Em outras palavras, interpretando as últimas entradas de série temporal no exemplo para web.dev, foi descoberto que, de 14 de agosto de 2022 a 10 de setembro de 2022, 91,87% dos carregamentos de página tinham valores de LCP menores que 2.500 ms, 5,27% tinham valores entre 2.500 ms e 4.000 ms, e 2,85% tinham valores maiores que 4.000 ms.
Da mesma forma, há uma série temporal para os valores de p75: o LCP p75 de 14 de agosto de 2022 a 10 de setembro de 2022 foi 1377. Isso significa que, para esse período de coleta, 75% das experiências do usuário tiveram um LCP menor que 1.377 ms e 25% das experiências do usuário tiveram um LCP maior que 1.377 ms.
Embora o exemplo liste apenas seis entradas de série temporal e períodos de coleta,
as respostas da API fornecem 25 entradas de série temporal por padrão e um máximo de
40, quando "collectionPeriodCount": 40 é especificado na solicitação. Como as
datas de término de cada um desses períodos de coleta são sábados com sete dias
de diferença, com "collectionPeriodCount": 40, isso abrange 10 meses.
Em qualquer resposta, o comprimento da série temporal para as densidades de bucket de histograma e para os valores de p75 será exatamente o mesmo que o comprimento da matriz no campo collectionPeriods: há uma correspondência um para um com base no índice dessas matrizes.
Consultar dados no nível da página
Além dos dados de origem, a API CrUX History permite o acesso a dados históricos no nível da página. Embora os dados de origem estivessem disponíveis anteriormente usando o conjunto de dados do CrUX no BigQuery, os dados históricos no nível da página só estavam disponíveis se os sites coletassem e armazenassem os dados. A nova API agora desbloqueia esses dados históricos no nível da página.
Os dados no nível da página podem ser consultados da mesma maneira, mas usando url em vez de origin no payload:
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/"}'
Os dados históricos no nível da página (e da origem) estão sujeitos aos
mesmos requisitos de qualificação que o
restante do CrUX. Portanto, as páginas em particular podem não ter um registro histórico
completo. Nesses casos, os dados "ausentes" serão representados por "NaN" para as
histogramTimeseries densidades e null para percentilesTimeseries. O motivo da diferença é que as densidades de histograma são sempre números, enquanto os percentis podem ser números ou strings (o CLS usa strings, mesmo que pareçam números).
Visualizar os dados
A maneira mais fácil de visualizar os dados é usando o CrUX Vis, uma ferramenta criada especificamente para demonstrar o poder da API CrUX History. Leia mais em a documentação do CrUX Vis.
Para gerar gráficos semelhantes, criamos um exemplo do Colab. Um Colab, ou "Colaboratory", permite escrever e executar Python no navegador. O Colab da API CrUX History (link em inglês) usa Python para fazer chamadas para a API e representar os dados.
Esse Colab permite criar gráficos de p75, gráficos de três buckets, receber dados em formato de tabela e conferir o par de solicitação e resposta da API CrUX, preenchendo um breve formulário. Não é necessário ser um programador para usar isso, mas você pode analisar o código Python e modificá-lo para algo incrível.
Este é apenas um exemplo de como usar essa nova API. Como um endpoint HTTP baseado em JSON, a API pode ser consultada em qualquer tecnologia.
Conclusão
Antes da introdução do endpoint de API CrUX History, os proprietários de sites tinham informações históricas limitadas que podiam ser obtidas do CrUX. Os dados mensais de origem estavam disponíveis usando o BigQuery, mas os dados semanais não estavam disponíveis, nem os dados históricos no nível da página. Os proprietários de sites podiam registrar esses dados usando a API diária, mas muitas vezes a necessidade disso só era descoberta após uma regressão nas métricas.
A expectativa com a introdução dessa API CrUX History é que ela permita que os proprietários de sites tenham uma compreensão melhor das métricas de mudança do site e como uma ferramenta de diagnóstico para quando surgirem problemas. Se você estiver usando a nova API, envie feedback para o grupo do Google Chrome UX Report (Discussões).