Get Started with the PageSpeed Insights API

Use the PageSpeed Insights API to:

• Measure the performance of a web page.
• Get suggestions on how to improve the page's performance, accessibility, and SEO.
• Learn how to convert the page into a Progressive Web App.

The PageSpeed Insights API returns real-world data from the Chrome User Experience Report and lab data from Lighthouse.

Prerequisites

This tutorial assumes that you have general knowledge of command line interfaces and web development.

Optional: Set up an API key

If you're just trying out the PageSpeed Insights API, you don't need an API key. If you plan on using the API in an automated way and making multiple queries per second, you'll need an API key.

Acquiring and using an API key

Get a Key

Or create one in the Credentials page.

After you have an API key, your application can append the query parameter key=yourAPIKey to all request URLs.

The API key is safe for embedding in URLs; it doesn't need any encoding.

API Explorer

To make calls to the PageSpeed Insights API without writing any code, check out the API Explorer.

CURL

To try out the PageSpeed Insights API from the command line:

1. Open a terminal.

2. Run the following command. Append &key=yourAPIKey if you're using an API key.

   curl https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://developers.google.com
   

   The response is a JSON object. See Response to learn more about each of the properties in the response object.

   {
    "captchaResult": "CAPTCHA_NOT_NEEDED",
    "kind": "pagespeedonline#result",
    "id": "https://developers.google.com/",
    "loadingExperience": {
     "id": "https://developers.google.com/",
     "metrics": {
      "FIRST_CONTENTFUL_PAINT_MS": {
       "percentile": 3482,
       "distributions": [
        {
         "min": 0,
         "max": 1000,
         "proportion": 0.37151728768042963
        },
        {
         "min": 1000,
         "max": 2500,
         "proportion": 0.4244153519077991
        },
        {
         "min": 2500,
         "proportion": 0.2040673604117713
        }
       ],
       "category": "SLOW"
      },
      "FIRST_INPUT_DELAY_MS": {
       "percentile": 36,
       "distributions": [
        {
         "min": 0,
         "max": 50,
         "proportion": 0.960628961482204
        },
        {
         "min": 50,
         "max": 250,
         "proportion": 0.02888834714773281
        },
        {
         "min": 250,
         "proportion": 0.010482691370063388
        }
       ],
       "category": "FAST"
      }
     },
     "overall_category": "SLOW",
     "initial_url": "https://developers.google.com/"
    },
    "originLoadingExperience": {
     "id": "https://developers.google.com",
     "metrics": {
      "FIRST_CONTENTFUL_PAINT_MS": {
       "percentile": 2761,
       "distributions": [
        {
         "min": 0,
         "max": 1000,
         "proportion": 0.4236433226493666
        },
        {
         "min": 1000,
         "max": 2500,
         "proportion": 0.45045120795679117
        },
        {
         "min": 2500,
         "proportion": 0.1259054693938423
        }
       ],
       "category": "SLOW"
      },
      "FIRST_INPUT_DELAY_MS": {
       "percentile": 45,
       "distributions": [
        {
         "min": 0,
         "max": 50,
         "proportion": 0.9537371485251699
        },
        {
         "min": 50,
         "max": 250,
         "proportion": 0.03044972719889055
        },
        {
         "min": 250,
         "proportion": 0.01581312427593959
        }
       ],
       "category": "FAST"
      }
     },
     "overall_category": "SLOW",
     "initial_url": "https://developers.google.com/"
    },
    "lighthouseResult": {
     "requestedUrl": "https://developers.google.com/",
     "finalUrl": "https://developers.google.com/",
     "lighthouseVersion": "3.2.0",
     "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/72.0.3584.0 Safari/537.36",
     "fetchTime": "2018-11-01T03:03:58.394Z",
     "environment": {
      "networkUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3559.0 Safari/537.36",
      "hostUserAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/72.0.3584.0 Safari/537.36",
      "benchmarkIndex": 590.0
     },
     "runWarnings": [],
     "configSettings": {
      "emulatedFormFactor": "desktop",
      "locale": "en-US",
      "onlyCategories": [
       "performance"
      ]
     },
     "audits": {
      "estimated-input-latency": {
       "id": "estimated-input-latency",
       "title": "Estimated Input Latency",
       "description": "The score above is an estimate of how long your app takes to respond to user input, in milliseconds, during the busiest 5s window of page load. If your latency is higher than 50 ms, users may perceive your app as laggy. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/estimated-input-latency).",
       "score": 1.0,
       "scoreDisplayMode": "numeric",
       "displayValue": "30 ms"
      },
      "uses-rel-preconnect": {
       "id": "uses-rel-preconnect",
       "title": "Preconnect to required origins",
       "description": "Consider adding preconnect or dns-prefetch resource hints to establish early connections to important third-party origins. [Learn more](https://developers.google.com/web/fundamentals/performance/resource-prioritization#preconnect).",
       "score": 1.0,
       "scoreDisplayMode": "numeric",
       "details": {
        "headings": [],
        "type": "opportunity",
        "items": [],
        "overallSavingsMs": 0.0
       }
      },
      ...
     },
     "categories": {
      "performance": {
       "id": "performance",
       "title": "Performance",
       "score": 0.96,
       "auditRefs": [
        {
         "id": "first-contentful-paint",
         "weight": 3.0,
         "group": "metrics"
        },
        {
         "id": "first-meaningful-paint",
         "weight": 1.0,
         "group": "metrics"
        },
        ...
       ]
      }
     },
     "categoryGroups": {
      "a11y-element-names": {
       "title": "Elements Have Discernible Names",
       "description": "These are opportunities to improve the semantics of the controls in your application. This may enhance the experience for users of assistive technology, like a screen reader."
      },
      "a11y-language": {
       "title": "Page Specifies Valid Language",
       "description": "These are opportunities to improve the interpretation of your content by users in different locales."
      },
      ...
     },
     "i18n": {
      "rendererFormattedStrings": {
       "varianceDisclaimer": "Values are estimated and may vary.",
       "opportunityResourceColumnLabel": "Opportunity",
       "opportunitySavingsColumnLabel": "Estimated Savings",
       "errorMissingAuditInfo": "Report error: no audit information",
       "errorLabel": "Error!",
       "warningHeader": "Warnings: ",
       "auditGroupExpandTooltip": "Show audits",
       "passedAuditsGroupTitle": "Passed audits",
       "notApplicableAuditsGroupTitle": "Not applicable",
       "manualAuditsGroupTitle": "Additional items to manually check",
       "toplevelWarningsMessage": "There were issues affecting this run of Lighthouse:",
       "scorescaleLabel": "Score scale:",
       "crcLongestDurationLabel": "Maximum critical path latency:",
       "crcInitialNavigation": "Initial Navigation",
       "lsPerformanceCategoryDescription": "[Lighthouse](https://developers.google.com/web/tools/lighthouse/) analysis of the current page on an emulated mobile network. Values are estimated and may vary.",
       "labDataTitle": "Lab Data"
      }
     }
    },
    "analysisUTCTimestamp": "2018-11-01T03:03:58.394Z"
   }
   

JavaScript

To try out the PageSpeed Insights API from JavaScript:

1. Copy the code below. The code uses the PageSpeed Insights API to measure the performance of https://developers.google.com, and then it displays the results.

   <script>
   function run() {
     const url = setUpQuery();
     fetch(url)
       .then(response => response.json())
       .then(json => {
         // See https://developers.google.com/speed/docs/insights/v5/reference/pagespeedapi/runpagespeed#response
         // to learn more about each of the properties in the response object.
         showInitialContent(json.id);
         const cruxMetrics = {
           "First Contentful Paint": json.loadingExperience.metrics.FIRST_CONTENTFUL_PAINT_MS.category,
           "First Input Delay": json.loadingExperience.metrics.FIRST_INPUT_DELAY_MS.category
         };
         showCruxContent(cruxMetrics);
         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,
           'First Meaningful Paint': lighthouse.audits['first-meaningful-paint'].displayValue,
           'First CPU Idle': lighthouse.audits['first-cpu-idle'].displayValue,
           'Estimated Input Latency': lighthouse.audits['estimated-input-latency'].displayValue
         };
         showLighthouseContent(lighthouseMetrics);
       });
   }
   
   function setUpQuery() {
     const api = 'https://www.googleapis.com/pagespeedonline/v5/runPagespeed';
     const parameters = {
       url: encodeURIComponent('https://developers.google.com')
     };
     let query = `${api}?`;
     for (key in parameters) {
       query += `${key}=${parameters[key]}`;
     }
     return query;
   }
   
   function showInitialContent(id) {
     document.body.innerHTML = '';
     const title = document.createElement('h1');
     title.textContent = 'PageSpeed Insights API Demo';
     document.body.appendChild(title);
     const page = document.createElement('p');
     page.textContent = `Page tested: ${id}`;
     document.body.appendChild(page);
   }
   
   function showCruxContent(cruxMetrics) {
     const cruxHeader = document.createElement('h2');
     cruxHeader.textContent = "Chrome User Experience Report Results";
     document.body.appendChild(cruxHeader);
     for (key in cruxMetrics) {
       const p = document.createElement('p');
       p.textContent = `${key}: ${cruxMetrics[key]}`;
       document.body.appendChild(p);
     }
   }
   
   function showLighthouseContent(lighthouseMetrics) {
     const lighthouseHeader = document.createElement('h2');
     lighthouseHeader.textContent = "Lighthouse Results";
     document.body.appendChild(lighthouseHeader);
     for (key in lighthouseMetrics) {
       const p = document.createElement('p');
       p.textContent = `${key}: ${lighthouseMetrics[key]}`;
       document.body.appendChild(p);
     }
   }
   
   run();
   </script>
   

2. Paste the code into an HTML file.

3. Open the HTML file in a browser. Upon successful completion, your page will look like Figure 1.

   

Next steps

• See Response to learn more about each of the properties in the response object.
• Set up an API key if you plan on making more than 2 queries per second.
• See About the PageSpeed Insights API to learn more about how performance measurements are calculated.

Feedback

Was this page helpful?