Measure Core Web Vitals with the PSI API and CrUX API

1. Before you begin

In this codelab, you learn how to measure a web page's Core Web Vitals with the PageSpeed Insights (PSI) API and Chrome UX Report (CrUX) API.

Both APIs return identical Core Web Vitals data, but each API offers distinct benefits. In addition to CrUX data from the field, the PSI API also provides data from Lighthouse, which is Google's automated and open source tool that audits web pages and recommends how to improve them. The CrUX API doesn't provide Lighthouse data, so it executes faster.

Google recommends that you measure Core Web Vitals across mobile and desktop devices. Core Web Vitals include these three metrics, which apply to all web pages and provide you with critical insight into the user experience:

  • Largest Contentful Paint (LCP). Measures load performance and should occur within 2.5 seconds of when the page begins to load.
  • First Input Delay (FID). Measures interactivity and should occur within 100 milliseconds.
  • Cumulative Layout Shift (CLS). Measures visual stability and should be within 0.1.

Prerequisites

What you'll do

  • Measure a web page's Core Web Vitals with the PSI API.
  • Measure a web page's Core Web Vitals with the CrUX API.

What you'll need

  • A Google Account
  • Access to a command line
  • A text editor of your choice
  • A web browser of your choice
  • A URL of your choice (This codelab uses https://developers.google.com.)

2. Measure Core Web Vitals with the PSI API

  1. If you need the performance data for the desktop version of a URL, run this curl command to request the data from the PageSpeed Insights API and save it in a response.txt file:
curl -o response.txt "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=YOUR_URL&strategy=desktop"

Replace the YOUR_URL placeholder with your URL.

  1. If you need the performance data for the mobile version of a URL, set the strategy query parameter to a mobile value at the end of the API string in the command provided in the previous step:
curl -o response.txt "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=YOUR_URL&strategy=mobile"

Replace the YOUR_URL placeholder with your URL.

  1. In your text editor, open the response.txt file and then find the loadingExperience property:

response.txt

   "loadingExperience": {
    "id": "https://developers.google.com/",
    "metrics": {
      "LARGEST_CONTENTFUL_PAINT_MS": {
        "percentile": 1714,
        "distributions": [
          {
            "min": 0,
            "max": 1000,
            "proportion": 0.49701860391159164
          },
          {
            "min": 1000,
            "max": 3000,
            "proportion": 0.40071951025600261
          },
          {
            "min": 3000,
            "proportion": 0.10226188583240581
          }
        ],
        "category": "AVERAGE"
      },
  },

The loadingExperience property reports this information for each of the Core Web Vitals based on the URL and device type indicated in the API request:

  • The percentile property indicates the 75th percentile for each metric.
  • The distributions property indicates the percentage of page views that had a good, needs improvement, or poor experience for each metric.
  • The category property classifies the performance of each metric as slow, average, or fast.

If the contents of the loadingExperience property are empty, the URL doesn't have enough performance data available. This issue typically arises when you test low-traffic web pages.

  1. Find the originLoadingExperience property:

response.txt

  "originLoadingExperience": {
    "id": "https://developers.google.com",
    "metrics": {
      "LARGEST_CONTENTFUL_PAINT_MS": {
        "percentile": 1649,
        "distributions": [
          {
            "min": 0,
            "max": 1000,
            "proportion": 0.488838781075378
          },
          {
            "min": 1000,
            "max": 3000,
            "proportion": 0.42709617576692827
          },
          {
            "min": 3000,
            "proportion": 0.084065043157693739
          }
        ],
        "category": "AVERAGE"
      },
  },

The originLoadingExperience property reports the aggregated experiences for the entire origin, rather than only the URL. It provides the same information for each of the Core Web Vitals as explained in the previous step.

3. Measure Core Web Vitals with the CrUX API

Get an API key

  1. In Google Cloud Console, search for Chrome UX and then select Chrome UX Report API in the drop-down menu.
  2. On the Chrome UX Report API page, click Enable, and then wait for the Enable button to change to a Manage button and select Manage.
  3. In the navigation menu, click Credentials, and then select Create Credentials > API key and copy the API key.

Make a request

  1. From your command line, request performance data for your URL from the CrUX API and save it in a response.txt file:
curl -o response.txt 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=YOUR_API_KEY' 'Content-Type: application/json' --data '{"url":"YOUR_URL"}'

Replace the YOUR_API_KEY placeholder with your API key and then replace the YOUR_URL placeholder with your URL.

  1. In your text editor, open the response.txt file:

response.txt

{
  "record": {
    "key": {
      "url": "https://developers.google.com/"
    },
    "metrics": {
      "cumulative_layout_shift": {
        "histogram": [
          {
            "start": "0.00",
            "end": "0.10",
            "density": 0.47784335300590036
          },
          {
            "start": "0.10",
            "end": "0.25",
            "density": 0.32379713914174157
          },
          {
            "start": "0.25",
            "density": 0.19835950785235579
          }
        ],
        "percentiles": {
          "p75": "0.23"
        }
      },
    }
  },
}

The CrUX API response provides this information for each of the Core Web Vitals:

  • The histogram property indicates the percentage of users that had a slow, average, or fast experience for a given metric.
  • The percentiles property indicates the 75th percentile observation for a given metric.

If you see an error message that says that the data isn't found, there isn't enough performance data available for the given URL. This issue typically arises when you test low-traffic web pages.

4. Congratulations

Congratulations! You measured a web page's Core Web Vitals with the PSI API and CrUX API.

Learn more