API CrUX

A API CrUX oferece acesso de baixa latência a dados agregados de experiência do usuário real 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 de Chrome UX Report API.

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

Nesta seção, detalhamos 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 pesquisados. 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 agregados, porque são todas as páginas dessa 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 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 relação aos quais um registro está sendo agregado. Por exemplo, um formato 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, implicitamente, 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 de dispositivo que o usuário final usou para acessar a página. Essa é uma classe geral de dispositivos 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 de ponto flutuante de precisão dupla codificados como uma string. Portanto, não são considerados pontos flutuantes e são informados 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 bins 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 considerar 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 específicos de métricas 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 valores de métricas

Mapeamento de nomes de métricas do BigQuery

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 esse dia ou se estão retornando os mesmos dados de ontem.

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

Além disso, o collectionPeriod sempre vai mostrar 28 dias, mesmo que os dados não sejam referentes a esse período completo (por exemplo, se uma página foi lançada há menos de 28 dias). O collectionPeriod é o período em que os dados da 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, é possível chamar isso de curl com a seguinte linha de comando (substitua 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_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 Usar a API Chrome UX Report para mais exemplos de consultas.

Pipeline de dados

O conjunto de dados da 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 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 com base no melhor esforço todos os dias.

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

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

Métricas

Um metric é um conjunto de dados agregados de experiência do usuário para uma única métrica de performance na Web, como o primeiro conteúdo renderizado. 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)
  }
}

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 intervalos 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 usam strings para o tipo de valor.

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

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
}

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 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 agrupamentos de histogramas, cada fraction é um número 0.0 <= value <= 1.0, e a soma deles é aproximadamente 1,0.

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

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 por uma cota maior.