API CrUX

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

Faça um teste

Caso de uso comum

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

Chave de API do CrUX

Para usar a API CrUX, é necessário ter uma chave de API do Google Cloud provisionada para uso do Chrome UX Report API.

Como receber e usar uma chave de API

Acessar 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 específica sobre uma página ou 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 o layout deste 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 serão retornados e agregados, porque todas essas páginas estão nessa 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 for definido como 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 em que um registro está sendo agregado. Por exemplo, um formato de PHONE indica que o registro contém informações sobre carregamentos 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, não especificar um formato indica que o registro contém informações sobre carregamentos 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

Informamos as métricas 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 duplas codificadas como uma string, portanto, não são consideradas flutuantes 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 intervalos específicos para essa métrica.

Um histograma de três intervalos para uma métrica de exemplo é assim:

{
  "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 0 ms e 1.000 ms. As unidades da métrica não estão contidas neste histograma. Nesse caso, vamos assumir 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 outras análises. Informamos valores de métricas específicos no percentil indicado para essa métrica. Eles são baseados no conjunto completo de dados disponíveis, e não nos dados agrupados finais. Portanto, não correspondem necessariamente a um percentil interpolado com base no histograma agrupado final.

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

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

Frações

As frações indicam as porcentagens de carregamentos de página que podem ser rotulados de uma maneira específica. Nesse caso, os valores das métricas 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 Double com duas casas decimais codificado como string sem unidade histograma com três agrupamentos, percentis com p75 CLS
interaction_to_next_paint int milésimos de segundo histograma com três agrupamentos, percentis com p75 INP
largest_contentful_paint int milésimos de segundo histograma com três agrupamentos, percentis com p75 LCP
experimental_cumulative_layout_shift_with_softnavs Double com duas casas decimais codificado como string sem unidade histograma com três agrupamentos, percentis com p75 Blog
experimental_interaction_to_next_paint_with_softnavs int milésimos de segundo histograma com três agrupamentos, percentis com p75 Blog
experimental_largest_contentful_paint_with_softnavs int milésimos de segundo histograma com três agrupamentos, percentis com p75 Blog
first_contentful_paint int milésimos de segundo histograma com três agrupamentos, percentis com p75 FCP
experimental_first_contentful_paint_with_softnavs int milésimos de segundo histograma com três agrupamentos, percentis com p75 Blog
experimental_time_to_first_byte int milésimos de segundo histograma com três agrupamentos, percentis com p75 TTFB
form_factors Double com 4 casas decimais porcentagem mapeamento do formato para a fração Formatos
navigation_types Double com 4 casas decimais porcentagem mapeamento do tipo de navegação para a fração Tipos de navegação
experimental_navigation_types_with_softnavs Double com 4 casas decimais porcentagem mapeamento do tipo de navegação para a fração Blog
round_trip_time int milésimos de segundo histograma com três agrupamentos, percentis com p75 Métrica de RTT
largest_contentful_paint_resource_type Double com 4 casas decimais porcentagem mapeamento do tipo de navegação para a fração Tipos de recursos da LCP
largest_contentful_paint_image_time_to_first_byte int milésimos de segundo percentis com p75 Subpartes da LCP
largest_contentful_paint_image_resource_load_delay int milésimos de segundo percentis com p75 Subpartes da LCP
largest_contentful_paint_image_resource_load_duration int milésimos de segundo percentis com p75 Subpartes da LCP
largest_contentful_paint_image_element_render_delay int milésimos de segundo percentis com p75 Subpartes da LCP
experimental_ad_count Double com duas casas decimais sem unidade Somente p75 Contagem de anúncios
experimental_ad_density Double com duas casas decimais sem unidade Somente p75 Densidade de anúncios
experimental_ad_cpu int milésimos de segundo Somente p75 Peso do anúncio: CPU
experimental_ad_kilobytes int KB Somente p75 Ponderação do anúncio: rede

Mapeamento de nomes de métricas 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
experimental_cumulative_layout_shift_with_softnavs experimental.cumulative_layout_shift_with_softnavs
experimental_first_contentful_paint_with_softnavs n/a
experimental_interaction_to_next_paint_with_softnavs experimental.interaction_to_next_paint_with_softnavs
experimental_largest_contentful_paint_with_softnavs experimental.largest_contentful_paint_with_softnavs
navigation_types navigation_types
experimental_navigation_types_with_softnavs n/a
form_factors N/A
round_trip_time round_trip_time
largest_contentful_paint_resource_type N/A
largest_contentful_paint_image_time_to_first_byte N/A
largest_contentful_paint_image_resource_load_delay N/A
largest_contentful_paint_image_resource_load_duration N/A
largest_contentful_paint_image_element_render_delay N/A
experimental_ad_count n/a
experimental_ad_density n/a
experimental_ad_cpu n/a
experimental_ad_kilobytes n/a

Período de coleta

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

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

Isso permite entender melhor os dados e se eles já foram atualizados para o dia em questão ou se estão retornando os mesmos dados de ontem.

O período de coleta também está disponível no PageSpeed Insights:

O PageSpeed Insights mostra as datas do período de coleta em uma dica.
Datas do período de coleta no PageSpeed Insights.

Além disso, o collectionPeriod sempre vai mostrar 28 dias, mesmo que os dados não sejam referentes a todo esse período (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"]}'

Os dados no nível da página estão disponíveis na 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_shift
  • first_contentful_paint
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_cumulative_layout_shift_with_softnavs
  • experimental_first_contentful_paint_with_softnavs
  • experimental_interaction_to_next_paint_with_softnavs
  • experimental_largest_contentful_paint_with_softnavs
  • experimental_navigation_types_with_softnavs
  • 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 (informado apenas se nenhum formFactor for especificado na solicitação)
  • experimental_ad_count (informado apenas para páginas incluídas nas métricas de anúncios)
  • experimental_ad_density (informado apenas para páginas incluídas nas métricas de anúncios)
  • experimental_ad_cpu (informado apenas para páginas incluídas nas métricas de anúncios)
  • experimental_ad_kilobytes (informado apenas para páginas incluídas nas métricas de anúncios)

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

Consulte Como usar a API Chrome UX Report para 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 serem disponibilizados usando a API.

A média contínua

Os dados no Chrome UX Report são uma média contínua de 28 dias de métricas agregadas. Isso significa que os dados apresentados no Chrome UX Report em qualquer momento são, na verdade, dados dos últimos 28 dias agregados.

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

Atualizações diárias

Os dados são atualizados diariamente por volta das 4h UTC. Não há um contrato de nível de serviço para os horários de atualização. Ela é executada diariamente, na medida do possível.

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 sobre a 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 de todos os formatos será retornado.

metrics[]

string

As métricas que devem 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_cumulative_layout_shift_with_softnavs", "experimental_first_contentful_paint_with_softnavs", "experimental_interaction_to_next_paint_with_softnavs", "experimental_largest_contentful_paint_with_softnavs", "experimental_time_to_first_byte", "experimental_navigation_types_with_softnavs", "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", "experimental_ad_count", "experimental_ad_density", "experimental_ad_cpu", "experimental_ad_kilobytes"]

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 do URL que é a origem de um site.

Por exemplo: "https://example.com", "https://cloud.google.com"

url

string

O url_pattern url se refere a um padrão do 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 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 ú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

enum (FormFactor)

O formato é a classe de 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_pattern. O padrão do 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 a que este registro se refere.

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 o qual esse registro é destinado.

Observação: ao especificar um url, somente os dados desse URL específico serão agregados.

Métricas

Um metric é um conjunto de dados agregados da experiência do usuário para uma única métrica de performance 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 percentis específicos (como o p75) ou frações rotuladas.

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

ou

{
  "fractions": {
    object (Fractions)
  }
}
Campos
histogram[]

object (Bin)

O histograma de 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 ~1.

percentiles

object (Percentiles)

Percentis úteis comuns da métrica. O tipo de valor dos percentis será o mesmo dos tipos de valor fornecidos para os bins do histograma.

fractions

object (Fractions)

Esse objeto contém frações rotuladas, que somam ~1.

As frações são arredondadas para quatro casas decimais.

Agrupamento

Um bin é uma parte discreta de dados que vai do início ao fim ou, se nenhum fim for 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 buckets de métricas vão usar int32s para os tipos de início e fim. No entanto, a Cumulative Layout Shift é medida em decimais sem unidade e é exposta como um decimal codificado como uma string. Portanto, os intervalos de métricas vão usar strings para o tipo de valor.

{
  "start": value,
  "end": value,
  "density": number
}
Campos
start

(integer | string)

Start é o início do agrupamento de dados.

end

(integer | string)

End é o fim do intervalo de dados. Se o fim 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 experimentaram o valor desse agrupamento para a métrica em questão.

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 experimentado por uma porcentagem do total de usuários.

{
  "P75": value
}
Campos
p75

(integer | string)

75% dos carregamentos de página apresentaram a métrica em questão com um valor igual ou inferior a esse.

Frações

Fractions contém frações rotuladas que somam ~1. Cada rótulo descreve um carregamento de página de alguma forma. Portanto, as métricas representadas dessa maneira podem ser consideradas como produzindo 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": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Assim como os valores de densidade em agrupamentos de histogramas, cada fraction é um número 0.0 <= value <= 1.0, e a soma deles é de 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 básicas e automatizadas que são feitas quando se sabe que a pesquisa do url_pattern fornecido vai falhar. Ações complexas, como seguir 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 por projeto na nuvem 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 para aumentar a cota.