loading...
Cover image for Monitoring Performance with the PageSpeed Insights API

Monitoring Performance with the PageSpeed Insights API

addyosmani profile image Addy Osmani ・6 min read

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:

pagespeed insights v5 report

psi-score 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.
psi fcp 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 lab 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']).
psi opportunities 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.
psi opportunities 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:

pagespeed insights rum

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

web.dev/measure

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):

pagespeed insights wordpress

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:

pagespeed insights lighthouse viewer

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:

pagespeed insights node module build process output

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

pagespeed insights live demo

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.

pagespeed insights google sheets

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.

pagespeed insights api limits

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

With thanks to Shane Exterkamp for his review

Discussion

pic
Editor guide
Collapse
jakepartusch profile image
Jake Partusch

Thanks Addy, this is super cool! After reading, I was motivated enough to make this into a GitHub Action so I could integrate Page Speed Insights into my CI/CD pipeline 🎉 😃

github.com/JakePartusch/psi-action

Collapse
shmdhussain12 profile image
Mohamed Hussain

Thanks for mentioning the different detailed ways we could use the PSI data and different tools to view the performance data.

I tested the crux.run data and real google big query data, on comparing both seeing some significant difference. Is crux.run is not the crux data?...

Is there a way to find out , for which urls we have the PSI field data, as in crux big query we have only domain based data not particular URL specific data available

Collapse
cruxrun profile image
Crux.Run

Hi there! crux.run is exactly the data from the BigQuery database . If you are seeing a difference it might be a result of aggregating across all connection types and https vs. http aggregation? But yes .. the underlying data is 100% the same

Collapse
ibrahimcesar profile image
Ibrahim Cesar

Addy, I was at last Chrome Dev Summit and your talk about Adaptive Loading really inspired my work. I was eager to test this kind of monitoring tool with the site I work on (a news media outlet in Brazil). But the PSI API gives me results far from the the ones I get on Lighthouse through Audit on Chrome. Per example, now, our performance is scoring 78 but when I use PSI I get 0.03!

Our webapp is a React SSR, using code-splitting, and with the Front Page with several areas on lazy loading. I think this is messing with our scores through PSI API, what approach do you advise us to in order o better automate our performance?

Thanks in advance!

Collapse
portentandy profile image
Andy Schaff

Hey Addy, any updates on PSI API getting the latest updates for Core Web Vitals? It also seems that the API returns an older Lighthouse report (6.3.0 vs latest 6.4.1). Thanks in advance!