# Google Search Console

> Query search performance data, inspect URLs for indexing status, list verified sites, and view sitemap information from Google Search Console.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://console.cloud.google.com/) and create or select a project
2. Enable the **Search Console API** in the [API Library](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)
3. Create OAuth2 credentials (type: **Web application**) in [Credentials](https://console.cloud.google.com/apis/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:**

```json
{
  "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:**

```json
{}
```

***

## 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:**

```json
{
  "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:**

```json
{
  "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