Monitoring Performance with the PageSpeed Insights API

The PageSpeed Insights API provides free access to performance monitoring for web pages and returns data with suggestions for how to improve. The V5 API includes lab data from Lighthouse and real-world data from the Chrome User Experience Report (CrUX).

const url = 'https://wordpress.org';
const apiCall = `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${url}`;
const response = await fetch(apiCall);
const json = await response.json();

Teams use the API to build dashboards, custom reports and custom integrations with other user-experience measurement tools. The responses from the API could be used to monitor and graph any of the data from the PageSpeed Insights (PSI) tool:

	The PSI score (json.lighthouseResult.categories.performance.score) is determined by running Lighthouse to analyze lab data about the page. A score at or above 90 is considered fast and below 50 is considered to be slow. See the FAQ for the latest on scoring and bit.ly/perf-variance to learn about score variance.
	If available, PSI will report field metric values (json.loadingExperience.metrics) for First Contentful Paint and First Input Delay data from the Chrome User Experience Report for the origin or page URL.
	PSI uses Lighthouse to analyze a URL, generating a performance score that factors in a number of different metrics in a lab setting, like Time to Interactive (json.lighthouseResult.audits['interactive']).
	The Lighthouse report opportunities (e.g json.lighthouseResult.audits['uses-rel-preload'], json.lighthouseResult.audits['offscreen-images'] etc.) provide suggestions how to improve the page’s performance metrics.
	Thumbnail screenshots from the load of your site are available as base64 images via json.lighthouseResult.audits['screenshot-thumbnails']. The last screenshot from pageload is available via json.lighthouseResult.audits['final-screenshot'].

It's possible to build highly customized reports using PSI data. e.g VRBO, a vacation rentals site, graph real-world data from the PSI API to track long term performance trends to ensure their speed remains competitive within the travel industry:

web.dev/measure uses the exact same backend as PageSpeed Insights and uses this data for historical measurement over time:

It's helpful to become familiar with the structure of the PSI API response. There's extensive metrics info available for lab and field/real-world:

const url = 'https://wordpress.org';
const apiCall = `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${url}`;
fetch(apiCall)
  .then(response => response.json())
  .then(json => {
      // Real-world metrics
      const cruxMetrics = {
      "First Contentful Paint": json.loadingExperience.metrics.FIRST_CONTENTFUL_PAINT_MS.category,
      "First Input Delay": json.loadingExperience.metrics.FIRST_INPUT_DELAY_MS.category
      };
      // Lab metrics
      const lighthouse = json.lighthouseResult;
      const lighthouseMetrics = {
      'First Contentful Paint': lighthouse.audits['first-contentful-paint'].displayValue,
      'Speed Index': lighthouse.audits['speed-index'].displayValue,
      'Time To Interactive': lighthouse.audits['interactive'].displayValue,
      };
      // ...
});

Responses from the PSI API are focused on performance data. That said, you can supply the ?category argument to specify any additional Lighthouse audit categories you would like data for:

curl -i "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://web.dev&category=pwa&category=performance&category=accessibility&category=best-practices&category=seo"

You can also supply a locale or strategy argument (desktop or mobile - which simulates a page load on a median-class device (Moto G4) on a mobile network).

Lighthouse is starting to support Stack Packs - stack-specific recommendations, providing more detailed guidance on how to implement optimizations (e.g WordPress). PSI's API responses also support this so if you're testing a WordPress site, these strings are included (demo URL for wordpress.org):

The PageSpeed Insights Tool also supports fetching PSI API data and rendering it with our official Lighthouse Viewer. Pass ?psiurl as a parameter to see this in action:

One of the tools we built on top of PSI is the psi Node module, offering convenient performance reporting in your build process.

const psi = require('psi');

(async () => {
  // Get the PageSpeed Insights report
  const { data } = await psi('https://web.dev');
  console.log('Speed score:', data.lighthouseResult.categories.performance.score);

  // Output a formatted report to the terminal
  await psi.output('https://theverge.com');
  console.log('Done');
})();

The output of psi looks a little like this when used as a CLI with PageSpeed Insights V5:

To try out the PSI API, check out this Glitch demo using both Lighthouse and CrUX data.

You can also use Google Sheets and a cron job to automate monitoring multiple URLs (e.g competitors) by regularly pinging the PSI API. A handy guide and sheet you can copy are available.

What about third-party resources?

We know third-party scripts are costly. In the top 4 million sites, ~2700 origins are responsible for ~57% of all script execution time. Lighthouse exposes an impact summary for third-party code, available via the API from json.lighthouseResult.audits['third-party-summary'].

PageSpeed Insights API Limits

For infrequent usage, the PSI API functions without an API key.

If you intend to make multiple queries per second however, it is recommended to sign up for a PSI API key. API keys have a daily limit of 25,000 queries a day or 400 queries per 100 seconds. This should be enough for most dashboarding needs. It is also possible to request a higher quota if needed.

What's next for the PSI API?

We hope to bring metrics like Largest Contentful Paint and Cumulative Layout Shift to Lighthouse, CrUX and PageSpeed Insights in 2020. We may also explore better hosted API options for obtaining field-data from CrUX. In the interim, you may be interested in Crux.run, a fast mirror of CrUX reporting data which also has an API.

Additional reading

• How PageSpeed Works - Calibre Blog
• Why is my Lighthouse score different from PSI? - DebugBear
• PageSpeed Insights Monitoring - Treo
• Automate Google PageSpeed Insights with Apps Script
• Monitoring the competition with the Chrome UX Report
• What's in the PageSpeed score?
• Treo Lighthouse field performance plugin (uses the API)

With thanks to Shane Exterkamp for his review