Google is committed to advancing racial equity for Black communities. See how.

Measure Core Web Vitals with the PageSpeed Insights and CrUX Report APIs

This codelab teaches you how to measure a web page's Core Web Vitals with the PageSpeed Insights and Chrome User Experience Report APIs.

Prerequisites

  • Basic knowledge of how to use a command line

What you'll do

  • 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

  • Access to a command line
  • A URL of your choice
  • A web browser of your choice
  • A Google Account

First, measure a web page's Core Web Vitals with the PageSpeed Insights API.

  1. Open your command line.
  2. Run this command, which uses curl to make a request to the PageSpeed Insights API:
curl -o response.txt "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://developers.google.com"

The command returns performance data for the desktop version of https://developers.google.com and saves it to a file named response.txt.

  1. Open the response.txt file in your text editor.
  2. Find the loadingExperience property, which reports the Core Web Vitals for the URL and device type indicated in the API request. The property's contents look like this code snippet:
   "loadingExperience": {
    "id": "https://developers.google.com/",
    "metrics": {
      "FIRST_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"
      },
  },

It provides the following information for each of the Core Web Vitals:

  • The percentile property indicates the ninetieth percentile observation for each metric.
  • The distributions property indicates the percentage of users that had a slow, average, or fast experience for each metric.
  • The category property classifies the performance of each metric as either slow, average, or fast.
  1. Find the originLoadingExperience property, which reports the aggregated Core Web Vitals for the entire origin, rather than only the URL. The property's contents look like this code snippet:
  "originLoadingExperience": {
    "id": "https://developers.google.com",
    "metrics": {
      "FIRST_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"
      },
  },

It provides the same information for each of the Core Web Vitals as explained in the previous step.

You measured a web page's Core Web Vitals with the PageSpeed Insights API.

Now, measure a web page's Core Web Vitals with the CrUX API.

Get an API key

First, get an API key, which the CrUX API requires.

  1. Navigate to Google Cloud Console.
  2. Type Chrome UX into the search bar.
  3. Select Chrome UX Report API from the drop-down menu that appears.

992e3aa34d6b403a.png

  1. Click Enable.

78209c58dc83d696.png

  1. Click Manage.

c1f166f8b7d7fda4.png

  1. Click Credentials > Create Credentials > API key.

bd93b80cd4d4c41c.png

  1. Copy the API key.

Make a request

Next, make a request to the CrUX API.

  1. Open your command line.
  2. Run this command, which uses curl to make a request to the CrUX API, but replace YOUR_API_KEY with the API key that you created in the previous section.
curl -X POST -o response.txt 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=YOUR_API_KEY' --header 'Accept: application/json' --header 'Content-Type: application/json' --data '{"url":"https://developers.google.com"}'

The command returns performance data for https://developers.google.com and saves it to a file named response.txt.

  1. Open the response.txt file in your text editor.

The CrUX API response looks like this code snippet:

{
  "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 the following 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 seventy-fifth percentile observation for a given metric.

You measured a URL's Core Web Vitals with the CrUX API.

Congratulations! You measured a web page's Core Web Vitals with the PageSpeed Insights and CrUX APIs.

Learn more