CrUX API

CrUX API를 사용하면 페이지 및 출처 수준의 집계된 실제 사용자 환경 데이터에 지연 시간이 짧게 액세스할 수 있습니다.

사용해 보기

일반적인 사용 사례

CrUX API를 사용하면 'https://example.com 출처의 측정항목 가져오기'와 같이 특정 URI의 사용자 환경 측정항목을 쿼리할 수 있습니다.

CrUX API 키

CrUX API를 사용하려면 Chrome UX Report API 사용을 위해 프로비저닝된 Google Cloud API 키가 필요합니다.

API 키 획득 및 사용

키 가져오기

또는 사용자 인증 정보 페이지에서 만드세요.

API 키가 있으면 애플리케이션은 모든 요청 URL에 쿼리 매개변수 key=yourAPIKey를 추가할 수 있습니다.

API 키는 URL에 포함하기에 안전합니다. 인코딩이 전혀 필요하지 않습니다.

쿼리 예를 참고하세요.

데이터 모델

이 섹션에서는 요청 및 응답의 데이터 구조를 자세히 설명합니다.

녹화

페이지 또는 사이트에 관한 개별 정보입니다. 레코드에는 식별자 및 특정 측정기준 조합에 관한 데이터가 포함될 수 있습니다. 레코드에는 하나 이상의 측정항목에 대한 데이터가 포함될 수 있습니다.

식별자

식별자는 조회할 레코드를 지정합니다. CrUX에서 이러한 식별자는 웹페이지와 웹사이트입니다.

출발지

식별자가 출처인 경우 해당 출처의 모든 페이지에 있는 모든 데이터가 함께 집계됩니다. 예를 들어 http://www.example.com 출처에 다음 사이트맵에 표시된 페이지가 있다고 가정해 보겠습니다.

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

즉, 출처를 http://www.example.com로 설정하여 Chrome UX 보고서를 쿼리하면 http://www.example.com/, http://www.example.com/foo.html, http://www.example.com/bar.html의 데이터가 모두 해당 출처 아래에 있는 페이지이므로 함께 집계되어 반환됩니다.

URL

식별자가 URL인 경우 해당 URL의 데이터만 반환됩니다. http://www.example.com 출처 사이트맵을 다시 살펴봅니다.

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

식별자가 http://www.example.com/foo.html 값으로 URL로 설정된 경우 해당 페이지의 데이터만 반환됩니다.

측정기준

측정기준은 레코드가 집계되는 특정 데이터 그룹을 식별합니다. 예를 들어 PHONE 형식은 레코드에 휴대기기에서 발생한 로드에 관한 정보가 포함되어 있음을 나타냅니다. 각 측정기준에는 특정 개수의 값이 있으며, 암시적으로 해당 측정기준을 지정하지 않으면 측정기준이 모든 값에 대해 집계된다는 의미입니다. 예를 들어 폼 팩터를 지정하지 않으면 레코드에 모든 폼 팩터에서 발생한 로드에 관한 정보가 포함되어 있음을 나타냅니다.

폼 팩터

최종 사용자가 페이지로 이동하는 데 사용한 기기 클래스입니다. PHONE, TABLET, DESKTOP로 분할된 일반적인 기기 클래스입니다.

측정항목

측정항목은 히스토그램, 백분위수, 분수의 통계 집계로 보고됩니다.

부동 소수점 값은 소수점 4자리까지 반올림됩니다. cumulative_layout_shift 측정항목은 문자열로 인코딩된 double이므로 부동 소수점 수로 간주되지 않으며 문자열 내에서 소수점 2자리까지 보고됩니다.

히스토그램

측정항목이 히스토그램으로 표현되면 해당 측정항목의 특정 범위에 해당하는 페이지 로드의 비율이 표시됩니다.

예시 측정항목의 3개 구간 히스토그램은 다음과 같습니다.

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

이 데이터는 페이지 로드의 38.18% 에서 예시 측정항목이 0밀리초에서 1,000밀리초 사이로 측정되었음을 나타냅니다. 측정항목의 단위는 이 히스토그램에 포함되지 않으며, 이 경우에는 밀리초로 가정합니다.

또한 페이지 로드의 49.91% 에서 측정항목 값이 1,000ms~3,000ms였고 11.92%에서는 3,000ms를 초과했습니다.

백분위수

측정항목에는 추가 분석에 유용한 백분위수도 포함될 수 있습니다. Google에서는 해당 측정항목의 지정된 백분위수에서 특정 측정항목 값을 보고합니다. 이는 최종 분류된 데이터가 아닌 사용 가능한 전체 데이터 세트를 기반으로 하므로 최종 분류된 히스토그램을 기반으로 하는 보간된 백분위수와 반드시 일치하지는 않습니다.

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

이 예시에서 페이지 로드의 75% 이상이 측정항목 값 <= 2063로 측정되었습니다.

참고: 각 백분위수의 값은 합성적으로 파생되며, 이는 사용자가 실제로 표시된 값을 경험했음을 의미하지는 않으며, 페이지 로드의 일부 비율에서 주어진 값보다 작은 측정항목 값을 경험했음을 의미합니다.

분수

분수는 특정 방식으로 라벨을 지정할 수 있는 페이지 로드의 비율을 나타냅니다. 이 경우 측정항목 값은 이러한 라벨입니다.

예를 들어 form_factors 측정항목은 지정된 쿼리가 적용되는 폼 팩터 (또는 기기)의 분류를 나열하는 fractions 객체로 구성됩니다.

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

이 경우 페이지 로드의 3.77% 는 데스크톱에서, 2.88% 는 태블릿에서, 93.35% 는 휴대전화에서 측정되어 총 100% 가 됩니다.

측정항목 값 유형

CrUX API 측정항목 이름	데이터 유형	미터법 단위	통계 집계	문서
cumulative_layout_shift	소수점 이하 2자리의 double로 인코딩된 문자열	단위 없음	구간 3개가 있는 히스토그램, p75가 있는 백분위수	cls
first_contentful_paint	int	밀리초	구간 3개가 있는 히스토그램, p75가 있는 백분위수	fcp
interaction_to_next_paint	int	밀리초	구간 3개가 있는 히스토그램, p75가 있는 백분위수	inp
largest_contentful_paint	int	밀리초	구간 3개가 있는 히스토그램, p75가 있는 백분위수	lcp
experimental_time_to_first_byte	int	밀리초	구간 3개가 있는 히스토그램, p75가 있는 백분위수	ttfb
form_factors	소수점 4자리 이중	퍼센트	폼 팩터에서 분수로 매핑	폼 팩터
navigation_types	소수점 4자리 이중	퍼센트	탐색 유형에서 분수로 매핑	탐색 유형
round_trip_time	int	밀리초	p75가 포함된 백분위수	rtt

BigQuery 측정항목 이름 매핑

CrUX API 측정항목 이름	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	해당 사항 없음
round_trip_time	해당 사항 없음

참고: CrUX BigQuery에서 히스토그램 밀도는 폼 팩터별로 출처당 최대 100% 를 더하므로 API에서 지원하는 form_factors 측정항목은 대신 first_contentful_paint의 히스토그램 밀도로 표현됩니다.

수집 기간

2022년 10월부터 CrUX API에는 집계 기간의 시작일과 종료일을 나타내는 firstDate 및 endDate 필드가 포함된 collectionPeriod 객체가 포함됩니다. 예를 들면 다음과 같습니다.

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

이를 통해 데이터를 더 잘 이해하고 해당 날짜에 아직 업데이트되었는지 또는 어제와 동일한 데이터를 반환하는지 확인할 수 있습니다.

참고: CrUX API는 당일 완료된 데이터를 기다리므로 오늘 날짜보다 약 2일 뒤에 제공되며, API에서 사용할 수 있기까지 약간의 처리 시간이 소요됩니다. 사용되는 시간대는 태평양 표준시 (PST)이며 일광 절약 시간은 적용되지 않습니다.

수집 기간은 PageSpeed Insights에서도 확인할 수 있습니다.

PageSpeed Insights의 수집 기간 날짜입니다.

또한 데이터가 28일 동안의 데이터가 아니더라도 (예: 페이지가 28일 전에 출시된 경우) collectionPeriod에는 항상 28일이 표시됩니다. collectionPeriod는 CrUX 데이터가 집계된 기간이며 데이터가 나타내는 기간일 필요는 없습니다.

쿼리 예

쿼리는 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"에 대한 POST 요청을 사용하여 JSON 객체로 제출되며, POST 본문에는 쿼리 데이터가 JSON 객체로 포함됩니다.

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

예를 들어 다음 명령줄을 사용하여 curl에서 호출할 수 있습니다 (API_KEY를 키로 대체).

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"]}'

참고: 위의 예는 Windows용 Git BASH 셸을 비롯한 macOS 또는 Linux 기반 시스템용입니다. 다른 시스템의 경우 약간의 수정이 필요할 수 있습니다. 예를 들어 cmd.exe 명령줄은 매개변수에 작은따옴표나 줄 연속 (\)을 허용하지 않으므로 큰따옴표를 사용해야 합니다 (\"를 사용하여 내부 따옴표를 적절하게 이스케이프 처리). 또한 단일 줄을 사용해야 합니다.

페이지 수준 데이터는 쿼리에서 origin 대신 url 속성을 전달하여 API를 통해 사용할 수 있습니다.

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

metrics 속성이 설정되지 않은 경우 사용 가능한 모든 측정항목이 반환됩니다.

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (요청에 formFactor가 지정되지 않은 경우에만 보고됨)

formFactor 값을 제공하지 않으면 모든 폼 팩터에서 값이 집계됩니다.

쿼리 예시는 Chrome UX Report API 사용을 참고하세요.

데이터 파이프라인

CrUX 데이터 세트는 API를 사용하여 사용할 수 있게 되기 전에 파이프라인을 통해 처리되어 데이터를 통합, 집계, 필터링합니다.

이동 평균

Chrome UX 보고서의 데이터는 집계된 측정항목의 28일 이동 평균입니다. 즉, 특정 시점에 Chrome UX 보고서에 표시되는 데이터는 실제로 지난 28일 동안의 데이터가 집계된 것입니다.

이는 BigQuery의 CrUX 데이터 세트에서 월별 보고서를 집계하는 방식과 유사합니다.

매일 업데이트

데이터는 매일 오전 4시(UTC) 무렵에 업데이트됩니다. 업데이트 시간에 대한 서비스수준계약은 없습니다. 매일 최선을 다해 실행됩니다.

주의: 데이터는 UTC 기준 04:00경에 업데이트된 후 당일에는 다르지 않으며 반복적으로 호출해도 동일한 결과가 반환됩니다.

스키마

CrUX API에는 POST HTTP 요청을 수락하는 단일 엔드포인트가 있습니다. API는 요청된 출처 또는 페이지에 대한 실적 데이터에 해당하는 하나 이상의 metrics가 포함된 record를 반환합니다.

HTTP 요청

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

URL은 gRPC 트랜스코딩 구문을 사용합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함되어야 합니다.

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

필드
formFactor	enum (FormFactor) 폼 팩터는 레코드 데이터가 속해야 하는 기기 클래스를 지정하는 쿼리 측정기준입니다. 이 필드는 DESKTOP, PHONE 또는 TABLET 값을 사용합니다. 참고: 폼 팩터를 지정하지 않으면 모든 폼 팩터의 집계된 데이터가 포함된 특수 레코드가 반환됩니다.
metrics[]	string 응답에 포함해야 하는 측정항목입니다. 지정하지 않으면 발견된 모든 측정항목이 반환됩니다. 허용되는 값: ["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
통합 필드 url_pattern. url_pattern는 레코드 조회의 기본 식별자입니다. 다음 중 하나여야 합니다.
origin	string url_pattern 'origin'은 웹사이트의 출처인 URL 패턴을 나타냅니다. 예: "https://example.com", "https://cloud.google.com"
url	string url_pattern url는 임의의 URL인 URL 패턴을 나타냅니다. 예: "https://example.com/, https://cloud.google.com/why-google-cloud/"

예를 들어 Chrome 개발자 문서 홈페이지의 데스크톱 최대 콘텐츠 페인트 값을 요청하려면 다음을 실행합니다.

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

응답 본문

요청이 성공하면 다음과 같은 구조로 record 객체와 urlNormalizationDetails가 포함된 응답이 반환됩니다.

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

예를 들어 이전 요청의 요청 본문에 대한 응답은 다음과 같습니다.

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

키

Key는 이 레코드를 고유하게 식별하는 모든 측정기준을 정의합니다.

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

필드
formFactor	enum (FormFactor) 폼 팩터는 이 레코드의 사이트에 액세스하는 데 모든 사용자가 사용한 기기 클래스입니다. 폼 팩터를 지정하지 않으면 모든 폼 팩터에 대한 집계된 데이터가 반환됩니다.
통합 필드 url_pattern. URL 패턴은 레코드가 적용되는 URL입니다. url_pattern은 다음 중 하나여야 합니다.
origin	string origin는 이 레코드의 출처를 지정합니다. 참고: origin를 지정하면 모든 페이지에서 이 출처 아래의 로드에 대한 데이터가 출처 수준 사용자 환경 데이터로 집계됩니다.
url	string url은 이 레코드가 적용되는 특정 URL을 지정합니다. 참고: url를 지정하면 해당 URL의 데이터만 집계됩니다.

측정항목

metric는 콘텐츠가 포함된 첫 페인트와 같은 단일 웹 성능 측정항목에 대한 집계된 사용자 환경 데이터 집합입니다. 실제 Chrome 사용량의 요약 히스토그램이 일련의 bins, 특정 백분위 데이터(예: p75)로 포함되거나 라벨이 지정된 분수가 포함될 수 있습니다.

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

또는

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

필드
histogram[]	object (Bin) 측정항목의 사용자 환경 히스토그램 히스토그램에는 하나 이상의 구간이 있으며 모든 구간의 밀도를 합하면 약 1이 됩니다.
percentiles	object (Percentiles) 측정항목의 일반적으로 유용한 백분위수입니다. 백분위수의 값 유형은 히스토그램 구간에 지정된 값 유형과 동일합니다.
fractions	object (Fractions) 이 객체에는 합계가 약 1인 라벨이 지정된 분수가 포함됩니다. 소수점 이하 4자리까지 반올림됩니다.

구간

bin는 시작부터 끝까지 또는 종료가 지정되지 않은 경우 시작부터 양의 무한대까지 확장되는 데이터의 개별적인 부분입니다.

빈의 시작 값과 종료 값은 빈이 나타내는 측정항목의 값 유형으로 지정됩니다. 예를 들어 콘텐츠가 포함된 첫 번째 페인트는 밀리초 단위로 측정되고 int로 노출되므로 측정항목 빈은 시작 유형과 종료 유형에 int32를 사용합니다. 그러나 누적 레이아웃 이동은 단위 없는 소수점으로 측정되며 문자열로 인코딩된 소수점으로 노출되므로 측정항목 빈은 값 유형에 문자열을 사용합니다.

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

필드
start	(integer | string) 시작은 데이터 빈의 시작입니다.
end	(integer | string) End는 데이터 빈의 끝입니다. end가 채워지지 않으면 빈에 끝이 없으며 시작부터 +inf까지 유효합니다.
density	number 지정된 측정항목에서 이 빈의 값을 경험한 사용자의 비율입니다. 밀도는 소수점 이하 4자리로 반올림됩니다.

백분위수

Percentiles에는 특정 통계 백분위수에서 측정항목의 합성 값이 포함됩니다. 이 측정항목은 총 사용자 수 중 특정 비율의 사용자가 경험한 측정항목 값을 추정하는 데 사용됩니다.

{
  "P75": value
}

필드
p75	(integer | string) 페이지 로드의 75% 에서 이 값 이하의 지정된 측정항목이 발생했습니다.

분수

Fractions에는 합계가 약 1이 되는 라벨이 지정된 분수가 포함됩니다. 각 라벨은 어떤 방식으로든 페이지 로드를 설명하므로 이러한 방식으로 표현된 측정항목은 숫자 값 대신 고유한 값을 생성한다고 생각할 수 있으며, 분수는 특정 고유한 값이 측정된 빈도를 나타냅니다.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

히스토그램 빈의 밀도 값과 마찬가지로 각 fraction는 숫자 0.0 <= value <= 1.0이며 합계는 약 1.0입니다.

UrlNormalization

조회 성공 확률을 높이기 위해 URL을 정규화하기 위해 취해진 정규화 작업을 나타내는 객체입니다. 이는 제공된 url_pattern를 조회할 때 실패가 알려진 것으로 간주될 때 취해지는 간단한 자동 변경사항입니다. 리디렉션 따르기와 같은 복잡한 작업은 처리되지 않습니다.

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

필드
originalUrl	string 정규화 작업 전에 요청된 원래 URL입니다.
normalizedUrl	string 정규화 작업 후의 URL입니다. 합리적으로 조회할 수 있는 유효한 사용자 환경 URL입니다.

비율 제한

CrUX API는 Google Cloud 프로젝트당 분당 150개의 쿼리로 제한되며 무료로 제공됩니다. 이 한도와 현재 사용량은 Google Cloud 콘솔에서 확인할 수 있습니다. 이 큰 할당량은 대부분의 사용 사례에 충분하며 할당량을 늘리기 위해 비용을 지불할 수는 없습니다.