# Pagespeed Chrome UX

> Analyze website performance using Google PageSpeed Insights and Chrome UX Report APIs. Fetch lab and field performance data including Core Web Vitals (LCP, FID, CLS, INP), accessibility scores, SEO metrics, and real-user experience data. Supports single URL analysis and bulk processing.

- Skill: `buzzmatic/pagespeed-chrome-ux` (Agent Skill)
- Install (CLI): `npx skillmds@latest add buzzmatic/pagespeed-chrome-ux`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buzzmatic/pagespeed-chrome-ux/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: Buzzmatic (https://skillmd.com/u/buzzmatic)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/buzzmatic/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
```bash
python scripts/fetch_pagespeed.py --url "https://example.com"
```

### Chrome UX Report Analysis
```bash
python scripts/fetch_crux.py --url "https://example.com"
```

### Bulk Analysis (Both APIs)
```bash
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

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--url` | Yes | - | URL to analyze (must include protocol) |
| `--strategy` | No | desktop | Device type: `desktop` or `mobile` |
| `--category` | No | all | Categories to analyze (comma-separated) |
| `--locale` | No | en | Report language (e.g., en, de, fr) |
| `--output` | No | auto | Custom output path (default: `./output/...`) |

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

```bash
# 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

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--url` | * | - | Specific URL to analyze |
| `--origin` | * | - | Origin (domain) to analyze |
| `--form-factor` | No | all | Device type: `DESKTOP`, `PHONE`, `TABLET`, or `all` |
| `--metrics` | No | all | Specific metrics (comma-separated) |
| `--output` | No | auto | Custom output path (default: `./output/...`) |

*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

```bash
# 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

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--urls-file` | * | - | File with URLs (one per line) |
| `--urls` | * | - | Comma-separated URLs |
| `--api` | No | both | API to use: `psi`, `crux`, or `both` |
| `--strategy` | No | both | PSI strategy: `desktop`, `mobile`, or `both` |
| `--form-factor` | No | all | CrUX form factor |
| `--delay` | No | 1 | Delay between requests (seconds) |
| `--output-dir` | No | `./output` | Output directory |

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

#### Example Commands

```bash
# 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:**
```bash
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
```bash
# 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
```bash
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
```bash
# Analyze entire site or section
python scripts/bulk_analyze.py --urls-file important_pages.txt
```

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

### 5. Core Web Vitals Monitoring
```bash
# 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/