cotera
Logo

Google Search Console

Authentication Type: OAuth2 Description: Query search performance data, inspect URLs for indexing status, list verified sites, and view sitemap information from Google Search Console.

Authentication

To authenticate with Google Search Console, you need OAuth2 credentials:

  1. Go to the Google Cloud Console and create or select a project
  2. Enable the Search Console API in the API Library
  3. Create OAuth2 credentials (type: Web application) in Credentials

You'll need to provide:

  • clientId string: Your OAuth2 client ID from Google Cloud Console
  • clientSecret string: Your OAuth2 client secret
  • refreshToken string: An OAuth2 refresh token with Search Console access scope

Search Analytics

Query Search Analytics

Query search performance data from Google Search Console with clicks, impressions, CTR, and average position. Supports grouping by dimensions and filtering by date range, search type, and more.

Operation Type: Query (Read)

Parameters:

  • siteUrl string (required): Search Console property URL (e.g., "https://example.com/" or "sc-domain:example.com")
  • startDate string (required): Start date in YYYY-MM-DD format (Pacific Time)
  • endDate string (required): End date in YYYY-MM-DD format (Pacific Time)
  • dimensions array of strings (nullable): Group results by dimensions. Options: "query", "page", "country", "device", "date", "searchAppearance"
  • type string (nullable): Filter by search type. Options: "web", "image", "video", "news", "discover", "googleNews"
  • dimensionFilterGroups array of objects (nullable): Advanced filtering on dimensions
    • groupType string: Filter group type
    • filters array of objects: Individual filters
      • dimension string: Dimension to filter
      • operator string: Filter operator (e.g., "contains", "equals", "notContains")
      • expression string: Filter value
  • aggregationType string (nullable): How to aggregate results. Options: "auto", "byProperty", "byPage"
  • rowLimit number (nullable): Maximum rows to return (default 1000, max 25000)
  • startRow number (nullable): Pagination offset (0-based)
  • dataState string (nullable): Data freshness. Options: "final", "all" (includes fresh/partial data)

Returns:

  • rows array of objects: Search analytics data rows
    • keys array of strings: Dimension values for this row (in same order as requested dimensions)
    • clicks number: Number of clicks
    • impressions number: Number of impressions
    • ctr number: Click-through rate (0 to 1)
    • position number: Average position in search results
  • responseAggregationType string: Aggregation type used

Example Usage:

{
  "siteUrl": "https://example.com/",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "dimensions": ["query", "page"],
  "type": "web",
  "rowLimit": 100,
  "dataState": "final"
}

Sites

List Sites

List all Search Console properties accessible to the authenticated user, including their permission levels.

Operation Type: Query (Read)

Parameters:

None required.

Returns:

  • sites array of objects: List of accessible Search Console properties
    • siteUrl string: The URL of the property
    • permissionLevel string: Your permission level (e.g., "siteOwner", "siteFullUser", "siteRestrictedUser")

Example Usage:

{}

Sitemaps

List Sitemaps

List all sitemaps submitted for a Search Console property, including submitted vs. indexed URL counts and error/warning information.

Operation Type: Query (Read)

Parameters:

  • siteUrl string (required): Search Console property URL

Returns:

  • sitemaps array of objects: List of sitemaps
    • path string: Sitemap URL
    • lastSubmitted string (nullable): Last submission timestamp
    • lastDownloaded string (nullable): Last download timestamp by Google
    • isPending boolean (nullable): Whether the sitemap is pending processing
    • isSitemapsIndex boolean (nullable): Whether this is a sitemap index file
    • type string (nullable): Sitemap type
    • errors number (nullable): Number of errors
    • warnings number (nullable): Number of warnings
    • contents array of objects (nullable): Content type breakdown
      • type string: Content type
      • submitted number: URLs submitted
      • indexed number: URLs indexed

Example Usage:

{
  "siteUrl": "https://example.com/"
}

URL Inspection

Inspect URL

Check how Google sees a specific URL, including indexing status, crawl information, canonical selection, robots.txt status, mobile usability, and rich results eligibility.

Operation Type: Query (Read)

Parameters:

  • inspectionUrl string (required): Fully-qualified URL to inspect (must belong to the specified property)
  • siteUrl string (required): Search Console property URL
  • languageCode string (nullable): BCP-47 language code for localized issue messages (e.g., "en-US")

Returns:

  • inspectionResultLink string (nullable): Link to the full inspection result in Search Console
  • indexStatus object (nullable): Indexing status information
    • verdict string: Indexing verdict (e.g., "PASS", "FAIL", "NEUTRAL")
    • coverageState string (nullable): Coverage state description
    • robotsTxtState string (nullable): robots.txt status
    • indexingState string (nullable): Current indexing state
    • lastCrawlTime string (nullable): Last crawl timestamp
    • pageFetchState string (nullable): Page fetch status
    • googleCanonical string (nullable): Google-selected canonical URL
    • userCanonical string (nullable): User-declared canonical URL
    • crawledAs string (nullable): Crawler used (desktop or mobile)
    • referringUrls array of strings (nullable): URLs that refer to this page
    • sitemap array of strings (nullable): Sitemaps containing this URL
  • mobileUsability object (nullable): Mobile usability assessment
    • verdict string: Mobile usability verdict
    • issues array of objects (nullable): Mobile usability issues found
  • richResults object (nullable): Rich results eligibility
    • verdict string: Rich results verdict
    • detectedItems array of objects (nullable): Detected structured data items

Example Usage:

{
  "inspectionUrl": "https://example.com/blog/my-post",
  "siteUrl": "https://example.com/",
  "languageCode": "en-US"
}

Common Use Cases

SEO Performance Monitoring:

  • Track search clicks, impressions, CTR, and average position over time
  • Identify top-performing queries and pages driving organic traffic
  • Compare performance across different date ranges to spot trends

Technical SEO Auditing:

  • Inspect URLs to check indexing status, crawl errors, and canonical issues
  • Monitor sitemap health including error counts and indexed vs. submitted URLs
  • Verify robots.txt compliance and mobile usability for key pages

Content Optimization:

  • Discover high-impression, low-CTR queries that need better meta descriptions or titles
  • Find pages ranking on page 2 that could be optimized to reach page 1
  • Analyze search appearance features like rich results eligibility

Multi-Site Management:

  • List all accessible Search Console properties for portfolio management
  • Monitor search performance across multiple sites from a single integration
  • Track sitemap submissions and indexing progress across properties