Manage Google Search Console for a Wix Site

The GSC Connection API links a Google account to the site. The GSC Site Readiness API acts through that account: verifies ownership, adds the Search Console property, submits the sitemap, requests indexing, reads search performance and URL inspection. Both select the site from the caller's authorization context and take no site ID. Use the site already selected in the environment. If none is selected, list the available sites. Select the only site automatically; if several are available, ask the user to choose by name before making site-specific calls. Never invent a site ID or ask the user to type one.

All endpoints are under https://www.wixapis.com: Connection calls under /gsc/connection/v1, everything else under /gsc/v1.

Start every task with two reads

Both are side-effect free. Do them before describing the site's state.

Read them together:

blockingReason is UNKNOWN_BLOCKING_REASON when the status is READY; not an error. Treat an unrecognized reason as "not ready, no known next action".

READY covers connection and verification only. Whether the property was added, the sitemap submitted, or indexing requested comes from List Events.

VALID can be stale, and MISSING_TOKEN means reconnect

INVALID is only written when a real call to Google is rejected, so a site nobody has queried since its credentials broke keeps reporting VALID. The tell arrives on the first Google-facing call:

The reference describes MISSING_TOKEN as "no Google account is connected"; it also fires when the stored credentials are gone while Get Connection still said VALID. Either way: the Google account must be reconnected. Do not retry, and do not tell the user the site is connected.

Connect a Google account

Get Connect URL is GET, but it writes: every call starts a new single-use authorization attempt (two-hour expiry) and Get Connection reports PENDING while it is open. Use Get Connection to check connection status. Call Get Connect URL when starting a connection or reconnection attempt; while the user completes that attempt, use Get Connection for status checks. Request a new URL when a new attempt is needed, such as after expiry. On an already-connected site it is allowed: the same Google account refreshes the credentials, a different one replaces the connection. Say which before you do it.

1. Read Get Connection. If VALID, stop unless the user wants to reconnect.

2. Call Get Connect URL. The request takes no parameters or body.

   Copy

   Copy

   The response above is illustrative. Wix generates the authorization URL, including its OAuth query parameters. Give the user the exact returned connectUrl; do not construct, modify, or reuse the example URL.

3. Give the URL to the user and ask them to tell you when they have finished. Wix completes the exchange server-side; there is no code to send back.

4. When the user says they are done, read Get Connection once and confirm VALID. Do not poll while waiting. If it is still PENDING, the user has not finished; if the attempt expired (two hours), request a fresh URL only after they agree.

Writes need a published, indexable site with a connected domain

Get Connect URL, Verify Site, Add Site, and Submit Sitemap fail with FAILED_PRECONDITION until the site is published, has a connected (premium) domain, and allows indexing. The code names the first failing check:

Codes: SITE_NOT_PUBLISHED, DOMAIN_NOT_CONNECTED, SITE_NOT_INDEXABLE. A free site on a wixsite.com address cannot complete these writes. Report the missing prerequisite and stop. When listing sites to find one that qualifies, filter for premium sites with a connected domain.

Set the site up in Search Console

Run the steps the user asked for, in this order, confirming before each write. Bodies are empty unless shown.

All succeed with {}. Re-read Get Site Readiness after each step and act on the current blockingReason. Verify Site on an already-verified site returns {} and re-stamps the SITE_VERIFIED event date: safe, but not a change to report.

Two Google-side failures are retryable. RESOURCE_EXHAUSTED (GOOGLE_QUOTA_EXCEEDED): the quota is daily, tell the user to retry tomorrow. UNAVAILABLE (GOOGLE_UNAVAILABLE): retry once after a few seconds. On any other error your next message is the final response: name the step that failed and the error code, and make no further Search Console calls.

Check what was done: List Events and List Sitemaps

One entry per event type with the date it last occurred, not sorted by date: never read the last entry as the latest event. Types: ACCOUNT_CONNECTED, SITE_VERIFIED, SITE_ADDED, SITEMAP_SUBMITTED, SITE_INDEXING_REQUESTED, PAGE_INDEXING_REQUESTED. A missing type means that step never happened.

Wix submits several sitemaps, typically one per content type. pending: true with an empty type means Google has not processed it yet. Counts are strings.

Read search performance

• startDate and endDate are required, YYYY-MM-DD, end inclusive.
• dimensions repeats: date, query, page, country, device, searchAppearance; omit for one aggregate row. keys follow your order.
• type: web (default), image, video, news. Page with rowLimit/startRow.
• It is Google's own report: the latest days are usually missing, and there is no history from before the property was added. Empty results is a real answer.

Inspect pages

Page IDs are Wix static-page IDs, not URLs. Discover them with List Item SEO Tags for STATIC_PAGE. The request has no body:

Relevant response fields (unrelated SEO fields omitted; IDs are illustrative):

If pagingMetadata.hasNext is true, pass pagingMetadata.cursors.next back as paging.cursor in the next request's query string, URL-encoded. Continue until hasNext is false. The optional paging.limit controls the page size; omit the cursor on the first request. Treat cursors as opaque.

Use each selected entry's itemId as a pageIds entry for Inspect URLs. Do not use the composite id (STATIC_PAGE:c1dmp) or a page URL, and never invent an ID. The example below assumes discovery returned c1dmp for the selected page.

• data.inspectionResultLink is returned by Google. The complete URL above is illustrative; use the actual returned link unchanged, including its query parameters. Do not construct a link from the example values.
• Each page spends one unit of the account's Google quota (2,000 per property per day): confirm the page list first. Sites over 2,000 pages fail with SITE_EXCEEDS_INSPECTION_LIMIT.
• The site stores one inspection; without updateResults: true a new call replaces it. Prefer true unless the user wants a clean run.
• ONGOING: poll GET https://www.wixapis.com/gsc/v1/inspection every few seconds until COMPLETE or ERROR (same shape plus updatedDate).
• remainingPageCount > 0 on COMPLETE means quota ran out. Name the missing pages; do not call it done.
• data is Google's raw URL Inspection payload: read indexStatusResult.verdict (PASS, PARTIAL, FAIL, NEUTRAL) and coverageState; text is English only. UNKNOWN_INSPECTION_STATUS with empty results means never inspected.

Disconnect and clear

Two different removals; confirm which one the user wants.

Neither removes the site from Search Console or revokes Wix's access on Google's side. Disconnect with no stored credentials returns NOT_FOUND (CONNECTION_NOT_FOUND).

When a call fails

• 403 or PERMISSION_DENIED: stop after the first and report the missing SEO permission (reads need view access to SEO settings, writes need manage access). Do not try another site, path, or method.
• FAILED_PRECONDITION: act on details.applicationError.code as above. Do not retry the same call.
• Get Connect URL is a recovery step only for MISSING_TOKEN, INVALID, or TOKEN_INVALID, and only after the user agrees to reconnect.