Pagespeed Chrome UX

PageSpeed Insights & Chrome UX Report API Skill

Comprehensive website performance analysis using Google's PageSpeed Insights and Chrome User Experience Report (CrUX) APIs.

Overview

This skill provides two complementary performance analysis tools:

1. PageSpeed Insights (PSI): Lab performance data from Lighthouse audits
2. Chrome UX Report (CrUX): Real-world field data from actual Chrome users

Quick Start

PageSpeed Insights Analysis

python scripts/fetch_pagespeed.py --url "https://example.com"

Chrome UX Report Analysis

python scripts/fetch_crux.py --url "https://example.com"

Bulk Analysis (Both APIs)

python scripts/bulk_analyze.py --urls-file urls.txt

Scripts

1. fetch_pagespeed.py - PageSpeed Insights API

Fetches Lighthouse lab performance data and PSI scores.

Parameters

Categories

Available categories (use comma-separated list or "all"):

• performance - Core Web Vitals and performance metrics
• accessibility - Accessibility audit
• best-practices - Web best practices
• seo - SEO audit
• pwa - Progressive Web App audit

Example Commands

# Basic desktop analysis
python scripts/fetch_pagespeed.py --url "https://example.com"

# Mobile performance only
python scripts/fetch_pagespeed.py --url "https://example.com" --strategy mobile --category performance

# Full audit with all categories
python scripts/fetch_pagespeed.py --url "https://example.com" --category all

# Custom output path
python scripts/fetch_pagespeed.py --url "https://example.com" --output output/psi_example.json

# German locale
python scripts/fetch_pagespeed.py --url "https://example.com" --locale de

Response Data

Returns comprehensive Lighthouse data including:

Performance Metrics:

• First Contentful Paint (FCP)
• Largest Contentful Paint (LCP)
• Total Blocking Time (TBT)
• Cumulative Layout Shift (CLS)
• Speed Index
• Time to Interactive (TTI)

Scores (0-100):

• Performance score
• Accessibility score
• Best Practices score
• SEO score
• PWA score (if applicable)

Additional Data:

• Detailed audit results
• Opportunities for optimization
• Diagnostic information
• Screenshot and filmstrip

2. fetch_crux.py - Chrome UX Report API

Fetches real-world field performance data from actual Chrome users.

Parameters

*Either --url or --origin is required

Available Metrics

Core Web Vitals:

• largest_contentful_paint - LCP in milliseconds
• first_contentful_paint - FCP in milliseconds
• interaction_to_next_paint - INP in milliseconds
• cumulative_layout_shift - CLS (unitless)

Additional Metrics:

• experimental_time_to_first_byte - TTFB in milliseconds
• round_trip_time - RTT in milliseconds
• navigation_types - Navigation type distribution
• form_factors - Device distribution

Example Commands

# Analyze specific URL
python scripts/fetch_crux.py --url "https://example.com/"

# Analyze entire origin (all pages)
python scripts/fetch_crux.py --origin "https://example.com"

# Desktop only with specific metrics
python scripts/fetch_crux.py --url "https://example.com/" --form-factor DESKTOP --metrics largest_contentful_paint,cumulative_layout_shift

# All form factors separately
python scripts/fetch_crux.py --url "https://example.com/" --form-factor all

# Custom output path
python scripts/fetch_crux.py --url "https://example.com/" --output output/crux_example.json

Response Data

Returns 28-day rolling average data including:

For Each Metric:

• Histogram: Distribution across performance bins (good/needs-improvement/poor)
• Percentiles: p75 value (75th percentile)
• Density: Percentage of users in each bin

Additional Info:

• Collection period (28-day window)
• Form factor breakdown
• URL vs Origin data

3. bulk_analyze.py - Bulk URL Analysis

Process multiple URLs through both PageSpeed Insights and Chrome UX Report APIs.

Parameters

*Either --urls-file or --urls is required

Example Commands

# Analyze URLs from file
python scripts/bulk_analyze.py --urls-file urls.txt

# Analyze specific URLs
python scripts/bulk_analyze.py --urls "https://example.com,https://example.com/page1"

# PageSpeed Insights only (mobile)
python scripts/bulk_analyze.py --urls-file urls.txt --api psi --strategy mobile

# Chrome UX only (desktop)
python scripts/bulk_analyze.py --urls-file urls.txt --api crux --form-factor DESKTOP

# Custom output directory
python scripts/bulk_analyze.py --urls-file urls.txt --output-dir output

# Custom delay for rate limiting
python scripts/bulk_analyze.py --urls-file urls.txt --delay 2

Input File Format

Create a text file with one URL per line:

https://example.com/
https://example.com/page1
https://example.com/page2
https://competitor.com/

Output

For each URL, creates separate JSON files:

• {url_safe}_psi_desktop.json - PageSpeed desktop results
• {url_safe}_psi_mobile.json - PageSpeed mobile results
• {url_safe}_crux.json - Chrome UX results

Plus a summary CSV with key metrics for all URLs.

Environment Variables

Required:

GOOGLE_PAGESPEED_API_KEY=your_api_key_here

Get your API key from: https://console.cloud.google.com/apis/credentials

Setup:

1. Go to Google Cloud Console
2. Create/select a project
3. Enable "PageSpeed Insights API" and "Chrome UX Report API"
4. Create credentials (API key)
5. Add to .env file in project root

Rate Limits

PageSpeed Insights:

• No official limit documented
• Recommended: ~1 request per second for bulk operations
• Use API key for higher limits

Chrome UX Report:

• 150 queries per minute per Google Cloud project
• Bulk script includes automatic rate limiting

Data Freshness

PageSpeed Insights:

• Live analysis on each request
• ~30-60 seconds per URL

Chrome UX Report:

• 28-day rolling average
• Updated daily around 04:00 UTC
• ~2 days latency from current date

Output Structure

By default, all files are written under ./output/ in the current working directory:

output/
├── psi_{url}_{strategy}.json
├── crux_{url}.json
└── bulk_summary.csv

Override the location with --output (single-URL scripts) or --output-dir (bulk).

Use Cases

1. Single Page Performance Audit

# Get both lab and field data
python scripts/fetch_pagespeed.py --url "https://example.com"
python scripts/fetch_crux.py --url "https://example.com"

2. Mobile vs Desktop Comparison

python scripts/fetch_pagespeed.py --url "https://example.com" --strategy desktop
python scripts/fetch_pagespeed.py --url "https://example.com" --strategy mobile

3. Bulk Site Analysis

# Analyze entire site or section
python scripts/bulk_analyze.py --urls-file important_pages.txt

4. Competitor Benchmarking

# Compare multiple competitors
python scripts/bulk_analyze.py --urls "https://site1.com,https://site2.com,https://site3.com"

5. Core Web Vitals Monitoring

# Track real user metrics
python scripts/fetch_crux.py --origin "https://example.com" --metrics largest_contentful_paint,cumulative_layout_shift,interaction_to_next_paint

Tips & Best Practices

1. Use CrUX for real data: PageSpeed is lab data; CrUX is real users
2. URL vs Origin: CrUX supports both - URL for specific pages, Origin for domain-wide
3. Rate limiting: Use --delay for bulk operations to avoid rate limits
4. Strategy choice: Mobile is often more important for most sites
5. Cache awareness: Neither API caches results, each call triggers new analysis
6. Insufficient data: CrUX may return empty if URL lacks enough real-user data

Troubleshooting

"GOOGLE_PAGESPEED_API_KEY not found"

• Add API key to .env file in project root

"Insufficient data" from CrUX

• URL doesn't have enough Chrome user traffic
• Try using --origin instead of --url

Rate limit errors (429)

• Increase --delay in bulk operations
• CrUX limited to 150 queries/minute

API key errors (403)

• Ensure APIs are enabled in Google Cloud Console
• Check API key restrictions

API Documentation

• PageSpeed Insights: https://developers.google.com/speed/docs/insights/v5/get-started
• Chrome UX Report: https://developer.chrome.com/docs/crux/api
• Web Vitals: https://web.dev/vitals/