Site Kit by Google ability reference

Date windows that end yesterday, and the period they are compared with

With no dates supplied, every Site Kit read ends yesterday in the site's own timezone and starts 27 days earlier, a 28-day window. Today is left out because its numbers are partial and would read as a drop against any full day. The comparison period has the same number of days and ends the day before start_date. Dates must be strict Y-m-d values: an impossible date, a start after the end, or a span longer than 480 days returns wppilot_site_kit_invalid_date.

Search Console figures lag by two to three days, so the last days of a window can still move. Before drawing a conclusion, the agent should say which dates it read, using the period and previous_period fields that come back with the data.

How many Google requests one Site Kit call spends

wppilot/site-kit-search-pages is the heaviest read. It asks Search Console for up to 500 page rows for the current period plus a one-row totals query, another 500 page rows for the previous period when compare is on, and up to 1,000 query-and-page rows whenever opportunity_limit is above zero. Sending compare: false or opportunity_limit: 0 drops the matching requests. Each request is cached on its own, and the cached flag is true only when every part came from the cache.

wppilot/site-kit-page-insights sends three Search Console requests (current totals, previous totals and the top queries for that URL), one GA4 report and, unless include_pagespeed is false, a PageSpeed run. GA4 reports carry both periods in a single request using named date ranges, so a comparison does not double the Analytics cost. When Google refuses on quota the call returns wppilot_site_kit_quota, and answers cached during the past hour stay available meanwhile.

Reading Search Console and GA4 comparison fields

The comparison fields are computed by GoBuildWP from Site Kit's rows, so their conventions are worth knowing before quoting them to a site owner.

• ctr is a fraction between 0 and 1, rounded to four places; multiply by 100 before calling it a percentage.
• position is an average rounded to one decimal, and position_improvement is the previous position minus the current one, so a positive number means the page or query moved up.
• clicks_pct, impressions_pct and each GA4 change_pct value are null when the previous period was zero, instead of showing an infinite rise.
• On the top-pages list, previous is null when the page had no row among the 500 previous-period pages fetched, so it was absent or very far down, not merely outside the top 25.
• missed_clicks is impressions multiplied by the site CTR, minus actual clicks. A page needs min_impressions (100 by default) to qualify as low CTR, and a query needs min_query_impressions (10 by default) for the position 5 to 20 list.

GA4 metrics, aliases and the shared-dashboard limit

wppilot/site-kit-analytics-report accepts up to 10 metrics from a fixed list (sessions, totalUsers, activeUsers, screenPageViews, engagedSessions, engagementRate, averageSessionDuration, bounceRate, keyEvents, sessionKeyEventRate, ecommercePurchases and eventCount) and orders rows by the first one. conversions is accepted as an alias for keyEvents, because GA4 renamed the measure and people still ask for it by the old name. Dimensions are page, page_title, source_medium, channel, country, device, date or none, and date rows come back in date order instead. Anything else returns wppilot_site_kit_invalid_metric or wppilot_site_kit_invalid_dimension.

source_medium is outside Site Kit's shareable list. A user who reads Analytics through a shared dashboard rather than their own Google sign-in gets wppilot_site_kit_not_shareable for it, and channel is the shareable substitute.

Pointing a Site Kit read at a single page

The per-page calls take post_id or url. A post_id must be a published post the current user can edit, mirroring Site Kit's own rule for post insights; otherwise the call returns wppilot_site_kit_invalid_target or wppilot_site_kit_forbidden. A url may be absolute or a path starting with a slash, and must be on the site's own host (a leading www. is ignored), because Google filters on exact URLs and a page on another host would silently read as no traffic.

In page insights, PageSpeed returns a performance score, lab timings and, only when Google holds field data for that URL, a field block; most low-traffic pages have none. strategy defaults to mobile. A single Lighthouse run is a lab measurement, so report it as such. Only when no section returns any data does the whole call fail, and then it carries the Search Console section's error so the cause is not lost.

What the Site Kit status call shows a non-administrator

wppilot/site-kit-status reads Site Kit's connection route, which only users with googlesitekit_setup may call; for anyone else the site block is null rather than guessed. Per module it reports active, connected, shareable, the owner's user id, the stored property ids and current_user_can_read. If Site Kit refuses its module list, the result adds modules_error and the data calls make the final decision themselves. Every call in the module is a read: nothing is written to Site Kit, Google or site content (only GoBuildWP's own hour-long cache transients), so the module stays available under the Read Only safety profile and there is nothing for the change ledger to record.

• wppilot_site_kit_reauth: the Google sign-in expired or was revoked; the account owner signs in again in Site Kit.
• wppilot_site_kit_google_permission: Google says the connected account cannot see that property; its owner grants access, or Site Kit is reconnected with an account that has it.
• wppilot_site_kit_insufficient_scopes: not every permission was accepted at sign-in; reconnect and accept them all. When nobody has signed in at all, the same Site Kit answer is reported as wppilot_site_kit_not_connected instead.
• wppilot_site_kit_unavailable: Site Kit's REST routes are not registered on the request, usually because Site Kit is inactive or failed to load.