Guide: Using PageSpeed Insights with Databox (Custom API Integration)

Discover how to integrate PageSpeed Insights and Databox, leveraging PSI's API to analyze and visualize your website's Core Web Vital metrics.

IN THIS ARTICLE

• Overview
• Specification
• Usage
  • How to connect PageSpeed Insights to Databox
  • How to visualize data from PageSpeed Insights
  • Examples
• Observations

Overview

PageSpeed Insights (PSI) performs in-depth analysis of individual URLs, providing granular diagnostic information and actionable suggestions to improve page performance. PSI delivers both lab data (simulated performance) and field data (real-world user experiences), offering a comprehensive breakdown of various performance metrics beyond Core Web Vitals. This tool is ideal for obtaining specific recommendations and detailed insights to enhance the speed and user experience of particular web pages.

Specification

The table below shows how the integration is implemented and provides additional helpful resources and information.

Usage

How to connect PageSpeed Insights to Databox

Go to Data Manager > + New connection. Type PageSpeed Insights in the search bar and click on the Connect button. Next, click on the green Connect now button.

This will open the Authorization window, where you will be prompted to enter your Google login credentials and authorize the Databox app.

How to visualize data from PageSpeed Insights

First you'll need to create Custom Metrics using the Metric Builder. To do that, reference the API documentation for specifics on what parameters should be used.

1. Navigate to Metrics > Custom Metrics to access the Metric Builder.
2. Click the green + New Custom Metric button and select the PageSpeed Insights connection in Data Source drop-down list.
3. Find the relevant endpoint in the API documentation that can be used to return the data you need. The base URL is already predefined, you only need to input the missing part of the chosen endpoint's URL.
4. Add the query parameters. Parameters are required to specify the URL to pull data for, as well as information related to strategy and UTM parameters. They are defined as key-value pairs. Multiple parameters can be added by clicking on the + control.
5. Add any necessary headers. v5 does not require any headers but this could change with future updates to the API.
6. Once you have all necessary fields populated, click on the green Continue button. You will be directed to the Select value step.
7. In the Select value step, select a property in the response that includes the metric value you'd like to use for the metric. A metric value must always be numeric.
8. Once you have selected the value, click on the green Continue button.
9. The Segment by dimension step is optional. This step will be taken into account only when you are trying to create a dimensional metric.
   1. If you'd like to segment your metric by multiple dimensions, choose one to complete during this set up, then start over and select a different dimension until each dimensional metric is created.

   2. To skip this step, select None. 

10. The Select date step is optional as well. You can choose between:
    1. Use current time of storing data (Dynamic): select this option if you want to associate the values with the current time. You'll likely be using this option since the API does not return historical data.
    2. Use a field from response (optional): select this option if there is a date associated with each value.
11. In the Preview & Customize step, you can see the JSONata expression that has been created based on the chosen options.
    

    1. Pro tip: You can customize the JSONata expression in the right-hand panel, if you need further customization. More information about JSONata can be found here

12. To continue, click on the Preview data button to apply the JSONata expression to the response received from the API. You should see a table with dates, values and dimensions (if selected).
13. After you have previewed your data and verified it is working as expected, click on the green Continue button to proceed to the last step of the metric setup.
14. In the Describe metric step, populate the following:
    1. Name your metric: a name for the metric.
    2. Data aggregation: this determines how the data is handled. It impacts the way data is grouped and displayed for longer Date Ranges. Learn more here.
    3. Favorable trend: this affects how comparison values (i.e. deltas) are calculated and displayed on our visualizations. Choose UP if higher values are more disabled, and DOWN otherwise.
15. Once you completed the Describe metric step, click the green Continue button to save the metric in your account. 

{
    "value": loadingExperience.metrics.LARGEST_CONTENTFUL_PAINT_MS.percentile / 1000
}

{
    "value": loadingExperience.metrics.FIRST_CONTENTFUL_PAINT_MS.percentile / 1000
}

{
    "value": loadingExperience.metrics.EXPERIMENTAL_TIME_TO_FIRST_BYTE.percentile / 1000
}

{
    "value": loadingExperience.metrics.INTERACTION_TO_NEXT_PAINT.percentile
}

{
    "value": loadingExperience.metrics.FIRST_INPUT_DELAY_MS.percentile
}

{
    "value": loadingExperience.metrics.CUMULATIVE_LAYOUT_SHIFT_SCORE.percentile
}

Observations

Here are a few points to keep in mind about this integration.

Historical Data: The PageSpeed Insights API lacks historical data for its performance metrics. However, by utilizing Databox, you can gather and accumulate the values received during each sync. This accumulation enables you to approximate and track the changes in performance metrics over time, similar to what is displayed in the Google Search Console reports.

Lab vs Real-World Data: you can distinguish between them by referencing their properties in the response: originLoadingExperience and loadingExperience, respectively.