Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Google Search Console to Fondoo

Live5 min readUpdated

Connecting Google Search Console lets Fondoo verify your site with Google, submit its sitemap and keep a daily copy of your search performance. Your AI agent can then read clicks, impressions and positions, find pages that are close to page one, and check whether single URLs are indexed.

What Fondoo can do with it

Search Console is not an API-key connector. You sign in with Google once and Fondoo stores the resulting tokens. After that:

  • Verify and register your site (Fondoo-hosted sites). On the next publish_site or deploy_static, Fondoo asks Google for an HTML-tag verification token, adds it to your pages, verifies the property, adds it to your Search Console account and submits https://<your-domain>/sitemap.xml. Later publishes submit the sitemap again.
  • Daily rankings sync. A daily job (08:00 UTC) refreshes the last seven days of final Search Analytics data by query, page and date (sync_search_rankings).
  • Reports from stored data: gsc_performance (totals by query, page or date), gsc_compare_periods (pages and queries that lost clicks) and gsc_opportunities (positions 8 to 20, and high-impression pages with low click-through).
  • Live calls to Google: gsc_sitemaps lists your sitemaps. gsc_inspect_url runs Google's URL Inspection on one HTTPS URL of your site.
  • Status: get_search_connection_status shows connected, property, verified, last sync and last error. It never returns tokens.

Nothing here spends money or deletes data, so no owner approval is needed. Agents need search:read for reads and search:write for connect_search_console.

Before you start

  • A Google account. Search Console has no fee.
  • Fondoo-hosted site: you do not need to verify anything first. Fondoo verifies a URL-prefix property for your site's exact address, for example https://www.example.com/.
  • External site (created with connectedUrl): Fondoo cannot add the tag to a server it does not host. The Google account you connect must already have access to the URL-prefix property for that exact origin.
  • Property types. A Domain property (example.com) covers all subdomains and both http and https, and can only be verified by DNS. A URL-prefix property (https://www.example.com/) covers only URLs that start with that exact prefix, and allows several methods, including an HTML tag (Google). Fondoo always works with the URL-prefix property. If you already verified a Domain property, Google says child properties you add under it are verified automatically (Google).
  • Self-hosting Fondoo: you need your own Google OAuth client. Hosted Fondoo uses Fondoo's own Google app, so skip that step.

Step by step: get your credentials

On hosted Fondoo there is nothing to copy. You approve access in Google's consent screen.

  1. Ask your agent (or call the API) to run connect_search_console for your site. It returns an authorizationUrl.
  2. Open the link within 10 minutes, signed in to the Google account that should own the property. The link works once.
  3. Google asks you to allow two permissions. Allow both:
    • https://www.googleapis.com/auth/webmasters: read Search Console data, add the site and submit sitemaps.
    • https://www.googleapis.com/auth/siteverification: get the verification token and verify the site.
  4. You see "Search Console connected. Publish your site to verify ownership and submit its sitemap." Publish once; that step verifies the site.

External site only: before step 1, add the property yourself. In Search Console, open the property selector → Add property → choose URL prefix → enter your origin, for example https://www.example.com → pick a method → Verify. Leave the tag, file or DNS record in place. Google rechecks it and removes access after a grace period if it is gone (Google).

Self-hosters only (from Fondoo's docs/self-hosting.md):

  1. In Google Cloud, create a project and enable the Google Search Console API and the Site Verification API.
  2. In Google Auth Platform, set up Branding and Audience. While the app is in Testing, add your account as a test user (Google).
  3. Under Clients → Create client, choose Web application. Register exactly https://<your API host>/oauth/google/callback as a redirect URI.
  4. Set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI and a 64-hex-character CONNECTION_ENCRYPTION_KEY (openssl rand -hex 32). Restart the app and worker. Set SEARCH_JOBS_ENABLED=true for the daily sync.

Google gives External apps in Testing status refresh tokens that expire after 7 days (Google). Publish the app, or expect to reconnect weekly.

Connect it in Fondoo

a. In the dashboard. Go to Connections → Connect a tool and find "Search Console" in Find a tool. Connect Google Search Console gives a Connect securely link with these setup steps. It does not start the Google sign-in. Use your agent or REST for that. After you connect, the card moves to Connected with a Reconnect button.

b. By asking your agent. Example prompt: "Connect Google Search Console for my site and give me the Google sign-in link."

connect_search_console({siteId: "YOUR-SITE-ID"})

REST:

curl -X POST https://api.getfondoo.com/v1/ops/connect_search_console \
  -H "Authorization: Bearer $FONDOO_API_KEY" -H "Content-Type: application/json" \
  -d '{"siteId":"YOUR-SITE-ID"}'

Open the returned authorizationUrl yourself. Google's callback runs complete_search_console_connection for you. Do not call it by hand.

Test that it works

  1. Publish the site (publish_site or deploy_static).
  2. Run get_search_connection_status({siteId}). Expect connected: true, your https://.../ property and verified: true.
  3. Run gsc_sitemaps({siteId}). Your sitemap.xml should be listed.
  4. Run get_connection_health({siteId}). The search_console line should be ok.
  5. Rankings appear after the first daily sync. Google's data lags a few days.

Troubleshooting

  • "Search Console is not configured": the server has no Google OAuth settings. On self-hosted Fondoo, set the four environment variables above.
  • "Invalid or expired OAuth state": the link is older than 10 minutes or was already used. Run connect_search_console again.
  • "Offline access required; reconnect with consent": Google returned no refresh token. Run connect_search_console again and approve the consent screen.
  • "Publish to verify the canonical property first": you connected but have not published since, or your domain changed. Publish again. A new custom domain is a new URL-prefix property.
  • "Reconnect Search Console" or "Google API request failed (403)": access was revoked, the test-mode token expired, or (external sites) your Google account cannot see that exact URL-prefix property.
  • "Daily URL Inspection quota exhausted": wait for the next UTC day, or raise inspectionBudget with update_site_settings (1 to 2,000).

Limits, data and security

  • Google's limits: Search Analytics 1,200 queries per minute per site and per user; URL Inspection 2,000 per day and 600 per minute per site (Google).
  • Fondoo's inspection budget is per site per UTC day: the lower of GSC_INSPECTION_DAILY_LIMIT (default 2,000) and the site's inspectionBudget. Failed attempts still count. Google counts on Pacific time and may allow less.
  • Fondoo stores the Google access and refresh tokens encrypted with AES-256-GCM, bound to your site. No operation returns them. It also stores the daily query, page, clicks, impressions, CTR and position rows, and URL inspection history.
  • To switch Google accounts, run connect_search_console again; the new tokens replace the old ones. There is no disconnect operation. To cut access, remove Fondoo's app under Google Account third-party connections.
  • Search Console does not use webhooks with Fondoo.