Measure Core Web Vitals with the PageSpeed Insights API and Chrome UX (CrUX) Report API

1. Before you begin

In this codelab, you learn how to measure a web page's Core Web Vitals with the PageSpeed Insights API and 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 PageSpeed Insights 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

• Web Vitals article
• Basic knowledge of the command line
• Defining the Core Web Vitals metrics thresholds article

What you'll learn

• Measure a web page's Core Web Vitals with the PageSpeed Insights 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 PageSpeed Insights API

1. If you need the performance data for the desktop version of a URL, 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.

At the end of the API string, notice that the strategy query parameter is set to a desktop value, which specifies the request for desktop data.

2. If you need the performance data for the mobile version of a URL, 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=mobile"

Replace the YOUR_URL placeholder with your URL.

At the end of the API string, notice that the strategy query parameter is set to a mobile value, which specifies the request for mobile data.

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

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

Caution: This command applies to macOS, Linux, and Git BASH for Windows. If your machine runs a different operating system or command line, you might need to slightly modify the command. For example, if you use the Command shell on Windows, you need to use double quotes around parameters rather than single quotes. You then need to place a slash before existing double quotes to escape inner quotes.

2. 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 PageSpeed Insights API and CrUX API.

Learn more

• Get Started with the PageSpeed Insights API
• Using the CrUX API
• Web Vitals