API CrUX History

Publicado em 7 de fevereiro de 2023 e atualizado pela última vez em 11 de abril de 2025

A API CrUX History oferece acesso de baixa latência a seis meses de dados históricos de experiência do usuário real na granularidade da página e da origem.

Faça um teste

Caso de uso comum

A API CrUX History permite consultar métricas históricas de experiência do usuário para um URI específico, como "Receba as tendências históricas de UX para a origem https://example.com".

A API History segue a mesma estrutura da API CrUX diária, exceto que os valores são fornecidos em uma matriz e as chaves são identificadas com nomes no plural (por exemplo, histogramTimeseries em vez de histogram ou p75s em vez de p75).

Chave da API CrUX

Assim como a API diária, o uso da API CrUX History requer uma chave de API do Google Cloud provisionada para uso de Chrome UX Report API. A mesma chave pode ser usada para a API diária e de histórico.

Como receber e usar uma chave de API

Ou crie uma na página "Credenciais".

Depois que você tiver uma chave de API, seu aplicativo poderá anexar o parâmetro de consulta key=yourAPIKey a todos os URLs de solicitação.

É seguro incorporar a chave de API a URLs. Não é necessário codificá-la.

Consulte Exemplos de consultas.

Modelo de dados

Esta seção detalha a estrutura dos 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 de uma ou mais métricas.

Identificadores

Os identificadores especificam quais registros devem ser procurados. 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 definido neste sitemap:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Isso significa que, ao consultar o relatório de UX do Chrome 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 serão retornados e agregados, porque são todas páginas nessa origem.

URLs

Quando o identificador é um URL, apenas os dados desse URL específico são retornados. Voltando ao 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 for definido como o URL com o valor de http://www.example.com/foo.html, apenas 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 de PHONE indica que o registro contém informações sobre cargas que ocorreram em um dispositivo móvel.

Formato

A API CrUX History só está disponível agregada pela dimensão do formato. Essa é uma classe geral de dispositivo dividida em PHONE, TABLET e DESKTOP.

Métrica

Nós informamos as 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 caiu em um intervalo, proporcionalmente a todas. Os pontos de dados são apresentados na ordem dos períodos de coleta também retornados pela API, sendo o primeiro ponto o período mais antigo e o final o período de coleta mais recente.

Um histograma de três intervalos para uma métrica de exemplo tem esta aparência:

{
  "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 0ms e 2.500ms no primeiro período de coleta no histórico, seguido por 92,03%, 91,94%... As unidades da métrica não estão contidas neste histograma. Neste caso, vamos presumir milissegundos.

Além disso, 5,21% dos carregamentos de página tiveram o valor da métrica de exemplo entre 2.500ms e 4.000ms no primeiro período de coleta no histórico, e 2,88% dos carregamentos de página tiveram um valor maior que 4.000ms no primeiro período de coleta no histórico.

Percentis

As métricas também podem conter séries temporais de percentis que podem ser úteis para outras análises.

Os pontos de dados são apresentados na ordem dos períodos de coleta também retornados pela API, sendo o primeiro ponto o período mais antigo e o 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 no percentil fornecido para essa métrica. Eles são baseados no conjunto completo de dados disponíveis, e não nos dados finais agrupados, portanto, não correspondem necessariamente a um percentil interpolado com base no histograma agrupado final.

Frações

As métricas podem ser expressas como séries temporais de frações marcadas. Cada rótulo descreve uma carga de página de uma maneira específica. Os pontos de dados são apresentados na ordem dos períodos de coleta também retornados pela API, sendo o primeiro ponto o período mais antigo e o 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 diária sobre os tipos de valor de métrica da API CrUX para mais detalhes.

Qualificação da métrica

Com base nos critérios de qualificação, uma origem ou um URL só pode ser qualificado para alguns dos períodos de coleta cobertos pela API CrUX History. Nesses casos, a API History do CrUX vai retornar "NaN" para as densidades histogramTimeseries e null para o percentilesTimeseries nos períodos de coleta que não têm dados qualificados. A razão para a diferença é que as densidades de 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, ele vai aparecer como:

{
  "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 tornam e deixam de ser qualificados ao longo do tempo, muitas entradas podem estar 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 de coleta estão em ordem crescente e representam o período 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 40 semanas anteriores, um período de coleta por semana. Por padrão, 25 períodos de coleta são retornados. Para mudar isso, defina "collectionPeriodCount" na solicitação como um número entre 1 e 40.

Como cada período de coleta contém os dados agregados dos 28 dias anteriores e os períodos de coleta são por semana, eles se sobrepõem. Elas são semelhantes a uma média móvel de dados, com três semanas de dados incluídas em cada período subsequente e uma semana 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 dados de consulta como um objeto JSON no corpo POST.

Observe que queryHistoryRecord substitui queryRecord na API diária da CrUX.

Um exemplo de corpo é:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Por exemplo, isso pode ser chamado de 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 ao transmitir 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 estiver definida, todas as métricas disponíveis serão retornadas:

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (somente informado se nenhum formFactor for especificado na solicitação)

Se nenhum valor de formFactor for fornecido, os valores serão agregados em todos os formatos.

Consulte o guia Como usar a API History do CrUX para conferir mais exemplos de consultas.

Pipeline de dados

O conjunto de dados do CrUX é processado por um pipeline para consolidar, agregar e filtrar os dados antes de ficar disponível pela API.

A média contínua

Os dados no Relatório de UX do Chrome são uma média contínua de 28 dias das métricas agregadas. Isso significa que os dados apresentados no Relatório de UX do Chrome a qualquer momento são dados agregados dos últimos 28 dias.

A API History contém vários períodos de coleta, cada um com duração de 28 dias. Como cada período de coleta contém os dados agregados dos 28 dias anteriores e os períodos de coleta são por semana, eles se sobrepõem. Elas são semelhantes a uma média móvel de dados, com três semanas de dados incluídas em cada período subsequente e uma semana diferente.

Atualizações semanais

A API History é atualizada toda segunda-feira por volta das 04h UTC 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 40 semanas anteriores (aproximadamente 10 meses), um período de coleta por semana. Por padrão, retornamos 25 entradas por série temporal, mas isso pode ser substituído especificando o parâmetro de solicitação collectionPeriodCount.

Não há contrato de nível de serviço para os horários de atualização. Ela é executada com o melhor esforço 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 performance da 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 corpos de solicitação semelhantes aos da API CrUX diária, com um campo "collectionPeriodCount" opcional extra:

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // 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.

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

Por exemplo, para solicitar os valores de Largest Contentful Paint para computador da página inicial do web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Essa solicitação semelhante inclui o campo opcional collectionPeriodCount e geraria 40 entradas de série temporal, fornecendo cerca de 10 meses de histórico de desempenho da Web para a origem https://web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ],
  "collectionPeriodCount": 40
}

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 ao corpo da solicitação na solicitação anterior pode 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.
}

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. Ele contém um histograma de resumo do uso real do Chrome como uma série de bins.

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

ou

"fractionTimeseries": {
  object (Fractions)
}

Agrupamento

Um bin é uma parte discreta de dados que se estende do início ao fim ou, se nenhum fim for fornecido, do início ao infinito positivo.

Os valores inicial e final de um intervalo são fornecidos no tipo de valor da métrica que ele representa. Por exemplo, o primeiro paint com conteúdo é medido em milissegundos e exposto como ints. Portanto, os intervalos de métricas vão usar int32s para os tipos de início e fim. No entanto, a mudança cumulativa do layout é medida em decimais sem unidade e é exposta como um decimal codificado como uma string. Portanto, os intervalos de métricas usam strings para o tipo de valor.

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

Percentis

Percentiles contém valores sintéticos de uma métrica em um determinado percentil estatístico. Eles são usados para estimar o valor de uma métrica conforme observado por uma porcentagem de usuários do total de usuários.

{
  "P75": value
}

Frações

Fractions contém séries temporais de frações marcadas que somam aproximadamente 1 por entrada. Cada rótulo descreve uma carga de página de alguma forma. Assim, as métricas representadas dessa forma podem ser consideradas como produtoras de valores distintos em vez de valores numéricos, e as frações expressam a frequência com que um valor distinto específico foi medido.

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

Assim como os valores de densidade em buckets de histograma, cada fraction é um número 0.0 <= value <= 1.0, e eles somam aproximadamente 1,0. Quando a métrica não está disponível para um período de coleta específico, a entrada correspondente será "NaN" em todas as matrizes de frações.

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 mudanças básicas e automatizadas que são feitas quando a pesquisa do url_pattern fornecido falha. Ações complexas, como redirecionamentos, não são processadas.

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

Limites de taxas

A API CrUX History compartilha o mesmo limite de 150 consultas por minuto em cada projeto do Google Cloud com a API CrUX, que é oferecida sem custo. Esse limite e seu uso atual podem ser vistos 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 um aumento dela.