SpeedSurgeon Documentation

Run Google PageSpeed Insights from your WordPress admin and get WordPress-specific step-by-step fix instructions for every failing Lighthouse audit — real plugin names, menu paths, and code snippets, not generic web advice.

Overview

SpeedSurgeon brings Google PageSpeed Insights directly into your WordPress admin. Run a scan on any URL, see your Performance, Accessibility, Best Practices, and SEO scores, and get a ranked list of every failing audit — with WordPress-specific fix instructions attached to each one.

The core value is the Translation Layer: a curated map of 30+ Lighthouse audit IDs to WordPress-specific remediation. Instead of "eliminate render-blocking resources," you get: "Install Autoptimize, enable Defer JavaScript, add your Google Fonts URL to Asset CleanUp's exclusion list." Real steps. Real plugins. Real menu paths.

What's included by tier

Feature	No License	Lite / Plus / Pro
Scanner (mobile, desktop, both)	✓	✓
Score circles (Performance, Accessibility, Best Practices, SEO)	✓	✓
Failing / passing audit list	✓	✓
24-hour result caching	✓	✓
WordPress-specific fix steps	✗	✓
Recommended plugin links	✗	✓
Scan history	✗	Plus & Pro
Automatic plugin updates	✗	✓

Installation

Download speedsurgeon.zip from your Boulley Technology account.
In WordPress, go to Plugins → Add New → Upload Plugin.
Choose the zip file and click Install Now, then Activate Plugin.
Go to Tools → SpeedSurgeon → Settings and enter your Google PSI API key and your license key.

SpeedSurgeon requires WordPress 6.0+, PHP 7.4+, and outbound HTTPS access from your server to googleapis.com. Most managed WordPress hosts support this out of the box.

Getting a Google API Key

SpeedSurgeon calls the Google PageSpeed Insights API v5, which requires a free Google API key. The free tier allows 25,000 requests per day — far more than any WordPress site will need.

Go to console.cloud.google.com and sign in with your Google account.
Create a new project (or select an existing one) using the project selector at the top.
In the left menu, go to APIs & Services → Library. Search for PageSpeed Insights API and click Enable.
Go to APIs & Services → Credentials → Create Credentials → API Key.
Copy the generated key. Optionally, click Restrict Key and limit it to the PageSpeed Insights API for security.
Paste the key into Tools → SpeedSurgeon → Settings → Google PSI API Key and click Save.

Restricting the API key to the PageSpeed Insights API (under "API restrictions") is a good security practice — it means the key can't be used for anything else if it were ever exposed.

Running a Scan

Go to Tools → SpeedSurgeon and click the Scanner tab.

URL to Scan — enter any publicly accessible URL. It doesn't have to be your own site. The URL must be reachable by Google's servers (localhost and staging sites behind a firewall cannot be scanned).
Device — choose Mobile, Desktop, or Both. "Both" runs mobile and desktop scans in parallel.
Click Run PageSpeed Scan. Scans typically take 10–30 seconds as Google's Lighthouse engine audits the page.

Cached results

Scan results are cached for 24 hours using WordPress transients. If a cached result exists, you'll see a Cached badge next to the scan timestamp. To force a fresh scan (discarding the cache), click the ↺ Force fresh scan button at the bottom of the results.

Caching is per URL + device combination. A mobile scan for https://example.com/ and a desktop scan for the same URL are cached independently.

Understanding Scores

SpeedSurgeon displays four Lighthouse category scores, each on a 0–100 scale:

Performance — Core Web Vitals and loading speed metrics (LCP, FCP, Speed Index, CLS, TBT, TTI).
Accessibility — Whether the page can be used by people with disabilities (alt text, colour contrast, keyboard navigation, ARIA).
Best Practices — Security, HTTPS, modern web standards, no deprecated APIs.
SEO — Meta tags, crawlability, mobile-friendliness, structured data.

Score colours follow Lighthouse's own thresholds:

Green (90–100) — Good. No urgent action needed.
Orange (50–89) — Needs improvement.
Red (0–49) — Poor. Prioritise fixes here first.

A Performance score of 90+ on mobile is the gold standard. Mobile scores are almost always lower than desktop scores because Lighthouse simulates a mid-range mobile device on a throttled connection.

Audit Results

Below the score circles, failing audits are listed first — sorted by impact (highest-weight audits at the top). Passing audits are collapsed and can be expanded with the Show ▾ button.

Failing audits

Each failing audit shows:

Title — what Lighthouse is checking (e.g. "Eliminate render-blocking resources").
Savings estimate — how much time or bytes fixing this audit could save (e.g. "Est savings of 65 KiB").
Fix instructions (licensed users) — numbered WordPress-specific steps. Click the audit row to expand.
Recommended plugins — direct links to the WordPress.org plugin page for tools that help with this audit.

Passing audits

Passing audits (score ≥ 0.9) are shown in a collapsed section. They represent things your site is already doing right — useful for confirming that a fix you applied is working.

Fix Instructions (Translation Layer)

The Translation Layer is the heart of SpeedSurgeon. It maps Lighthouse audit IDs to WordPress-specific remediation — not generic web performance advice, but step-by-step instructions written for WordPress users.

Supported audits include:

Category	Audits Covered
Performance	LCP, FCP, Speed Index, render-blocking resources, unused CSS/JS, next-gen images, image compression, lazy loading, TTFB, font-display, third-party scripts, main thread work, DOM size, total byte weight, cache lifetimes, preconnect, redirect chains, HTTP/2, legacy JavaScript
SEO	Meta description, canonical, crawlable anchors, link text, robots.txt, tap targets, structured data
Accessibility	Image alt text, colour contrast, heading order, link names, button names, form labels, HTML lang attribute
Best Practices	HTTPS, document.write(), doctype, charset

If a failing audit is not yet in the Translation Layer, you'll see a link to the relevant Lighthouse documentation instead. The map grows with each SpeedSurgeon release.

Fix steps require an active SpeedSurgeon license (Lite, Plus, or Pro). Without a license, you'll see which audits fail but not the step-by-step instructions.

Scan History

The History tab is available on Plus and Pro licenses. It keeps a log of your last 50 scans across all URLs and devices, showing scores over time so you can track the impact of your optimisations.

Each history entry records:

The scanned URL
Device (mobile or desktop)
Performance, Accessibility, Best Practices, and SEO scores
Scan date and time

Click Clear History to wipe all entries. The live cached scan result is unaffected — only the history log is cleared.

History only records live (non-cached) scans. If a result is served from cache, no history entry is written — the existing entry from the original scan is already in the log.

License & Automatic Updates

Enter your license key under Tools → SpeedSurgeon → Settings → License Key and click Activate. A valid license:

Unlocks WordPress-specific fix instructions for every failing audit.
Enables the Scan History tab (Plus and Pro).
Enables automatic plugin updates directly from your WordPress admin (Plugins → SpeedSurgeon will show an update notice when a new version is available).

Your license key is found in your Boulley Technology account under My Licenses.

License tiers

Tier	Sites	Fix Steps	History
Lite	1	✓	✗
Plus	3	✓	✓
Pro	Unlimited	✓	✓

Troubleshooting

"Could not reach the Google API"

Your server can't make outbound HTTPS requests to googleapis.com. This is usually a firewall or cURL SSL certificate issue. Check with your hosting provider that outbound HTTPS is allowed. On local development environments (XAMPP, Local), download a cacert.pem file and set curl.cainfo in your php.ini.

"Scan failed. Please check your API key."

Verify your API key is correct under Tools → SpeedSurgeon → Settings. Also confirm:

The PageSpeed Insights API is enabled in your Google Cloud project (APIs & Services → Library).
If you restricted the key, it allows the PageSpeed Insights API.
You haven't exceeded the free 25,000 requests/day quota.

Scan times out or dies mid-way

PSI scans take 15–30 seconds. If your PHP max_execution_time is 30 seconds, the request may die before the API responds. SpeedSurgeon tries to extend this at runtime via set_time_limit(120). If that doesn't work (some hosts block it), ask your host to raise max_execution_time to at least 60 seconds, or set it in php.ini.

Only Performance score shows; other categories show "—"

This was a bug in SpeedSurgeon 1.0.0 caused by the PSI API receiving category[0]=performance instead of repeated &category= params. It was fixed in 1.0.1. Update the plugin via Plugins → SpeedSurgeon or re-download from your account.

Fix steps not showing (lock icon)

Step-by-step fix instructions require a valid Lite, Plus, or Pro license. Enter your key under Tools → SpeedSurgeon → Settings → License Key.

Scores look different from Google Search Console / PageSpeed web tool

SpeedSurgeon uses the same API as the PageSpeed web tool, so scores should be identical. Minor variations are normal — Lighthouse scores vary slightly between runs due to network variability and server load. For stable readings, run 2–3 consecutive scans and average the results.

FAQ

Do I need a Google API key?

Yes. SpeedSurgeon calls the Google PageSpeed Insights API v5, which requires a key. The free tier allows 25,000 requests per day. Setup takes about 2 minutes — see the Google API Key section above.

Can I scan any URL, or only my own site?

Any publicly accessible URL. The scan is performed by Google's servers, so the URL must be reachable from the public internet. Local development URLs (localhost, .local domains, staging sites behind a firewall or basic auth) cannot be scanned.

Will scanning my site hurt its performance?

No. The scan is triggered manually from your admin, and Google's Lighthouse engine fetches your page from their infrastructure. Your server handles one extra page request from Google — no different from a search engine bot visit.

Why are my scores different every time I scan?

Lighthouse scores vary slightly between runs due to network conditions, server load, and the lab environment Google uses. Variations of ±5 points are normal. Use the 24-hour cache to avoid unnecessary re-scans, and compare trends over time rather than individual scores.

How many Lighthouse audits does the Translation Layer cover?

SpeedSurgeon 1.0.0 covers 30+ of the most common actionable Lighthouse audit IDs across Performance, SEO, Accessibility, and Best Practices. The map grows with each update. If an audit isn't covered yet, you'll see a link to its Lighthouse documentation instead.

Does the plugin store any data about my scans?

Scan results are cached as WordPress transients (in your wp_options table) for 24 hours. Scan history (Plus/Pro) stores a lightweight summary — URL, device, scores, and timestamp — also in wp_options. No data is sent to Boulley Technology servers. The only external calls are to the Google PSI API and to boulleytechnology.ca for license validation and plugin updates.

Can I use SpeedSurgeon on a client's site?

Yes. Each site requires its own license activation. A Plus license covers 3 sites and a Pro license covers unlimited sites — both are a good fit for agencies managing multiple client sites.

Support

For help with SpeedSurgeon, reach out via [email protected]. Include your WordPress version, PHP version, and a brief description of what's happening. If you're seeing a specific error, a screenshot of Tools → SpeedSurgeon with the error visible is very helpful.

Feature requests are welcome — the Translation Layer grows based on which audits customers encounter most often in the wild.