CrUX History API 사용 방법

Johannes Henkel
Johannes Henkel
X GitHub Mastodon
Jasmine Yan
Jasmine Yan
GitHub
Barry Pollard

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

이 가이드에서는 Chrome UX 보고서 (CrUX) History API 엔드포인트를 소개합니다. 이 엔드포인트는 웹 실적 데이터의 시계열을 제공합니다. 이 데이터는 매주 업데이트되며 1주일 간격으로 40개의 데이터 포인트가 포함된 약 6개월의 기록을 확인할 수 있습니다.

이제 원래 CrUX API 엔드포인트의 일일 업데이트와 함께 최신 데이터와 이전 데이터를 모두 빠르게 확인할 수 있으므로 시간이 지남에 따라 웹페이지 변경사항을 확인하는 데 유용한 도구입니다.

이 페이지에서 API 사용해 보기

사용해 보기

일일 CrUX API 쿼리

CrUX API에 관한 이전 도움말을 요약하면 다음과 같은 방법으로 특정 출처의 필드 데이터 스냅샷을 가져올 수 있습니다.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [{
          "start": 0, "end": 2500, "density": 0.9192
        }, {
          "start": 2500, "end": 4000, "density": 0.0513
        }, {
          "start": 4000, "density": 0.0294
        }],
        "percentiles": {
          "p75": 1303
        }
      }
      // ...
    },
    "collectionPeriod": {
      "firstDate": { "year": 2022, "month": 12, "day": 27 },
      "lastDate": { "year": 2023, "month": 1, "day": 23 }
    }
  }
}

이 스냅샷에는 특정 28일 수집 기간(이 경우 2022년 12월 27일부터 2023년 1월 23일까지)의 히스토그램 밀도 값과 백분위수 값이 포함됩니다.

CrUX History API 쿼리

기록 엔드포인트를 호출하려면 URL의 queryRecord를 curl 명령어의 queryHistoryRecord로 변경합니다. 이전 호출과 동일한 CrUX API 키를 사용하면 됩니다. collectionPeriodCount 는 반환할 시계열 항목 수를 지정하며 최대 40개입니다. 지정하지 않으면 기본값은 25입니다.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'

전반적인 응답 모양은 비슷하지만 데이터가 훨씬 많습니다. 이제 단일 데이터 포인트 대신 75번째 백분위수 (p75) 및 히스토그램 밀도 값을 포함하는 필드의 시계열이 있습니다.

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

이 예에서 최대 콘텐츠 페인트 (LCP) 측정항목의 0~2500ms 버킷에 대한 densities 시계열은 [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].입니다. 이러한 밀도는 각각 해당하는 collectionPeriods 항목에서 관찰되었습니다. 예를 들어 다섯 번째 밀도인 0.9183은 2022년 9월 3일에 종료된 다섯 번째 수집 기간의 밀도였고 0.9187은 그 다음 주에 종료된 기간의 밀도였습니다.

즉, 예시에서 마지막 시계열 항목을 해석한 결과 web.dev의 경우 2022년 8월 14일부터 2022년 9월 10일까지 페이지 로드의 91.87% 가 2500ms보다 작은 LCP 값을, 5.27% 가 2500ms와 4000ms 사이의 값을, 2.85% 가 4000ms보다 큰 값을 갖는 것으로 확인되었습니다.

마찬가지로 p75 값의 시계열이 있습니다. 2022년 8월 14일부터 2022년 9월 10일까지의 LCP p75는 1377이었습니다. 즉, 이 수집 기간 동안 사용자 경험의 75% 는 LCP가 1377ms 미만이었고 사용자 경험의 25% 는 LCP가 1377ms보다 컸습니다.

예에서는 6개의 시계열 항목과 수집 기간만 나열하지만 API의 응답은 기본적으로 25개의 시계열 항목과 최대 40개를 제공합니다. 요청에 "collectionPeriodCount": 40이 지정된 경우입니다. 이러한 각 수집 기간의 종료일은 7일 간격의 토요일이므로 "collectionPeriodCount": 40을 사용하면 10개월이 포함됩니다.

지정된 응답에서 히스토그램 버킷 밀도와 p75 값의 시계열 길이는 collectionPeriods 필드의 배열 길이와 정확히 동일합니다. 이러한 배열의 색인을 기반으로 일대일 대응이 있습니다.

페이지 수준 데이터 쿼리

CrUX History API를 사용하면 출처 수준 데이터뿐만 아니라 이전 페이지 수준 데이터에도 액세스할 수 있습니다. 이전에는 BigQuery의 CrUX 데이터 세트를 사용하여 출처 수준 데이터를 사용할 수 있었지만 페이지 수준 이전 데이터 는 사이트에서 데이터를 직접 수집하고 저장한 경우에만 사용할 수 있었습니다. 이제 새 API를 사용하면 이전 페이지 수준 데이터를 잠금 해제할 수 있습니다.

페이지 수준 데이터는 동일한 방식으로 쿼리할 수 있지만 페이로드에서 origin 대신 url을 사용합니다.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"url": "https://web.dev/blog/"}'

페이지 수준 (및 출처 수준) 이전 데이터는 나머지 CrUX와 동일한 자격 요건을 충족해야 하므로 특히 페이지에 완전한 이전 기록이 없을 수 있습니다. 이러한 경우 '누락된' 데이터는 "NaN" 밀도의 경우 histogramTimeseries으로, percentilesTimeseries의 경우 null로 표시됩니다. 차이점은 히스토그램 밀도는 항상 숫자이지만 백분위수는 숫자 또는 문자열일 수 있다는 것입니다 (CLS는 숫자처럼 보이더라도 문자열을 사용함).

데이터 시각화

데이터를 시각화하는 가장 쉬운 방법은 CrUX Vis를 사용하는 것입니다. 이 도구는 CrUX History API의 기능을 보여주기 위해 특별히 만들어졌습니다. 자세한 내용은 CrUX Vis 문서를 참고하세요.

비슷한 차트를 직접 생성할 수 있도록 예시 Colab을 만들었습니다. Colab 또는 'Colaboratory'를 사용하면 브라우저 내에서 Python을 작성하고 실행할 수 있습니다. CrUX History API Colab (소스) 은 Python을 사용하여 API를 호출하고 데이터를 차트로 표시합니다.

이 Colab을 사용하면 간단한 양식을 작성하여 p75 차트, 3개 버킷 차트를 만들고 표 형식으로 데이터를 가져오고 CrUX API의 요청 및 응답 쌍을 확인할 수 있습니다. 프로그래머가 아니어도 사용할 수 있지만 Python 코드를 살펴보고 멋진 코드로 수정할 수 있습니다.

이것은 이 새 API를 사용하는 방법의 한 가지 예일 뿐입니다. JSON 기반 HTTP 엔드포인트인 API는 모든 기술에서 쿼리할 수 있습니다.

결론

CrUX History API 엔드포인트가 도입되기 전에는 사이트 소유자가 CrUX에서 얻을 수 있는 이전 정보가 제한적이었습니다. BigQuery를 사용하여 월별 출처 수준 데이터를 사용할 수 있었지만 주간 데이터나 페이지 수준 이전 데이터는 사용할 수 없었습니다. 사이트 소유자는 일일 API를 사용하여 이 데이터를 직접 기록할 수 있지만 측정항목이 회귀된 후에야 이 데이터가 필요한 경우가 많았습니다.

이 CrUX History API를 도입함으로써 사이트 소유자가 변화하는 사이트 측정항목을 더 잘 이해하고 문제가 발생할 때 진단 도구로 사용할 수 있기를 바랍니다. 새 API를 사용하는 경우 Chrome UX 보고서 (토론) Google 그룹에서 의견을 보내주세요.