WPGator Search Insights — Documentation
Issue, verify, manage and report on Learndash certfificates. Supports persistent issuance and evidential records.
Overview
WPGator Search Insights turns first-party Google Search Console data into practical query, landing-page and content-alignment reports inside WordPress.
The plugin imports finalized Web Search data for a recent 28-day period, the preceding 28 days and a 90-day context window. It compares current and previous performance, surfaces transparent Defend, Recover, Grow and Review opportunities, and lets administrators move directly between queries and their associated landing pages.
Global filters and optional query lenses help isolate useful patterns such as question-form searches, test-answer traffic, local intent and potential commercial intent. On-demand Search Term Mentions can check whether an exact query appears in a local page’s title, headings, body content, link text or URLs without storing or scoring the result.
Search Console reports are requested directly by the connected WordPress site and stored in its own database. WPGator’s authorization service handles Google sign-in and token refresh only; it does not receive or analyse the site’s queries, pages or performance reports. The plugin adds no front-end tracking script, analytics tag or visitor cookie.
Requirements
| WordPress | 7.0 or later; WordPress 7.0.2 tested for V1 |
| PHP | 8.1 or later; PHP 8.3 tested |
| Google account | An account with access to at least one Google Search Console property |
| Search Console access | Read-only access to properties available to the connected Google account |
| Google Cloud project | Not required — authorization is handled through the WPGator OAuth service |
| Internet access | The WordPress server must be able to make outbound HTTPS requests to Google and wpgator.tech. |
| Site scope | One selected Search Console property per WordPress installation |
| Search type | Google Web Search data in V1; image, video, news and Discover are not included |
| Search Term Mentions | The selected landing page must belong to the current WordPress site and be publicly reachable. |
| WordPress Multisite | Not supported in V1 |
| Analytics or SEO plugin | Not required; no dependency on Google Analytics, Site Kit or a third-party SEO plugin |
| Licence | Free — no licence key, feature gate or paid tier |
Quick Start
- Install & activate — Requires WordPress 7.0+ and PHP 8.1+. No Google Cloud project, analytics service, SEO plugin or licence key is required.
- Connect Google Search Console — Open Search Insights → Connect and select Connect Google Search Console. Sign in with a Google account that can access the property you want to analyse and approve the read-only permission.
- Select a property — Choose one available Search Console property from the dropdown and save it. WPGator Search Insights analyses one selected property per WordPress installation.
- Synchronize reports — Open the Data tab and select Synchronize datasets. The plugin imports the current and previous 28-day windows plus 90-day context data into the local WordPress database.
- Review your search evidence — Use Opportunities, Queries and Pages to apply filters, inspect query-to-page relationships, run on-demand Search Term Mention checks and export matching results to CSV.
User Guide
Connect Search Console and select a property
Connect a Google account
Open Search Insights → Connect and select Connect Google Search Console. Sign in with a Google account that can access the property you want to analyse.
WPGator Search Insights requests only read-only Search Console access. It cannot edit a property, change its configuration or access Google Analytics, advertising, email or unrelated Google services.
No personal Google Cloud project or API credentials are required. WPGator’s authorization service completes the Google OAuth callback and token refresh without exposing a shared client secret inside the distributed WordPress plugin.
Select a property
After authorization, choose a property from the Search Console property dropdown and save it. The list contains the properties available to the connected Google account and shows the reported permission level.
V1 analyses one selected property at a time. Changing the property does not mix datasets: each imported dataset retains its original property identifier. Previously synchronized data can reappear when you return to that property, but run a new synchronization whenever you need current reporting windows.
| Check connection | Tests the stored Google authorization and refreshes the available property list. |
| Disconnect | Removes locally stored Google credentials and stops future API access. Existing reporting datasets are retained until the plugin is deleted. |
| Save property | Selects the property used by the Opportunities, Queries, Pages and Data tabs. |
manage_options capability.Synchronize Search Console data
Open the Data tab and select Synchronize datasets. Synchronization is manual in V1, allowing the site owner to decide when Google is queried and local reports are replaced.
The plugin retrieves six datasets:
| Dataset | Window | Purpose |
|---|---|---|
| Site query | Current 28 days | Recent property-level query performance |
| Site query | Previous 28 days | Comparison period immediately before the current window |
| Site query | 90-day context | Broader visibility and threshold context |
| Query + page | Current 28 days | Recent query-to-landing-page relationships |
| Query + page | Previous 28 days | Previous query-to-page relationships |
| Query + page | 90-day context | Broader page and query context |
The windows end three complete days before the synchronization date. This avoids treating Google’s most recent and potentially incomplete reporting days as finalized data.
Large datasets are retrieved in pages of up to 25,000 rows. The progress display shows which dataset is being processed. If the administrator returns while an active synchronization is still valid, the plugin can resume it.
A new synchronization is built separately from the completed reports. Existing reports remain available until all six replacement datasets finish successfully.
Metrics, comparison states and opportunities
Reported metrics
| Impressions | The number of impressions reported by Google for the query or landing page. |
| Clicks | Clicks reported by Google Search Console. |
| CTR | Clicks divided by impressions for the relevant dataset. |
| Position | Google’s average position. A lower number represents a stronger average position. |
| Change | Impression difference and, where available, average-position movement between the current and previous windows. |
Comparison states
| New | Appears in the current 28-day window but not the previous one. |
| Persistent | Appears in both 28-day comparison windows. |
| Lost | Appears in the previous window but has no impressions in the current window. |
Opportunity labels
The Opportunities tab applies transparent performance signals using the connected property’s own visibility distribution. Every result includes the evidence that caused its label.
| Defend | A query retaining useful current visibility, commonly a top-10 average position, but showing a material decline in impressions, clicks or position. |
| Recover | A query that previously had useful or above-typical visibility and has materially declined or disappeared from the current window. |
| Grow | A new or improving query with current visibility above the property’s normal level. |
| Review | A query with relatively high visibility but weak clicks or click-through performance that merits a manual check of intent, page fit and search presentation. |
The summary cards are clickable and apply the matching Opportunity Type filter.
Filters and query lenses
Global report filters apply across Opportunities, Queries, Pages and their relevant drill-downs.
| Search queries | Finds queries containing the entered text. Available on Opportunities and Queries. |
| Opportunity Type | Shows only Defend, Recover, Grow or Review results. |
| Minimum impressions | Requires the selected minimum in either the current or previous comparison window. |
| Current average position: Top 10 | Shows records with a current average position of 10 or better. |
| Current average position: Positions 11+ | Shows records with current visibility outside the top 10. |
| No current visibility | Shows records without a current average-position value. |
| Query lens | Applies a deterministic query-pattern view without changing stored data or opportunity classifications. |
Available query lenses
| Question-form | Queries containing a question mark or beginning with a recognized question word. |
| Test / answer-seeking | Queries containing explicit test, quiz, answer-key or similar answer-seeking phrases. |
| Local search intent | Queries containing phrases such as “near me”, “nearby” or “closest”, plus locations configured by the administrator. |
| Potential commercial intent | Queries containing explicit terms such as buy, price, cost, discount, delivery, book, hire or quote. |
Add site-relevant location names and abbreviations under Search Insights → Connect → Query lens settings, one item per line. Up to 100 entries can be saved. These settings remain in the local WordPress database.
Lenses are neutral filters rather than intent judgments. A question-form query may be useful on one site and irrelevant on another. Multiple lenses may conceptually match the same query, but V1 displays one selected lens at a time.
When a lens is active, the Pages tab retains the complete landing-page list and shows the number of matching queries beside View queries. Query rows similarly show the number of matching landing pages beside View pages.
Queries, landing pages and Search Term Mentions
Queries
The Queries tab retains New, Persistent and Lost queries through a full outer comparison of the two 28-day windows. Select a sortable column heading to reorder the results.
Select View pages under a query to see every associated landing page, page-level impression share, current and previous primary pages, and whether the primary page changed between windows.
The Multiple landing pages indicator is neutral. Multiple pages may represent intentional coverage, regional content, product variants or a possible content-overlap issue. The plugin presents the evidence without diagnosing cannibalization.
Pages
The Pages tab aggregates query-plus-page data by landing-page URL. Select View queries to inspect the queries associated with that page while retaining active global filters and query lenses.
The page list shows up to 200 rows on screen. An expanded page shows up to 1,000 matching queries. CSV exports include all matching records beyond those display limits.
Search Term Mentions
Open a Query’s landing pages and select Check mentions. The plugin fetches that public page on demand and counts the exact query phrase in:
| Title | The page’s HTML title element |
| H1, H2 and H3 | Visible headings within the detected page-content area |
| Body | Visible content excluding headings, links, forms, navigation, scripts and interface chrome |
| Link text | Visible link text within the page content |
| href | Normalized link destinations, with common URL separators treated as spaces |
Checks are case-insensitive but retain the query’s exact wording and punctuation. They are not scored, scheduled or persisted. Results remain visible while reviewing the current report and disappear when the admin page reloads.
Search Term Mentions can inspect only a known query-and-page pair on the current WordPress site. The page must be public, return HTTP 200 without a redirect, provide inspectable HTML and remain below the response-size limit.
CSV exports, privacy and data lifecycle
CSV exports
Export the current Opportunities, Queries or Pages report using its Export CSV button. Active search, type, impression, position, lens and sort settings are carried into the export.
Expanded query-to-page and page-to-query sections provide their own contextual exports. Each exported row repeats its source query or landing page so the file remains understandable outside WordPress.
CSV download links are protected by the current administrator’s WordPress capability and a time-limited nonce. Copying an export URL to a signed-out or unauthorized browser does not grant access.
Where data is stored
- Search Console reports are requested directly by the WordPress site from Google.
- Imported reports are stored in two custom tables in that site’s WordPress database.
- Access and refresh tokens are encrypted in a non-autoloaded local WordPress option.
- WPGator’s OAuth relay handles authorization and token refresh but does not receive Search Console reports.
- No front-end tracking script, analytics tag or visitor cookie is added.
Deactivate, disconnect or delete
| Deactivate plugin | Retains the connection, settings and imported datasets for later reactivation. |
| Disconnect Google | Deletes locally stored OAuth credentials, the selected property and cached property list. Imported reporting datasets remain in the database. |
| Delete plugin | Runs the uninstall routine and permanently removes Search Insights options, OAuth credentials, lens locations, synchronization state and both custom reporting tables. |
Troubleshooting
The Google connection window does not open
Allow popups for the WordPress administration page, then select Connect Google Search Console again. Confirm the WordPress server can make outbound HTTPS requests to wpgator.tech and Google.
No Search Console properties are returned
Confirm the connected Google account has permission to view at least one Search Console property. Open Google Search Console with the same account to verify its access, then use Check connection.
Synchronization fails or stops
Use Check connection to confirm authorization, then retry from the Data tab. Check outbound HTTPS access, hosting security rules and server logs for blocked requests to Google APIs or wpgator.tech.
If an earlier synchronization became stale or failed, starting again discards its incomplete temporary run. Previously completed reports remain available until a replacement run finishes.
A new or low-volume property shows little data
Search Console reports only data that Google makes available. New properties, low-impression queries and privacy-protected searches may produce few or no rows. The V1 synchronization also excludes Google’s most recent three reporting days.
Query totals and page totals do not match exactly
This is normally caused by Google’s different property and page aggregation methods. Use the Site query dataset for query-level totals and the Query + page dataset for landing-page relationships and impression share.
Search Term Mentions cannot inspect a page
Confirm the URL belongs to the current WordPress host, is the final canonical URL, returns HTTP 200 without redirecting and is publicly accessible. The optional feature also requires the PHP DOM extension. Protected, external, redirected, oversized or non-HTML pages are rejected.
Only part of a large report appears on screen
Queries and Pages show the first 200 matching rows. Expanded page queries show the first 1,000. The record-count message identifies the complete result size, and CSV export includes all matching rows.
Access is denied
Search Insights reports and actions are restricted to WordPress administrators with manage_options. A copied admin or CSV URL does not bypass the capability check or its nonce.
Developer Notes
OAuth architecture: WPGator Search Insights requests only https://www.googleapis.com/auth/webmasters.readonly. The WPGator OAuth relay owns the shared Google client credentials and handles authorization callback and token refresh. Search Console property and reporting requests are made directly by the connected WordPress installation; reporting data is not proxied through WPGator.
Token storage: Google access and refresh tokens are stored in a non-autoloaded WordPress option using authenticated local encryption. The encryption key is derived from WordPress secret material and a plugin-specific context string rather than stored separately in the database. Tokens are not exposed in HTML, JavaScript configuration, report exports or normal WordPress output.
Dataset storage: Imported metadata and report rows are stored in the site-prefixed wpgso_datasets and wpgso_rows tables. Every dataset records its Search Console property, dataset type, dimensions, reporting window, retrieval run and completion state to prevent cross-property or partial-run contamination.
Synchronization: V1 synchronization is administrator-initiated and processed through bounded AJAX steps. It retrieves Site query and Query + page datasets for the current 28 days, previous 28 days and 90-day context window. API pagination uses batches of up to 25,000 rows. An incomplete replacement run remains isolated; completed reports are replaced only after all six new datasets finish successfully.
Reporting model: Current and previous periods are fetched independently and compared locally using full-outer joins. This retains New, Persistent and Lost queries and page relationships. Opportunity classifications use transparent property-relative thresholds and recorded evidence; they are not conversion, causation or intent scores.
Aggregation: Site query reports use Search Console property aggregation while Query + page reports use page aggregation. Totals can differ legitimately because of Google’s aggregation and privacy behaviour. Query-to-page impression share is calculated from the page-aggregated dataset and should not be treated as a reconciliation of the property-level query total.
Search Term Mentions: Mention checks are synchronous, administrator-requested and non-persistent. The target must be a known query-and-page pair on the current WordPress host. Fetches reject credentials, external hosts, non-standard ports, redirects, non-200 responses and bodies above 5 MB. HTML parsing uses DOMDocument with network access disabled.
Query lenses: Lenses are deterministic, reversible filters over locally stored query strings. They use explicit boundary-aware phrases and optional administrator-defined locations. Lenses never rewrite source rows or alter Defend, Recover, Grow or Review classifications.
Administration security: Connection, property, synchronization, report, drill-down, mention and export handlers independently require manage_options and a valid WordPress nonce. Database writes use bounded, prepared operations. CSV output prefixes values that could otherwise be interpreted as spreadsheet formulas.
Data lifecycle: Deactivation retains settings, credentials and reports. Disconnecting removes local OAuth credentials and selected-property state while retaining imported datasets. WordPress plugin deletion runs the uninstall routine and removes all Search Insights options and both custom reporting tables.
Development relay override: Production uses https://wpgator.tech/wp-json/wpgator-search/v1. Controlled development environments can override this with the wpgso_relay_url filter. Never place shared Google client credentials in the distributed plugin or use this filter to send production tokens to an untrusted service.
Extension boundary: The relay URL filter is the only documented developer override in V1. Internal PHP classes, database tables, option names, AJAX actions, report heuristics and WPGSO_ identifiers are implementation details and are not a stable public extension API.
Changelog
+ Production Google Search Console connection using read-only OAuth access with no user-managed Google Cloud project or API credentials.
+ Local import of Site query and Query + page datasets for current 28-day, previous 28-day and 90-day context windows.
+ Full-outer query and landing-page comparison retaining New, Persistent and Lost search records.
+ Transparent Defend, Recover, Grow and Review opportunity signals using property-relative thresholds and visible supporting evidence.
+ Searchable and sortable Opportunities, Queries and Pages reports with impression, current-position and performance-type filters.
+ Reversible Question-form, Test / answer-seeking, Local search intent and Potential commercial intent query lenses.
+ Administrator-defined location terms for site-specific Local search intent filtering.
+ Bidirectional Query → Pages and Page → Queries drill-downs with current and previous impression share, primary-page indicators and page-change evidence.
+ On-demand Search Term Mention checks across page title, H1–H3 headings, body content, link text and normalized URLs.
+ Complete CSV exports for Opportunities, Queries, Pages and contextual drill-down reports, retaining active filters and sort order.
+ Large-dataset synchronization with 25,000-row API pagination, visible progress and safe recovery from interrupted runs.
~ Search Console reports are requested directly by the connected WordPress site and stored in its local database; WPGator handles authorization and token refresh only.
~ Property-isolated datasets prevent stale or mixed reporting when switching between Search Console properties.
~ Completed reports remain available until all replacement datasets finish successfully.
! Administrator capability and nonce checks protect connection, synchronization, drill-down, mention and CSV actions.
! CSV formula-injection protection and same-site restrictions harden exported data and public-page inspection.
Quick Reference
| WordPress | 7.0 or later; 7.0.2 tested for V1 |
| PHP | 8.1 or later; PHP 8.3 tested. The DOM extension is required for Search Term Mentions. |
| Google access | A Google account with access to at least one verified Search Console property |
| Google Cloud project | Not required — connection is handled through the WPGator OAuth relay |
| Google permission | Read-only Search Console access using webmasters.readonly |
| Search scope | Google Web search data for one selected Search Console property per WordPress installation |
| Report windows | Current 28 days, previous 28 days and 90-day context, ending three complete days before synchronization |
| Report views | Opportunities, Queries and Landing Pages with query-to-page and page-to-query drill-downs |
| Query lenses | Question-form, test / answer-seeking, local-search and potential-commercial-intent filters |
| Search Term Mentions | On-demand exact-phrase checks across the Title, H1–H3, body text, link text and href values of public pages on the connected WordPress site |
| Exports | CSV export for filtered Opportunities, Queries, Landing Pages and drill-down reports |
| Storage | Two site-prefixed local report tables plus encrypted, non-autoloaded OAuth credentials |
| Administration | WordPress administrators with the manage_options capability |
| Tracking | No front-end script, analytics tag, visitor cookie or Google Analytics connection |
| Pricing | Free — no licence key or paid tier required |
| Product information | View WPGator Search Insights |