Connect Google Search Console

Open a website’s Settings → Integrations → Google Search Console. The website owner signs in to Google, grants read-only access, then explicitly selects a matching property. Team members can read the imported reports.

Choose your property

The Google account needs owner or full-user access to an existing verified property. A Domain property includes its subdomains and protocols; a URL-prefix property covers only its prefix. Betterdata offers the exact domain and its www URL-prefix variant. A parent Domain property is not offered for a child website. Betterdata’s DNS verification is separate from Google’s verification.

Import and freshness

The first import covers up to 90 days, newest first, ending three days ago. A scheduled Worker checks for work every minute and resumes bounded pages. Large properties take longer. Each day appears only after all its datasets finish. Subsequent daily imports refresh the latest seven final-data days. Google may revise older data beyond that window; a reconnect and new property selection rebuilds the initial import.

Reports use Google Web Search and Pacific Time. Default ranges end three days ago; explicit dates are honored and show incomplete coverage when necessary. Google often delays data for 2–3 days. Last import and latest available search date are separate. A successful empty import does not mean the website has search traffic.

Understand the numbers

Clicks are Google clicks, not unique visitors. CTR is total clicks divided by total impressions. Position is weighted by impressions. Property totals are imported separately from page/query rows: Google can omit anonymized queries and return only top rows, so detail totals may differ. Search appearance categories can overlap. Google limits results to 50,000 rows per day per search type; capped days are marked.

Search reports support date ranges, text search, and literal landing-page path prefixes. Country, device and appearance tabs have independent aggregates; they cannot be combined with page filters. Betterdata audience, visitor and goal filters do not apply to this aggregate source and produce an explicit message.

Estimated keyword revenue

Revenue estimates allocate gross successful payments before refunds from each visitor’s first recorded Google organic landing page by the query’s share of all Search Console page clicks for the selected period. Hidden queries retain their share. Estimates require a completely imported period, at least 10 page clicks and 5 query/page clicks. Missing values appear as —. Revenue can be received after the landing visit; this is a period-level allocation, not a conversion-cohort measurement.

Amounts remain separate by currency. URLs match exact hostname and path; http/https versions are pooled. URLs with query strings are excluded from revenue matching because the tracker does not retain full query strings. Unlinked payments, paid-search payments and non-Google sources are excluded. Search queries are never assigned to individual visitors.

Disconnect and permissions

Disconnect stops syncing and deletes this website’s local Google credentials and imported search metrics. It does not revoke the shared Google application grant, which could disrupt other websites. You can revoke that grant in your Google account’s third-party connections. Revoked grants require reconnecting. Website ownership or domain changes invalidate the connection and its report access.

API, exports and MCP

GET /api/search-console?site=SITE_ID&range=30 returns queries, totals, daily metrics and provenance. Use kind=page|country|device|appearance, from/to, path, search, limit (up to 100), and offset. CSV export at /api/search-console/export returns up to 1,000 rows per request; advance offset for more. Exports include dates, imported-day counts and estimated-data labels. The read-only MCP tool is get_search_console.

Operator setup

Use the existing GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, or optionally configure a dedicated GSC_CLIENT_ID and GSC_CLIENT_SECRET pair. Enable the Search Console API, configure the consent screen and any required Google verification, and register the exact callback below on the chosen OAuth client. Enabling the API alone does not register this callback.

https://YOUR_BETTERDATA_HOST/api/integrations/google-search-console/callback

GSC_CLIENT_ID
GSC_CLIENT_SECRET
GSC_ENCRYPTION_KEY

The GSC settings are optional server secrets. Without a dedicated encryption key, Betterdata derives a namespaced key from the existing INTEGRATION_SIGNING_KEY. A dedicated GSC_ENCRYPTION_KEY must contain at least 32 characters. Keep the chosen key stable; changing it without re-encrypting stored grants requires reconnecting. Tokens are AES-GCM encrypted with site/owner binding and are never returned in reports or logs. Apply migration 0028 and deploy the Worker cron configuration through the normal release process. Local tests do not prove Google consent or production scheduling.

Google’s data limits and aggregation guide · Google authorization guide