Como usar a API CrUX History

Johannes Henkel

Jasmine Yan

Barry Pollard

Publicado em: 7 de fevereiro de 2023. Última atualização: 11 de abril de 2025

Este guia apresenta o endpoint da API History do Chrome UX Report (CrUX), que fornece séries temporais de dados de desempenho da Web. Esses dados são atualizados semanalmente e mostram 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 original da API CrUX, agora é possível ver rapidamente os dados mais recentes e o que aconteceu antes. Isso torna a ferramenta muito útil para acompanhar as mudanças nas páginas da Web ao longo do tempo.

Testar a API nesta página

Faça um teste

Consultar a API CrUX diária

Para recapitular um artigo anterior sobre a API CrUX, você pode receber um instantâneo 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 resumo inclui valores de densidade do histograma e percentis para um período de coleta de 28 dias específico, neste caso, de 27 de dezembro de 2022 a 23 de janeiro de 2023.

Consultar a API CrUX History

Para chamar o endpoint de histórico, mude queryRecord no URL para queryHistoryRecord no comando curl. Usar a mesma chave de API do 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 os valores do 75º percentil (p75) e de densidade do 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 grupo de 0 a 2.500 ms da métrica Maior exibição de conteúdo (LCP) é [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 de https://web.dev, foi constatado 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 uma LCP de menos de 1.377 ms, e 25% tiveram uma 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 cobre 10 meses.

Observação:ao contrário da API diária, a API CrUX History é atualizada apenas uma vez por semana, às segundas-feiras, incluindo dados até o sábado anterior. No entanto, assim como a API diária, cada valor na API CrUX History é medido nos 28 dias anteriores. Isso significa que a API History representa os mesmos dados que estavam disponíveis usando a API diária para a data especificada. A diferença é que agora é possível consultar esses dados de forma retrospectiva. No entanto, isso significa que a API History contém períodos de dados sobrepostos, mas, como uma análise de tendências, é útil para acompanhar a mudança nas métricas ao longo do tempo.

Em qualquer resposta, o comprimento da série temporal para as densidades de agrupamento do histograma e para os valores de p75 será exatamente o mesmo que o comprimento da matriz no campo collectionPeriods: há uma correspondência individual com base no índice dessas matrizes.

Consultar dados no nível da página

Além dos dados no nível da origem, a API CrUX History permite o acesso a dados históricos no nível da página. Embora os dados no nível da origem já estivessem disponíveis usando o conjunto de dados da CrUX no BigQuery, os dados históricos no nível da página só estavam disponíveis se os sites coletavam e armazenavam os dados por conta própria. A nova API 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 do restante da CrUX. Portanto, as páginas podem não ter um registro histórico completo. Nesses casos, os dados "ausentes" serão representados por "NaN" para as densidades histogramTimeseries e null para os percentilesTimeseries. O motivo da diferença é que as densidades do 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 na documentação do CrUX Vis.

Para gerar gráficos semelhantes, criamos um Colab de exemplo. Com o Colab, ou "Colaboratory", é possível escrever e executar Python no navegador. O CrUX History API Colab (fonte) usa Python para fazer chamadas à API e criar gráficos com os dados.

Com este Colab, é possível criar gráficos p75 e tri-bin, receber dados em formato tabular e conferir o par de solicitação e resposta da API CrUX preenchendo um breve formulário. Não é necessário ser programador para usar isso, mas você pode analisar o código Python e modificá-lo para criar algo incrível. Aproveite e envie feedback sobre o que você encontrar!

É claro que você não está limitado ao Colab ou ao Python. Este é apenas um exemplo de como usar essa nova API. Como um endpoint HTTP baseado em JSON, a API pode ser consultada de qualquer tecnologia.

Conclusão

Antes da introdução do endpoint da API CrUX History, os proprietários de sites tinham acesso limitado às informações históricas que podiam obter do CrUX. Os dados mensais de origem estavam disponíveis usando o BigQuery, mas os dados semanais e históricos no nível da página não estavam. Os proprietários de sites podem registrar esses dados usando a API diária, mas muitas vezes a necessidade disso só é 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 entendam melhor as métricas em constante mudança e sirva como uma ferramenta de diagnóstico quando surgirem problemas. Se você estiver usando a nova API, envie seu feedback no grupo do Google Chrome UX Report (Discussões).

Agradecimentos

Imagem principal de Dave Herring no Unsplash