CrUX 기록 API

게시: 2023년 2월 7일, 최종 업데이트: 2025년 4월 11일

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

사용해 보기

일반적인 사용 사례

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

History API는 일일 CrUX API와 동일한 구조를 따르지만 값이 배열로 제공되고 키가 복수형 이름으로 라벨이 지정됩니다 (예: histogram 대신 histogramTimeseries, p75 대신 p75s).

CrUX API 키

daily API와 마찬가지로 CrUX History API를 사용하려면 Chrome UX Report API 사용을 위해 프로비저닝된 Google Cloud API 키가 필요합니다. 일일 및 기록 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 폼 팩터는 레코드에 휴대기기에서 발생한 로드에 관한 정보가 포함되어 있음을 나타냅니다.

폼 팩터

CrUX History API는 폼 팩터 측정기준별로 집계된 경우에만 사용할 수 있습니다. PHONE, TABLET, DESKTOP로 분할된 일반적인 기기 클래스입니다.

측정항목

히스토그램, 백분위수, 비율과 같은 통계 집계의 시계열로 측정항목을 보고합니다.

히스토그램

측정항목이 히스토그램 배열로 표현되면 각 시계열 항목은 측정항목이 간격에 해당하는 페이지 로드의 비율을 전체에 비례하여 나타냅니다. 데이터 포인트는 API에서 반환한 수집 기간 날짜 순으로 표시되며, 첫 번째 포인트는 가장 빠른 기간이고 마지막 포인트는 가장 최근 수집 기간입니다.

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

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

이 데이터는 페이지 로드의 91.90% 가 기록의 첫 번째 수집 기간 동안 0ms~2,500ms 사이의 예시 측정항목 값을 경험했으며 그다음에는 92.03%, 91.94%... 측정항목의 단위는 이 히스토그램에 포함되지 않으며, 이 경우에는 밀리초로 가정합니다.

또한 페이지 로드의 5.21% 는 기록의 첫 번째 수집 기간에 2,500ms~4,000ms 사이의 예시 측정항목 값을 경험했으며, 페이지 로드의 2.88% 는 기록의 첫 번째 수집 기간에 4,000ms를 초과하는 값을 경험했습니다.

백분위수

측정항목에는 추가 분석에 유용한 백분위수의 시계열도 포함될 수 있습니다.

데이터 포인트는 API에서 반환한 수집 기간 날짜 순으로 표시되며, 첫 번째 포인트는 가장 빠른 기간이고 마지막 포인트는 가장 최근 수집 기간입니다.

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

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

분수

측정항목은 라벨이 지정된 분수의 시계열로 표현될 수 있습니다. 각 라벨은 특정 방식으로 페이지 로드를 설명합니다. 데이터 포인트는 API에서 반환한 수집 기간 날짜 순으로 표시되며, 첫 번째 포인트는 가장 빠른 기간이고 마지막 포인트는 가장 최근 수집 기간입니다.

예:

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

이 예에서 가장 최근 데이터 포인트는 페이지 로드의 14.21% 가 데스크톱에서 발생했고 82.88% 가 휴대전화에서 발생했음을 나타냅니다.

측정항목 값 유형

CrUX History API는 동일한 측정항목 값 유형을 사용하므로 자세한 내용은 일일 CrUX API 측정항목 값 유형 문서를 참고하세요.

측정항목 자격요건

자격 기준에 따라 출처 또는 URL이 CrUX History API의 적용 범위인 일부 수집 기간에만 해당할 수 있습니다. 이 경우 CrUX History API는 요건을 충족하는 데이터가 없는 수집 기간의 histogramTimeseries 밀도에 대해 "NaN"를, percentilesTimeseries에 대해 null를 반환합니다. 차이가 발생하는 이유는 히스토그램 밀도가 항상 숫자인 반면 백분위수는 숫자 또는 문자열일 수 있기 때문입니다 (CLS는 숫자처럼 보이더라도 문자열을 사용함).

예를 들어 두 번째 기간에 요건을 충족하는 데이터가 없는 경우 다음과 같이 표시됩니다.

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

시간이 지남에 따라 자격 요건을 충족했다가 충족하지 않는 URL 또는 출처의 경우 누락된 항목이 많을 수 있습니다.

수집 기간

CrUX History API에는 각 집계 기간의 시작일과 종료일을 나타내는 firstDate 및 endDate 필드 배열이 포함된 collectionPeriods 객체가 포함됩니다. 예를 들면 다음과 같습니다.

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

이러한 수집 기간은 오름차순으로 표시되며 응답의 다른 섹션에 있는 각 데이터 포인트의 기간을 나타냅니다.

History API는 매주 월요일에 업데이트되며 표준 2일 지연에 따라 이전 토요일까지의 데이터를 포함합니다. 이전 40주 동안의 데이터(주당 수집 기간 1회)가 포함됩니다. 기본적으로 25개의 수집 기간이 반환됩니다. 요청에서 "collectionPeriodCount"를 1과 40 사이의 숫자로 설정하여 이를 변경할 수 있습니다.

각 수집 기간에는 이전 28일 동안 집계된 데이터가 포함되며 수집 기간은 주 단위이므로 수집 기간이 겹치게 됩니다. 이동 평균과 유사하며, 이후 각 기간에는 3주 분량의 데이터가 포함되고 1주는 다릅니다.

쿼리 예

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

일일 CrUX API의 queryRecord를 대체하는 queryHistoryRecord를 사용합니다.

본문의 예는 다음과 같습니다.

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

페이지 수준 데이터는 쿼리에서 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
• 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 (요청에 formFactor가 지정되지 않은 경우에만 보고됨)

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

더 많은 쿼리 예시는 CrUX History API 사용 가이드를 참고하세요.

데이터 파이프라인

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

이동 평균

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

History API에는 각각 28일 동안의 여러 수집 기간이 포함되어 있습니다. 각 수집 기간에는 이전 28일 동안 집계된 데이터가 포함되며 수집 기간은 주 단위이므로 수집 기간이 겹치게 됩니다. 이동 평균과 유사하며, 이후 각 기간에는 3주 분량의 데이터가 포함되고 1주는 다릅니다.

주간 업데이트

History API는 매주 월요일 오전 4시 (UTC)경에 업데이트되며 표준 2일 지연에 따라 전주 토요일까지의 데이터를 포함합니다. 여기에는 이전 40주(약 10개월) 동안의 데이터(주당 수집 기간 1회)가 포함됩니다. 기본적으로 시계열당 25개의 항목이 반환되지만 collectionPeriodCount 요청 매개변수를 지정하여 이 값을 재정의할 수 있습니다.

업데이트 시간에 대한 서비스수준계약은 없습니다. 매일 최선을 다해 실행됩니다.

스키마

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

HTTP 요청

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

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

요청 본문

CrUX History API는 일일 CrUX API와 유사한 요청 본문을 사용하며 선택사항인 "collectionPeriodCount" 필드를 하나 추가합니다.

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

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

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

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

이 유사한 요청에는 선택사항인 collectionPeriodCount 필드가 포함되며, https://web.dev 출처의 웹 성능 기록을 약 10개월 동안 제공하는 시계열 항목 40개가 생성됩니다.

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ],
  "collectionPeriodCount": 40
}

응답 본문

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

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

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

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

키

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

측정항목

metric는 콘텐츠가 포함된 첫 페인트와 같은 단일 웹 성능 측정항목의 사용자 환경 데이터 집합입니다. 실제 Chrome 사용의 요약 히스토그램이 일련의 bins로 포함되어 있습니다.

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

또는

"fractionTimeseries": {
  object (Fractions)
}

구간

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

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

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

백분위수

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

{
  "P75": value
}

분수

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

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

히스토그램 빈의 밀도 값과 마찬가지로 각 fraction는 숫자 0.0 <= value <= 1.0이며 합계는 약 1.0입니다. 특정 수집 기간에 측정항목을 사용할 수 없는 경우 모든 분수 배열에서 해당 항목은 'NaN'이 됩니다.

UrlNormalization

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

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

비율 제한

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