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

## 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.

| Status | Beta |
|  --- | --- |
| Authorization Type | OAuth 2.0 |
| Account Permissions Required | N/A |
| API Versions Supported | Any (v5 as of November 2023) |
| API Scopes Required | openid |
| Supported Methods | GET |
| Supported Endpoints | All |
| Timezone | User-defined |
| Supported Pagination | N/A |
| Rate Limits | N/A |
| API Documentation | https://developers.google.com/speed/docs/insights/v5/about |
| Change Log | https://developers.google.com/speed/docs/insights/release_notes |


## Usage

### How to connect PageSpeed Insights to Databox

Go to **[Data Manager](https://app.databox.com/data-manager/available) > + 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](https://developers.transistor.fm/#intro) for specifics on what parameters should be used.

1. Navigate to **Metrics > [Custom Metrics](https://app.databox.com/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](https://docs.jsonata.org/overview)
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](https://developers.databox.com/metric-definition/#aggregation-functions).
  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.


### Examples

Below is a compiled list of suggested metrics that you can create from this integration.

**Largest Contentful Paint (LCP) - Desktop**

| 
| Endpoint | */v5/runPagespeed* |
| Parameters | *strategy* = DESKTOP *category* = PERFORMANCE *url* = http://your-domain.com |
| JSONata | `{     "value": loadingExperience.metrics.LARGEST_CONTENTFUL_PAINT_MS.percentile / 1000 }` |
| Metric Definition | *Number Format > + New Custom Format > 0.00 s* |


**First Contentful Paint (FCP) - Desktop**

| 
| Endpoint | */v5/runPagespeed* |
| Parameters | *strategy* = DESKTOP *category* = PERFORMANCE *url* = http://your-domain.com |
| JSONata | `{     "value": loadingExperience.metrics.FIRST_CONTENTFUL_PAINT_MS.percentile / 1000 }` |
| Metric Definition | *Number Format > + New Custom Format > 0.00 s* |


**Desktop Time to First Byte (TTFB)**

| 
| Endpoint | */v5/runPagespeed* |
| Parameters | *strategy* = DESKTOP *category* = PERFORMANCE *url* = http://your-domain.com |
| JSONata | `{     "value": loadingExperience.metrics.EXPERIMENTAL_TIME_TO_FIRST_BYTE.percentile / 1000 }` |
| Metric Definition | *Number Format > + New Custom Format > 0.00 s* |


**Interaction to Next Paint (INP) - Desktop**

| 
| Endpoint | */v5/runPagespeed* |
| Parameters | *strategy* = DESKTOP *category* = PERFORMANCE *url* = http://your-domain.com |
| JSONata | `{     "value": loadingExperience.metrics.INTERACTION_TO_NEXT_PAINT.percentile }` |
| Metric Definition | *Number Format > + New Custom Format > 0 ms* |


**First Input Delay (FID) - Desktop**

| 
| Endpoint | */v5/runPagespeed* |
| Parameters | *strategy* = DESKTOP *category* = PERFORMANCE *url* = http://your-domain.com |
| JSONata | `{     "value": loadingExperience.metrics.FIRST_INPUT_DELAY_MS.percentile }` |
| Metric Definition | *Number Format > + New Custom Format > 0 ms* |


**Cumulative Layout Shift (CLS) - Desktop**

| 
| Endpoint | */v5/runPagespeed* |
| Parameters | *strategy* = DESKTOP *category* = PERFORMANCE *url* = http://your-domain.com |
| JSONata | `{     "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.