Google Search Console

Knowi connects directly to the Google Search Console API to pull search performance data, keyword rankings, page-level metrics, and sitemap information into a single analytics platform.

Analyze your organic search queries, impressions, clicks, CTR, and average position alongside data from your other sources - no manual CSV exports or spreadsheet wrangling needed.

Overview

Knowi integrates with the Google Search Console API (Webmasters API v3) via OAuth 2.0. Once connected, you can pull search analytics data broken down by query, page, country, device, date, and search appearance. You can also list your verified properties and sitemaps.

All data access is read-only. Knowi does not modify your Search Console properties, sitemaps, or settings.

Prerequisites

Before connecting, make sure you have the following:

• A Google account with access to one or more verified properties in Google Search Console.
• At least one verified site (either a URL-prefix property like https://www.example.com or a domain property like sc-domain:example.com).
• Sufficient permissions on the property - you need at least Full or Restricted user access (Owner is not required for read-only data).

Connecting

1. Log in to Knowi and select "Queries" from the left sidebar.
2. Click on the "New Datasource +" button and select Google Search Console from the list of datasources.
3. Click "Connect with Google" to start the OAuth flow. You will be redirected to Google to authorize Knowi to access your Search Console data with read-only permissions (scope: webmasters.readonly).
4. After approving, you'll be redirected back to Knowi. Enter a Datasource Name (e.g., "Search Console - knowi.com") and click "Save".
5. Select a collection from the dropdown to start querying your search data.

Note: If your Google access token expires or you change your Google password, you will need to reconnect by clicking "Connect with Google" again.

URL Encoding

Several collections require a siteUrl parameter. This value must be URL-encoded.

URL-prefix properties

Encode the full URL:

https://www.example.com  -->  https%3A%2F%2Fwww.example.com
http://example.com       -->  http%3A%2F%2Fexample.com

Domain properties

Domain properties use the sc-domain: prefix. Encode the entire string:

sc-domain:example.com  -->  sc-domain%3Aexample.com

Finding your site URL

Use the List Verified Sites collection first to discover the exact site URLs registered in your account. Copy the siteUrl value from the response, then URL-encode it for use in other collections.

Collections

After connecting, select a collection from the dropdown to query your Search Console data.

Search Analytics

The primary collection for pulling search performance data. Uses a POST request with a JSON body that controls which dimensions, date ranges, filters, and pagination options are applied.

Endpoint: POST /sites/{siteUrl}/searchAnalytics/query

Parameters:

• Site URL (URL-encoded) - Your verified site URL, URL-encoded (see URL Encoding section above).
• Request Body (JSON) - The JSON payload that defines your query.
• Cloud9QL Query - Optional transformations applied after data is returned.

Request Body Format

The request body is a JSON object with the following fields:

Date Resolution

Knowi resolves the final startDate and endDate sent to the API based on the combination of fields you provide:

Examples:

• startDate: 2025-01-01, dateRange: 3m, no endDate -> resolves to 2025-01-01 through 2025-04-01
• dateRange: 3m, no startDate, no endDate -> resolves to 3 months ago through today
• startDate: 2025-01-01, endDate: 2025-03-31, dateRange: 3m -> resolves to 2025-01-01 through 2025-03-31 (range ignored)

Note: If you want dateRange to control the end date, leave endDate empty.

Example: Top queries by page and date

{
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "dimensions": ["query", "page", "date"],
  "rowLimit": 10000,
  "startRow": 0
}

Example: Device breakdown for a specific date range

{
  "startDate": "2025-06-01",
  "endDate": "2025-06-30",
  "dimensions": ["query", "device", "date"],
  "rowLimit": 25000,
  "startRow": 0
}

Example: Country-level performance

{
  "startDate": "2025-01-01",
  "endDate": "2025-03-31",
  "dimensions": ["country", "query"],
  "rowLimit": 10000,
  "startRow": 0
}

Example: Filter to a specific page path

{
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "dimensions": ["query", "date"],
  "rowLimit": 10000,
  "startRow": 0,
  "dimensionFilterGroups": [
    {
      "filters": [
        {
          "dimension": "page",
          "operator": "contains",
          "expression": "/blog/"
        }
      ]
    }
  ]
}

Example: Rolling 3-month window relative to today

Omit both startDate and endDate and use dateRange alone. Knowi calculates the start as 3 months before today and the end as today:

{
  "dateRange": "3m",
  "dimensions": ["query", "page", "date"],
  "rowLimit": 10000,
  "startRow": 0
}

Example: Fixed start date with a 30-day range

Set startDate and dateRange with no endDate. Knowi calculates the end date as 30 days after the start:

{
  "startDate": "2025-01-01",
  "dateRange": "30d",
  "dimensions": ["query", "date"],
  "rowLimit": 10000,
  "startRow": 0
}

Example: Filter to branded queries

{
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "dimensions": ["query", "page", "date"],
  "rowLimit": 10000,
  "startRow": 0,
  "dimensionFilterGroups": [
    {
      "filters": [
        {
          "dimension": "query",
          "operator": "contains",
          "expression": "knowi"
        }
      ]
    }
  ]
}

Filter Operators

The operator field in dimension filters supports:

Response Fields

The API returns a rows array. Each row contains:

Default Cloud9QL:

select expand(rows);

This expands the rows array so each row becomes a separate record.

List Verified Sites

Returns all sites (properties) that the authenticated user has access to in Search Console. Use this to discover the exact site URLs you need for other collections.

Endpoint: GET /sites

Parameters:

• Cloud9QL Query - Optional transformations.

Response fields: siteUrl, permissionLevel

The permissionLevel values are: siteOwner, siteFullUser, siteRestrictedUser, siteUnverifiedUser.

Default Cloud9QL:

select expand(siteEntry);

Tip: Run this collection first to get your site URLs, then URL-encode the siteUrl values for use in Search Analytics and List Sitemaps.

List Sitemaps

Returns the sitemaps submitted for a given site, along with their status and any errors.

Endpoint: GET /sites/{siteUrl}/sitemaps

Parameters:

• Site URL (URL-encoded) Your verified site URL, URL-encoded.
• Cloud9QL Query - Optional transformations.

Response fields: path, lastSubmitted, isPending, isSitemapsIndex, lastDownloaded, warnings, errors

Default Cloud9QL:

select expand(sitemap);

Custom Endpoint

For advanced users who need to call any Search Console API endpoint not covered by the predefined collections. Specify the API path relative to /webmasters/v3/.

Parameters:

• API Path - The path after /webmasters/v3/. Example: sites/https%3A%2F%2Fwww.example.com/searchAnalytics/query
• Request Body (JSON) - Optional JSON body for POST requests.
• Cloud9QL Query - Optional transformations.

Refer to the Google Search Console API reference for all available endpoints.

Cloud9QL Transformations

After pulling data from Search Console, use Cloud9QL to transform and enrich the results.

Expand the rows array

The Search Analytics response wraps results in a rows array. Expand it first:

select expand(rows);

Extract dimensions from keys

After expanding rows, the dimension values are in a keys array. Extract them by index (matching the order of your dimensions parameter):

select keys[0] as query, keys[1] as page, keys[2] as date,
       clicks, impressions, ctr, position;

Filter to high-performing queries

select * where clicks > 50 and position < 10;

Aggregate clicks by page

select keys[1] as page, sum(clicks) as total_clicks,
       sum(impressions) as total_impressions,
       avg(position) as avg_position
group by keys[1]
order by total_clicks desc;

Identify low-CTR opportunities

Pages ranking well but with low CTR may benefit from title/description improvements:

select * where position < 15 and ctr < 0.02
order by impressions desc;

Pagination for large datasets

The Search Console API returns a maximum of 25,000 rows per request. To pull more data, use startRow for pagination. Create multiple queries incrementing startRow by your rowLimit:

• Query 1: "rowLimit": 25000, "startRow": 0
• Query 2: "rowLimit": 25000, "startRow": 25000
• Query 3: "rowLimit": 25000, "startRow": 50000

Then use Cloud9QL append to combine the results, or schedule each query to write to the same dataset.

Cross-Source Joins

One of Knowi's key strengths is joining Search Console data with other sources without ETL. Examples:

Search Console + Google Analytics 4

Join organic search queries with on-site behavior and conversions:

select * left join [ga4_sessions]
on page = landing_page;

Search Console + Google Ads

Combine organic and paid search data for a unified keyword-level view:

select * left join [google_ads_keywords]
on query = keyword_text;

Search Console + MongoDB

Join search performance with product or content metadata:

select * left join [content_catalog]
on page = content_url;

Search Console + Salesforce

Connect organic traffic patterns to lead and opportunity data:

select * left join [salesforce_leads]
on page = lead_source_url;

See Joining Across Multiple Databases for details.

Scheduling

Once your query is configured, schedule it to run automatically to keep dashboards current:

• Daily - Standard cadence for tracking keyword rankings and click trends.
• Weekly - Summary reporting for SEO reviews and executive dashboards.
• Monthly - Long-term trend analysis and month-over-month comparisons.

Set up alerts to get notified via email, Slack, or webhook when metrics cross thresholds (e.g., average position drops below a target, impressions spike or decline significantly).

For more information, see Defining Data Execution Strategy.

Troubleshooting

Authorization Error

Re-authenticate by clicking "Connect with Google" on the datasource edit page. Ensure the webmasters.readonly scope is granted during the OAuth flow.

No Data Returned

Search Console data has a processing delay of 2-3 days. If you query very recent dates, you may get empty results. Adjust your endDate to at least 3 days before today.

siteUrl Not Found (403 or 404)

Verify that the siteUrl parameter is properly URL-encoded and matches a verified property in your account. Use the List Verified Sites collection to confirm the exact URL. Domain properties require the sc-domain: prefix (e.g., sc-domain%3Aexample.com).

Row Limit Exceeded

The API caps results at 25,000 rows per request. Use startRow for pagination to retrieve additional pages of data. See the Pagination section under Cloud9QL Transformations.

keys Array Indexing

The keys array in the response contains dimension values in the same order as your dimensions parameter. If you requested ["query", "page", "date"], then keys[0] is the query, keys[1] is the page URL, and keys[2] is the date.

Data Freshness

Search Console data is typically available with a 2-3 day delay. Conversion and click data may take longer to finalize. Set your scheduled queries to pull data with an appropriate lag to avoid incomplete results.

Notes

• Knowi uses the Google Search Console API (Webmasters API v3).
• All access is read-only. Knowi does not modify your properties, sitemaps, or any Search Console settings.
• OAuth tokens are automatically refreshed. If your token becomes invalid (e.g., password change, revoked access), reconnect via the datasource settings.
• The Search Console API has a quota of 1,200 queries per minute per project. Knowi manages this automatically, but very high-frequency scheduling may hit limits.
• Search Console data covers Google Search, Discover, and Google News. Use the type parameter in your request body to specify which search type to query.
• For the latest API details, refer to the Google Search Console API documentation.