API CrUX

A API CrUX oferece acesso de baixa latência a dados agregados de experiência de usuários reais na granularidade da página e da origem.

Faça um teste

Caso de uso comum

A API CrUX permite consultar as métricas de experiência do usuário para um URI específico, como "Receber métricas para a origem https://example.com".

Chave da API CrUX

O uso da API CrUX requer uma chave de API do Google Cloud provisionada para uso de Chrome UX Report API.

Como receber e usar uma chave de API

Gerar uma chave

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. Cada dimensão terá um determinado número de valores, e a falta de especificação dessa dimensão significa que ela é agregada em todos os valores. Por exemplo, especificar "sem formato" indica que o registro contém informações sobre cargas que ocorreram em qualquer formato.

Formato

A classe do dispositivo que o usuário final usou para navegar até a página. Essa é uma classe geral de dispositivo dividida em PHONE, TABLET e DESKTOP.

Métrica

As métricas são informadas como agregações estatísticas, em histogramas, percentis e frações.

Os valores de ponto flutuante são arredondados para quatro casas decimais. As métricas cumulative_layout_shift são números reais codificados como uma string, portanto, não são consideradas valores decimais e são informadas com duas casas decimais na string.

Histograma

Quando as métricas são expressas em um histograma, mostramos as porcentagens de carregamentos de página que se enquadram em determinados intervalos para essa métrica.

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

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Esses dados indicam que, para 38,18% dos carregamentos de página, a métrica de exemplo foi medida entre 0ms e 1.000ms. As unidades da métrica não estão contidas nesse histograma. Nesse caso, vamos presumir milissegundos.

Além disso, 49,91% dos carregamentos de página tiveram um valor de métrica entre 1.000 ms e 3.000 ms, e 11,92% tiveram um valor maior que 3.000 ms.

Percentis

As métricas também podem conter percentis que podem ser úteis para análises adicionais. Nós informamos valores específicos da métrica no percentil fornecido para ela. 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 baseado no histograma final agrupado.

{
  "percentiles": {
    "p75": 2063
  }
}

Neste exemplo, pelo menos 75% dos carregamentos de página foram medidos com um valor de métrica <= 2063.

Observação:os valores de cada percentil são derivados sinteticamente. Isso não implica que qualquer usuário realmente tenha experimentado o valor indicado, apenas que uma porcentagem de carregamentos de página teve um valor de métrica menor do que o valor fornecido.

Frações

As frações indicam as porcentagens de carregamentos de página que podem ser marcadas de uma maneira específica. Nesse caso, os valores da métrica são esses rótulos.

Por exemplo, a métrica form_factors consiste em um objeto fractions que lista o detalhamento dos formatos (ou dispositivos) que a consulta abrange:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

Nesse caso, 3,77% dos carregamentos de página foram medidos em um computador, 2,88% em um tablet e 93,35% em um smartphone, totalizando 100%.

Tipos de valor de métrica

Nome da métrica da API CrUX	Tipo de dados	Unidades métricas	Agregações estatísticas	Documentação
cumulative_layout_shift	2 casas decimais duplas codificadas como string	sem unidade	histograma com três intervalos, percentis com p75	cls
first_contentful_paint	int	milésimos de segundo	histograma com três intervalos, percentis com p75	fcp
interaction_to_next_paint	int	milésimos de segundo	histograma com três intervalos, percentis com p75	inp
largest_contentful_paint	int	milésimos de segundo	histograma com três intervalos, percentis com p75	lcp
experimental_time_to_first_byte	int	milésimos de segundo	histograma com três intervalos, percentis com p75	ttfb
form_factors	Número decimais de quatro casas	porcentagem	mapeamento do formato para fração	formatos
navigation_types	Número duplo com quatro casas decimais	porcentagem	Mapeamento do tipo de navegação para fração	tipos de navegação
round_trip_time	int	milésimos de segundo	percentis com p75	rtt

Mapeamento de nome de métrica do BigQuery

Nome da métrica da API CrUX	Nome da métrica do BigQuery
cumulative_layout_shift	layout_instability.cumulative_layout_shift
first_contentful_paint	first_contentful_paint
interaction_to_next_paint	interaction_to_next_paint
largest_contentful_paint	largest_contentful_paint
experimental_time_to_first_byte	experimental.time_to_first_byte
navigation_types	navigation_types
form_factors	N/A
round_trip_time	N/A

Observação:no CrUX BigQuery, as densidades de histograma somam 100% por origem em todos os formatos. Portanto, a métrica form_factors que oferecemos suporte na API é expressa como as densidades de histograma para first_contentful_paint.

Período de coleta

Desde outubro de 2022, a API CrUX contém um objeto collectionPeriod com campos firstDate e endDate que representam as datas de início e término da janela de agregação. Exemplo:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

Isso permite um melhor entendimento dos dados e se eles já foram atualizados para aquele dia ou se estão retornando os mesmos dados de ontem.

A API CrUX está aproximadamente dois dias atrás da data de hoje, porque ela aguarda dados completos do dia e há um tempo de processamento envolvido antes que ela fique disponível na API. O fuso horário usado é o horário padrão do Pacífico (PST, na sigla em inglês) sem mudanças para o horário de verão.

Além disso, o collectionPeriod sempre vai mostrar 28 dias, mesmo que os dados não sejam para os 28 dias completos (por exemplo, se uma página foi lançada há menos de 28 dias). O collectionPeriod é o período em que os dados do CrUX foram agregados, não necessariamente o período que os dados representam.

Exemplos de consultas

As consultas são enviadas como objetos JSON usando uma solicitação POST para https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" com dados de consulta como um objeto JSON no corpo POST:

{
  "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:queryRecord?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"]}'

Observação:o exemplo anterior é para sistemas baseados em macOS ou Linux, incluindo o shell Git BASH para Windows. Outros sistemas podem exigir pequenas modificações. Por exemplo, a linha de comando cmd.exe não permite aspas simples para parâmetros nem a continuação de linhas (\). Portanto, é necessário usar aspas duplas (com escape de aspas internas conforme apropriado com \") e também uma única linha.

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
• navigation_types
• 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 Como usar a API Relatório de UX do Chrome para conferir 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 ficar disponível usando a 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.

Isso é semelhante à forma como o conjunto de dados CRUX no BigQuery agrega relatórios mensais.

Atualizações diárias

Os dados são atualizados diariamente por volta das 04h UTC. 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.

Atenção: os dados não vão ser diferentes no mesmo dia após a atualização por volta das 04h UTC. Chamadas repetidas vão gerar os mesmos resultados.

Esquema

Há um único endpoint para a API CrUX 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:queryRecord

O URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação precisa conter dados com a seguinte estrutura:

{
  "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.
}

Campos
formFactor	enum (FormFactor) O formato é uma dimensão de consulta que especifica a classe de dispositivo a que os dados do registro devem pertencer. Esse campo usa os valores DESKTOP, PHONE ou TABLET. Observação: se nenhum formato for especificado, um registro especial com dados agregados sobre todos os formatos será retornado.
metrics[]	string As métricas que precisam ser incluídas na resposta. Se nenhuma for especificada, todas as métricas encontradas serão retornadas. Valores permitidos: ["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Campo de união url_pattern. O url_pattern é o identificador principal de uma pesquisa de registro. Pode ser apenas um dos seguintes:
origin	string A "origem" url_pattern se refere a um padrão de URL que é a origem de um site. Por exemplo: "https://example.com", "https://cloud.google.com"
url	string O url url_pattern se refere a um padrão de URL que é qualquer URL arbitrário. Por exemplo: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Por exemplo, para solicitar os valores de Largest Contentful Paint para computador da página inicial da documentação para desenvolvedores do Chrome:

{
  "url": "https://developer.chrome.com/docs/",
  "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 ao corpo da solicitação na solicitação anterior pode ser:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

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	enum (FormFactor) O formato é a classe de dispositivo que todos os usuários usaram para acessar o site desse registro. Se o formato não for especificado, os dados agregados de todos os formatos serão retornados.
Campo de união url_pattern. O padrão de URL é o URL ao qual o registro se aplica. url_pattern pode ser apenas de um dos tipos a seguir:
origin	string origin especifica a origem do registro. Observação: ao especificar um origin, os dados de 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	string url especifica um URL específico para este registro. Observação: ao especificar um url, apenas os dados desse URL específico serão agregados.

Métricas

Um metric é um conjunto de dados agregados de experiência do usuário para uma única métrica de desempenho da Web, como a First Contentful Paint. Ele pode conter um histograma de resumo do uso real do Chrome como uma série de bins, dados de percentil específicos (como o p75) ou frações marcadas.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

ou

{
  "fractions": {
    object (Fractions)
  }
}

Campos
histogram[]	object (Bin) O histograma das experiências do usuário para uma métrica. O histograma terá pelo menos um intervalo, e as densidades de todos os intervalos vão somar aproximadamente 1.
percentiles	object (Percentiles) Percentis úteis comuns da métrica. O tipo de valor das percentis será o mesmo dos tipos de valor fornecidos para os intervalos do histograma.
fractions	object (Fractions) Esse objeto contém frações marcadas, que somam aproximadamente 1. As frações são arredondadas para quatro casas decimais.

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,
  "density": number
}

Campos
start	(integer | string) "Start" é o início do contêiner de dados.
end	(integer | string) Fim é o fim do contêiner de dados. Se "end" não for preenchido, o intervalo não terá fim e será válido do início até +inf.
density	number A proporção de usuários que tiveram o valor desse intervalo 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 total de usuários.

{
  "P75": value
}

Campos
p75	(integer | string) 75% dos carregamentos de página tiveram a métrica em questão igual ou menor que esse valor.

Frações

Fractions contém frações marcadas que somam aproximadamente 1. Cada rótulo descreve uma 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 valor distinto específico foi medido.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": 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.

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 automatizadas simples 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
}

Campos
originalUrl	string O URL original solicitado antes de qualquer ação de normalização.
normalizedUrl	string O URL após qualquer ação de normalização. Esse é um URL de experiência do usuário válido que pode ser pesquisado.

Limites de taxas

A API CrUX é limitada a 150 consultas por minuto em cada projeto do Google Cloud, que é oferecido sem custo financeiro. 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.