A API CrUX History oferece acesso de baixa latência a seis meses de dados históricos da experiência do usuário real em granularidade da página e da origem.
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 "Confira as tendências históricas de UX para a origem do 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 da API CrUX
Assim como a API diária, para usar a API CrUX History, você precisa de uma chave de API do Google Cloud. A mesma chave pode ser usada para a API diária e de histórico.
Você pode criar uma na página Credenciais e provisioná-la para uso do Chrome UX Report API.
Depois que você estiver com uma chave de API, seu aplicativo poderá anexar o parâmetro de consulta key=[YOUR_API_KEY] a todos os URLs de solicitação. 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 de uma ou mais métricas.
Identificadores
Os identificadores especificam quais registros precisam ser pesquisados. No CrUX, esses identificadores são páginas da Web e sites.
Origem
Quando o identificador é uma origem, todos os dados presentes para todas as páginas nessa 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 sob essa origem.
URLs
Quando o identificador é um URL, apenas os dados desse URL específico são retornados. Analisando 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 de 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 ao qual um registro está sendo agregado. Por exemplo, o 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 de forma 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 enquadrava em um intervalo, proporcionalmente a todos. Os pontos de dados são apresentados na ordem das datas do período de coleta também retornadas pela API, sendo que o primeiro ponto é o período mais antigo e o último, o mais recente.
Um histograma simples de três bin 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 no 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 de exemplo entre 2.500 ms e 4.000 ms no primeiro período de coleta no histórico, e 2,88% dos carregamentos de página tiveram um valor maior que 4.000 ms 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 análises adicionais.
Os pontos de dados são apresentados na ordem das datas do período de coleta também retornadas pela API, sendo que o primeiro ponto é o período mais antigo e o último, o mais recente.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Esses percentis podem mostrar valores específicos de métricas no determinado percentil dessa métrica. Elas são baseadas no conjunto completo de dados disponíveis, e não nos dados finais agrupados por classes. Portanto, elas não correspondem necessariamente a um percentil interpolado baseado no histograma de agrupamento final.
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 também retornadas pela API, sendo que o primeiro ponto é o período mais antigo e o último, o 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%, de smartphones.
Tipos de valores de métricas
Como a API CrUX History usa os mesmos tipos de valores de métricas, você pode consultar a documentação diária sobre os tipos de valores de métricas da API CrUX para saber mais.
Qualificação da métrica
Com base nos critérios de qualificação, uma origem ou um URL só pode se qualificar para alguns 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. 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 se pareçam com números).
Por exemplo, se o segundo período não tiver dados qualificados, ele será exibido 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 estão dentro e fora da qualificação ao longo do tempo, pode haver muitas entradas faltando.
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 25 semanas anteriores, um período de coleta por semana.
Como cada período de coleta contém os dados agregados anteriores dos 28 dias anteriores e os períodos de coleta são semanais, isso significa que os períodos de coleta vão se sobrepor. Eles 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 dados de consulta como um objeto JSON no corpo do POST.
Observe o uso de queryHistoryRecord substituindo o queryRecord da API CrUX diária.
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 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_typesform_factors(informado apenas se nenhumformFactorfor especificado na solicitação)
Se nenhum valor de formFactor for informado, os valores vão ser agregados em todos os formatos.
Consulte o guia Como usar a API CrUX History para ver mais exemplos de consultas.
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 das métricas agregadas. Isso significa que os dados apresentados no Chrome UX Report a qualquer momento são, na verdade, dados dos últimos 28 dias agregados.
A API History contém vários períodos de coleta, cada um abrangendo esses 28 dias. Como cada período de coleta contém os dados agregados anteriores dos 28 dias anteriores e os períodos de coleta são semanais, isso significa que os períodos de coleta vão se sobrepor. Eles 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 4h 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 últimas 25 semanas (aproximadamente 6 meses), 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 com base no melhor esforço 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 os mesmos corpos de solicitação que a API CrUX diária, exceto por não oferecer suporte ao campo de solicitação effectiveConnectionType.
Por exemplo, para solicitar os valores de Maior exibição de conteúdo do 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 estrutura a seguir:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Por exemplo, a resposta ao 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 único.
{
"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 do dispositivo que todos os usuários usaram para acessar o site para esse 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_ pode ser apenas de um dos tipos a seguir: |
|
origin |
"Origin" especifica a origem desse registro. Observação: ao especificar uma origem, os dados dos carregamentos nela em todas as páginas são agregados aos dados de experiência do usuário no nível da origem. |
url |
Observação: quando você especifica um |
Métricas
Uma metric é um conjunto de dados de experiência do usuário para uma única métrica de desempenho na Web, como a primeira exibição de conteúdo. 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)
}
| Campos | |
|---|---|
histogramTimeseries[] |
O histograma de série temporal de 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 somados em torno de um. Os valores ausentes para esse 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 de histograma. Os valores ausentes para esse período de coleta específico serão marcados como |
fractionTimeseries |
Este objeto contém séries temporais de frações rotuladas, que somam aproximadamente uma por entrada. As frações são arredondadas para quatro casas decimais. As entradas que faltam são expressas como `"NaN"` em todas as frações. |
Agrupamento
Um bin é uma parte discreta dos dados que abrange do início ao fim ou se nenhum fim é fornecido 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 primeira exibição de conteúdo é medida em milissegundos e exposta como ints. Portanto, os agrupamentos de métricas vão usar int32s para os tipos de início e fim. No entanto, a mudança de layout cumulativa é medida em decimais sem unidade e exposta como um decimal codificado como uma string. Portanto, os agrupamentos de métricas usarão strings para o tipo de valor.
{
"start": value,
"end": value,
"densities": [number, number, number...etc.]
}
| Campos | |
|---|---|
start |
O início é o início do agrupamento de dados. |
end |
O fim é o fim do agrupamento de dados. Se end não for preenchido, o agrupamento não terá fim e será válido do início a +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. Eles são usados para estimar o valor de uma métrica conforme observado por uma porcentagem de usuários do número total.
{
"P75": value
}
| Campos | |
|---|---|
p75s |
As séries temporais dos valores que 75% da página carregaram a métrica especificada como igual ou menor que esse valor. |
Frações
Fractions contém séries temporais de frações rotuladas que somam aproximadamente 1 por entrada.
Cada rótulo descreve um carregamento de página de alguma forma. Por isso, as métricas representadas dessa maneira podem ser consideradas como produção de valores distintos em vez de valores numéricos, e as frações expressam com que frequência 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 caixas do histograma, cada fraction é um número
0.0 <= value <= 1.0, e a soma deles é aproximadamente 1,0. Quando a métrica não estiver disponível para um determinado período de coleta, a entrada correspondente será "NaN" em todas as matrizes de frações.
| Campos | |
|---|---|
p75s |
As séries temporais dos valores que 75% da página carregaram a métrica especificada como igual ou inferior a esse valor. |
UrlNormalization
Objeto que representa as ações de normalização realizadas para normalizar um URL e aumentar a chance de uma pesquisa bem-sucedida. Essas são mudanças automatizadas simples que são realizadas ao pesquisar o url_pattern fornecido. Ações complexas, como seguir redirecionamentos, não são processadas.
{
"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 válido de experiência do usuário que poderia ser razoavelmente pesquisado. |
Limitações de taxa
A API CrUX History tem o mesmo limite da API CrUX de 150 consultas por minuto em cada 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 é suficiente para a grande maioria dos casos de uso, e não é possível pagar por uma cota maior.