Google Search Console for Python

https://joshcarty.github.io/google-searchconsole
Admin
A Python library that simplifies working with the Google Search Console API, providing easy...
Tokens:28,224
Snippets:257
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Quickstart: authenticate, query, and export to DataFrame

Source: https://joshcarty.github.io/google-searchconsole

Quickstart example: authenticate with OAuth2, select a web property, run a query for the last 7 days, and export the result to a pandas DataFrame.

```python
import searchconsole

# Authenticate with your browser:
account = searchconsole.authenticate(client_config='client_secrets.json')

# Select your site
webproperty = account['https://www.example.com/']

# Query and analyze
report = webproperty.query.range('today', days=-7).dimension('query').get()

# Export to pandas for analysis
df = report.to_dataframe()
print(df.head())

```

--------------------------------

### Set up development environment with uv or pip

Source: https://joshcarty.github.io/google-searchconsole/contributing

Install dependencies using uv or create a virtual environment with pip and install the package in development mode.

```bash
# Install dependencies
uv sync

# Or using pip
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

```

--------------------------------

### Example filter method with docstring

Source: https://joshcarty.github.io/google-searchconsole/contributing

Example of a filter method following PEP 8 style, showing docstring with Args, Returns, and Example sections.

```python
def filter(dimension=expression, operator="equals", group_type="and"):
    """
    Filter results by dimension values.

    Args:
        dimension: Dimension to filter on (query, page, date, country, device, searchAppearance)
        expression: Value to filter by
        operator: Filter operator (equals, contains, notContains, etc.)
        group_type: How to combine multiple filters (default: "and")

    Returns:
        New Query object with filter applied

    Example:
        >>> query.filter('country', 'usa', 'equals')
        >>> query.filter('query', 'python', 'contains')
    """
    # Implementation
    pass

```

--------------------------------

### Install the library from GitHub

Source: https://joshcarty.github.io/google-searchconsole/getting-started

Use this pip command to install the Google Search Console Python library directly from its GitHub repository.

```bash
pip install git+https://github.com/joshcarty/google-searchconsole

```

--------------------------------

### Complete example: top 10 queries with searchconsole

Source: https://joshcarty.github.io/google-searchconsole/getting-started

Full working example: authenticate with saved credentials, select a property, query top 10 queries from the last 7 days, and display results with formatting.

```python
import searchconsole

# Authenticate
account = searchconsole.authenticate(client_config='client_secrets.json', credentials='credentials.json')

# Select property
webproperty = account['https://www.example.com/']

# Query top queries from the last 7 days
report = (
    webproperty.query
    .range('today', days=-7)
    .dimension('query')
    .limit(10)
    .get()
)

# Display results
print(f"Top 10 queries from the last 7 days:\n")
for i, row in enumerate(report, 1):
    print(f"{i}. {row.query}")
    print(f"   Clicks: {row.clicks}, Impressions: {row.impressions}, "
          f"CTR: {row.ctr:.2%}, Avg Position: {row.position:.1f}\n")

```

--------------------------------

### daterange() usage example

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows how to use daterange() to get the last 7 days. The example prints the start and end dates as ISO strings.

```python
from searchconsole.utils import daterange

# Last 7 days
start, end = daterange('today', days=-7)
print(start, end)  # ('2024-11-08', '2024-11-15')
```

--------------------------------

### Run a Search Analytics query

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Example of using the query builder to get a report with the 'query' dimension for the last 7 days.

```python
report = webproperty.query.range('today', days=-7).dimension('query').get()
```

--------------------------------

### Expected output for complete example

Source: https://joshcarty.github.io/google-searchconsole/getting-started

Shows the expected output format of the complete example, including the header and sample rows with clicks, impressions, CTR, and average position.

```text
Top 10 queries from the last 7 days:

1. python tutorial
   Clicks: 150, Impressions: 2500, CTR: 6.00%, Avg Position: 5.2

2. learn python
   Clicks: 120, Impressions: 1800, CTR: 6.67%, Avg Position: 4.8

3. python for beginners
   Clicks: 95, Impressions: 1200, CTR: 7.92%, Avg Position: 3.5
...

```

--------------------------------

### Console Flow Output and Redirect URL Example

Source: https://joshcarty.github.io/google-searchconsole/authentication

Example console output showing the authorization URL prompt and the redirect URL to copy and paste back into the console.

```text
Please visit this URL to authorize this application:
https://accounts.google.com/o/oauth2/auth?client_id=...

Enter the authorization code: 

```

```text
http://localhost:8080/?code=4/0AX4XfWh...&scope=https://www.googleapis.com/auth/webmasters.readonly

```

--------------------------------

### Docstring example for range method

Source: https://joshcarty.github.io/google-searchconsole/contributing

Example docstring for a public API method. Includes Args, Returns, Examples, and Note sections. The Note mentions the API's 16-month data retention limit.

```python
def range(self, start=None, stop=None, months=0, days=0):
    """
    Define the date range for the query.

    Args:
        start: Start date (str, datetime.date, or None). Supports "today", "yesterday",
               date strings like "2024-01-01", or datetime.date objects. Default: yesterday.
        stop: End date. Same formats as start. Default: same as start.
        months: Month offset from start date. Negative for past, positive for future.
        days: Day offset from start date. Negative for past, positive for future.

    Returns:
        New Query object with date range set.

    Examples:
        >>> query.range('today', days=-7)  # Last 7 days
        >>> query.range('2024-01-01', '2024-01-31')  # Specific range
        >>> query.range('today', months=-3)  # Last 3 months

    Note:
        API has a 16-month data retention limit.
    """

```

--------------------------------

### limit() usage examples

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Examples of using limit() with various limits and start positions, including auto-pagination for large limits. The API returns a maximum of 25,000 rows per request.

```python
# First 10 rows
query.limit(10)

# First 100 rows
query.limit(100)

# Rows 100-199 (pagination)
query.limit(100, 100)

# Rows 200-299
query.limit(100, 200)

# Large limit (auto-paginated)
query.limit(50000)  # Will make multiple API calls

```

--------------------------------

### OAuth2 and service account authentication examples

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Provides multiple usage examples for authenticate(): first-time OAuth2 with client_config, saved credentials, console flow for remote servers, service account, and dictionary-based configuration. Note that service_account cannot be used with client_config or credentials.

```python
# First-time OAuth2 authentication
account = searchconsole.authenticate(client_config='client_secrets.json')

# With saved credentials
account = searchconsole.authenticate(
    client_config='client_secrets.json',
    credentials='credentials.json'
)

# Console flow
account = searchconsole.authenticate(
    client_config='client_secrets.json',
    flow='console'
)

# Service account
account = searchconsole.authenticate(
    service_account='service_account.json'
)

# Using dictionaries
account = searchconsole.authenticate(
    client_config={'installed': {...}},
    credentials={'token': '...', ...}
)
```

--------------------------------

### Preview documentation locally with zensical serve

Source: https://joshcarty.github.io/google-searchconsole/contributing

Run this command in the project root to start a local preview server. Visit http://localhost:8000 to view the documentation.

```bash
zensical serve

```

--------------------------------

### Query.dimension() usage examples

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Examples of specifying single, multiple, and all dimensions for a query.

```python
# Single dimension
query.dimension('query')
query.dimension('page')

# Multiple dimensions
query.dimension('query', 'page')
query.dimension('query', 'date')
query.dimension('page', 'country', 'device')

# All dimensions
query.dimension('query', 'page', 'date', 'country', 'device', 'searchAppearance')
```

--------------------------------

### Complete example: authenticate, query, analyze, and export

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Puts together the full workflow: authenticate with client secrets, select a property, build a complex query with filters and dimensions, analyze results, and export to CSV and JSON.

```python
import searchconsole

# 1. Authenticate
account = searchconsole.authenticate(
    client_config='client_secrets.json',
    credentials='credentials.json'
)

# 2. Select property
webproperty = account['https://www.example.com/']
print(f"Permission: {webproperty.permission}")

# 3. Build complex query
report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('query', 'page', 'country')
    .filter('query', 'python', 'contains')
    .filter('page', '/blog/', 'contains')
    .filter('country', 'usa', 'equals')
    .search_type('web')
    .data_state('all')
    .limit(1000)
    .get()
)

# 4. Analyze results
print(f"Total rows: {len(report)}")
print(f"Dimensions: {report.dimensions}")
print(f"Metrics: {report.metrics}")

# 5. Access data
for row in report[:10]:
    print(f"{row.query} on {row.page}")
    print(f"  Country: {row.country}")
    print(f"  Clicks: {row.clicks}, Impressions: {row.impressions}")
    print(f"  CTR: {row.ctr:.2%}, Position: {row.position:.1f}\n")

# 6. Export
df = report.to_dataframe()
df.to_csv('search_console_data.csv', index=False)

data = report.to_dict()
import json
with open('search_console_data.json', 'w') as f:
    json.dump(data, f, indent=2)
```

--------------------------------

### Query.range() usage examples

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Multiple examples of using range() with different date specifications, including special strings, datetime objects, and offsets.

```python
# Last 7 days
query.range('today', days=-7)

# Last 30 days
query.range('today', days=-30)

# Specific date range
query.range('2024-01-01', '2024-01-31')

# Single day
query.range('yesterday')
query.range('2024-01-15')

# Last 3 months
query.range('today', months=-3)

# Using datetime objects
import datetime
query.range(
    start=datetime.date(2024, 1, 1),
    stop=datetime.date(2024, 1, 31)
)

# 28 days forward from date
query.range('2024-01-01', days=28)
```

--------------------------------

### Top Pages by Traffic - Get top 20 pages and sort by clicks

Source: https://joshcarty.github.io/google-searchconsole/examples

Retrieves the top 20 pages by traffic for the last 30 days, converts the report to a DataFrame, and prints the top 10 pages by clicks. Uses the same webproperty object from the previous example.

```python
report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('page')
    .limit(20)
    .get()
)

# Convert to DataFrame for easier analysis
df = report.to_dataframe()

# Sort by clicks
top_pages = df.nlargest(10, 'clicks')

print("Top 10 Pages by Clicks\n")
for idx, row in top_pages.iterrows():
    print(f"{row['page']}")
    print(f"  {row['clicks']:,} clicks, {row['impressions']:,} impressions\n")
```

--------------------------------

### data_state() usage examples

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Examples of using data_state() to include fresh data or only final data. Fresh data may be replaced with final data after a few days.

```python
# Include fresh data
query.data_state('all')

# Only final data (default)
query.data_state('final')

```

--------------------------------

### Unit test example for new feature

Source: https://joshcarty.github.io/google-searchconsole/contributing

Example test class using unittest to test a new feature and an edge case.

```python
import unittest
from searchconsole import Query

class TestNewFeature(unittest.TestCase):
    def test_feature_works(self):
        """Test that the new feature works as expected."""
        # Setup
        query = Query(...)

        # Execute
        result = query.new_feature()

        # Assert
        self.assertEqual(result.something, expected_value)

    def test_feature_edge_case(self):
        """Test edge case handling."""
        query = Query(...)

        with self.assertRaises(ValueError):
            query.new_feature(invalid_input)

```

--------------------------------

### Commit changes with descriptive message

Source: https://joshcarty.github.io/google-searchconsole/contributing

Example of staging and committing changes with a multi-line commit message. Use this when submitting changes.

```bash
git add .
git commit -m "Add support for bulk query execution

- Implement BulkQuery class
- Add tests for concurrent execution
- Update documentation with examples"

```

--------------------------------

### Execute query with get()

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Executes the query and returns all results. Automatically handles pagination if results exceed the per-request limit or specified limit.

```python
query.get()
```

```python
# Build and execute
report = (
    webproperty.query
    .range('today', days=-7)
    .dimension('query')
    .get()
)

# With multiple operations
report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('query', 'page')
    .filter('query', 'python', 'contains')
    .limit(1000)
    .get()
)
```

--------------------------------

### Documentation source tree structure

Source: https://joshcarty.github.io/google-searchconsole/contributing

Shows the layout of the docs/ directory with markdown files for each guide. Use this as a reference when adding or editing documentation.

```text
docs/
├── index.md           # Home page
├── getting-started.md # Getting started guide
├── authentication.md  # Authentication guide
├── api-reference.md   # API reference
├── examples.md        # Examples and cookbook
└── contributing.md    # This file

```

--------------------------------

### get()

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Executes the query and returns all results, automatically handling pagination if results exceed the per-request limit or specified limit.

```APIDOC
## get()

### Description
Execute the query and return all results. Automatically handles pagination if results exceed the per-request limit or your specified limit.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Request Example
```python
query.get()
```

### Response
#### Success Response
- **Returns:** `Report` object with all matching rows

#### Response Example
```python
# Build and execute
report = (
    webproperty.query
    .range('today', days=-7)
    .dimension('query')
    .get()
)

# With multiple operations
report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('query', 'page')
    .filter('query', 'python', 'contains')
    .limit(1000)
    .get()
)
```

### Notes
- Automatic Pagination: `get()` automatically handles pagination if results exceed the per-request limit or your specified limit.
```

--------------------------------

### Save and Reuse OAuth2 Credentials with serialize_credentials

Source: https://joshcarty.github.io/google-searchconsole/authentication

Shows the one-time setup: authenticate interactively, save credentials with serialize_credentials, then reuse them in later sessions to skip the browser flow. The credentials.json file contains access tokens and should be kept secure and added to .gitignore.

```python
# First authentication - opens browser
account = searchconsole.authenticate(client_config='client_secrets.json')

# Save credentials for future use
account.serialize_credentials('credentials.json')

```

```python
# Load saved credentials - no browser needed
account = searchconsole.authenticate(
    client_config='client_secrets.json',
    credentials='credentials.json',
)

```

--------------------------------

### limit() method signatures

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Signatures for the limit() method, which limits the number of rows returned. Supports optional start parameter for pagination.

```python
query.limit(limit)
query.limit(limit, start)

```

--------------------------------

### Access report.metrics attribute

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows the metrics attribute as a list of strings. The example prints the metrics from a report.

```python
report.metrics  # List[str]
```

```python
print(report.metrics)  # ['clicks', 'impressions', 'ctr', 'position']
```

--------------------------------

### Get Credentials from Environment Variable

Source: https://joshcarty.github.io/google-searchconsole/authentication

Retrieves Google credentials from an environment variable, a recommended practice for production to avoid committing secrets.

```python
credentials = os.environ.get('GOOGLE_CREDENTIALS')

```

--------------------------------

### execute()

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Executes a single request (one page of results). Usually you want get() instead, which fetches all pages automatically.

```APIDOC
## execute()

### Description
Execute a single request (one page of results). Usually you want `get()` instead, which fetches all pages automatically.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Request Example
```python
query.execute()
```

### Response
#### Success Response
- **Returns:** `Report` object with single page of results

#### Response Example
None

### Notes
- Usually you want `get()` instead, which fetches all pages automatically.
```

--------------------------------

### OAuth Error: Address already in use

Source: https://joshcarty.github.io/google-searchconsole/authentication

Error message shown when the OAuth flow cannot start because the port is already in use. Use the console flow instead.

```text
OSError: [Errno 98] Address already in use

```

--------------------------------

### Access report.first property

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows the first property returning the first row or None. The example checks if the report is not empty and prints the top query.

```python
report.first  # Row or None
```

```python
if report.first:
    print(f"Top query: {report.first.query}")
```

--------------------------------

### Execute single request with execute()

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Executes a single request and returns one page of results. Usually you want get() instead, which fetches all pages automatically.

```python
query.execute()
```

--------------------------------

### Fluent Query API: chained query with filters and limit

Source: https://joshcarty.github.io/google-searchconsole

Build a complex query using method chaining: range, dimensions, filters, limit, and get.

```python
report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('query', 'page')
    .filter('query', 'python', 'contains')
    .filter('page', '/blog/', 'contains')
    .limit(1000)
    .get()
)

```

--------------------------------

### Access Row named tuple attributes and dictionary-style access

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows how to access row data via attribute and dictionary-style access. The example retrieves the first row and prints query, clicks, and impressions using both methods.

```python
row = report.rows[0]

# Attribute access
print(row.query)
print(row.clicks)
print(row.impressions)

# Dictionary access
print(row['query'])
print(row['clicks'])
```

--------------------------------

### Convert report to pandas DataFrame with to_dataframe()

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows the to_dataframe() method that returns a pandas DataFrame. Requires the pandas library. The example prints head, info, describe, performs pandas operations, and saves to CSV and Excel.

```python
report.to_dataframe()
```

```python
df = report.to_dataframe()

print(df.head())
print(df.info())
print(df.describe())

# Pandas operations
print(df['clicks'].sum())
print(df.groupby('country')['clicks'].sum())

# Save to CSV
df.to_csv('report.csv', index=False)

# Save to Excel
df.to_excel('report.xlsx', index=False)
```

--------------------------------

### Top Performing Queries - Get top 10 queries for last 30 days

Source: https://joshcarty.github.io/google-searchconsole/examples

Authenticates with the Search Console API and retrieves the top 10 queries for the last 30 days. Requires client_secrets.json and credentials.json files. Prints a formatted report with clicks, impressions, CTR, and average position.

```python
import searchconsole

account = searchconsole.authenticate(
    client_config='client_secrets.json',
    credentials='credentials.json'
)

webproperty = account['https://www.example.com/']

# Query top queries
report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('query')
    .limit(10)
    .get()
)

print("Top 10 Queries (Last 30 Days)\n" + "="*50)
for i, row in enumerate(report, 1):
    print(f"{i:2d}. {row.query}")
    print(f"    Clicks: {row.clicks:>6,} | Impressions: {row.impressions:>8,}")
    print(f"    CTR: {row.ctr:>6.2%} | Avg Position: {row.position:>5.1f}\n")
```

--------------------------------

### Clone the repository and navigate into it

Source: https://joshcarty.github.io/google-searchconsole/contributing

Commands to fork and clone the repository locally, then change into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/google-searchconsole.git
cd google-searchconsole

```

--------------------------------

### Get report length with len()

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows how to get the number of rows in the report using len().

```python
num_rows = len(report)
print(f"Report has {num_rows} rows")
```

--------------------------------

### Authenticate with searchconsole (first-time interactive)

Source: https://joshcarty.github.io/google-searchconsole/getting-started

Opens a browser for login and permission grant, then returns an authenticated Account object. Requires a client_secrets.json file.

```python
import searchconsole

# First-time authentication (interactive)
account = searchconsole.authenticate(client_config='client_secrets.json')

```

--------------------------------

### search_type() usage examples

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Examples of using search_type() with different search types. Note that 'discover' and 'googleNews' do not return position data.

```python
# Image search
query.search_type('image')

# Video search
query.search_type('video')

# Google Discover (no position data)
query.search_type('discover')

# News search
query.search_type('news')

```

--------------------------------

### List web properties with searchconsole

Source: https://joshcarty.github.io/google-searchconsole/getting-started

Iterates over account.webproperties and prints each property's URL and permission level.

```python
# View all properties
for property in account.webproperties:
    print(f"URL: {property.url}, Permission: {property.permission}")

```

--------------------------------

### Month-over-Month Comparison using webproperty.query

Source: https://joshcarty.github.io/google-searchconsole/examples

Compares current month to previous month. Fetches data for the current month and the previous month, converts to DataFrames, and prints a summary with click and impression totals and the percentage change in clicks.

```python
import datetime

# Current month data
this_month_start = datetime.date.today().replace(day=1)
this_month_report = (
    webproperty.query
    .range(this_month_start, 'today')
    .dimension('query')
    .get()
)

# Previous month data
last_month_end = this_month_start - datetime.timedelta(days=1)
last_month_start = last_month_end.replace(day=1)
last_month_report = (
    webproperty.query
    .range(last_month_start, last_month_end)
    .dimension('query')
    .get()
)

# Convert to DataFrames
this_month_df = this_month_report.to_dataframe()
last_month_df = last_month_report.to_dataframe()

# Compare totals
this_month_clicks = this_month_df['clicks'].sum()
last_month_clicks = last_month_df['clicks'].sum()
change = ((this_month_clicks - last_month_clicks) / last_month_clicks * 100)

print(f"Month-over-Month Performance\n{'='*50}")
print(f"\nThis Month:")
print(f"  Clicks: {this_month_clicks:,}")
print(f"  Impressions: {this_month_df['impressions'].sum():,}")

print(f"\nLast Month:")
print(f"  Clicks: {last_month_clicks:,}")
print(f"  Impressions: {last_month_df['impressions'].sum():,}")

print(f"\nChange: {change:+.1f}%")
```

--------------------------------

### Year-over-Year Comparison using webproperty.query

Source: https://joshcarty.github.io/google-searchconsole/examples

Compares the last 30 days to the same period last year. Fetches data for the current 30-day period and the equivalent period from the previous year, converts to DataFrames, and prints a comparison of clicks, impressions, CTR, and position with percentage changes.

```python
import datetime

# This year (last 30 days)
this_year_report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('date')
    .get()
)

# Last year (same 30-day period)
days_ago_365 = datetime.date.today() - datetime.timedelta(days=365)
days_ago_395 = days_ago_365 - datetime.timedelta(days=30)

last_year_report = (
    webproperty.query
    .range(days_ago_395, days_ago_365)
    .dimension('date')
    .get()
)

# Compare
this_year_df = this_year_report.to_dataframe()
last_year_df = last_year_report.to_dataframe()

metrics = {
    'Clicks': ('clicks', this_year_df['clicks'].sum(), last_year_df['clicks'].sum()),
    'Impressions': ('impressions', this_year_df['impressions'].sum(), last_year_df['impressions'].sum()),
    'CTR': ('ctr', this_year_df['ctr'].mean(), last_year_df['ctr'].mean()),
    'Position': ('position', this_year_df['position'].mean(), last_year_df['position'].mean()),
}

print("Year-over-Year Comparison (Last 30 Days)\n")
for metric_name, (col, this_year, last_year) in metrics.items():
    change = ((this_year - last_year) / last_year * 100) if last_year > 0 else 0
    print(f"{metric_name}:")
    print(f"  This Year: {this_year:,.2f}")
    print(f"  Last Year: {last_year:,.2f}")
    print(f"  Change: {change:+.1f}%\n")
```

--------------------------------

### Authenticate with Configuration Dictionaries

Source: https://joshcarty.github.io/google-searchconsole/authentication

Passes client configuration and credentials as dictionaries instead of file paths, useful when storing them in environment variables or secret management systems.

```python
client_config = {
    "installed": {
        "client_id": "your_client_id.apps.googleusercontent.com",
        "client_secret": "your_client_secret",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "redirect_uris": ["http://localhost"]
    }
}

credentials = {
    "token": "ya29.a0AfH6SMBx...",
    "refresh_token": "1//0gZ9K8W...",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_id": "your_client_id.apps.googleusercontent.com",
    "client_secret": "your_client_secret",
    "scopes": ["https://www.googleapis.com/auth/webmasters.readonly"]
}

account = searchconsole.authenticate(client_config=client_config, credentials=credentials)

```

--------------------------------

### filter() usage examples

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Examples of using filter() with various operators and dimensions, including chaining multiple filters. Note that regex patterns use RE2 syntax.

```python
# Contains filter
query.filter('query', 'python', 'contains')

# Page filter
query.filter('page', '/blog/', 'contains')
query.filter('page', 'https://www.example.com/about/', 'equals')

# Country filter
query.filter('country', 'usa', 'equals')

# Device filter
query.filter('device', 'mobile', 'equals')

# Regex filters (RE2 syntax)
query.filter('page', r'/blog/\d{4}/\d{2}/', 'includingRegex')
query.filter('query', r'^(buy|purchase|order)', 'includingRegex')

# Exclude filters
query.filter('page', '/admin/', 'notContains')
query.filter('query', 'test', 'notContains')

# Multiple filters (chain them)
(
    query
    .filter('query', 'python', 'contains')
    .filter('page', '/blog/', 'contains')
    .filter('country', 'usa', 'equals')
    .filter('device', 'mobile', 'equals')
)

```

--------------------------------

### Content Gap Analysis with searchconsole

Source: https://joshcarty.github.io/google-searchconsole/examples

Queries queries over the last 30 days, filters for positions <= 10 and impressions >= 50, then sorts by CTR ascending to find the top 20 opportunities. Prints each query, position, CTR, clicks, impressions, and a suggestion for optimization.

```python
# Get queries with position in top 10 but low CTR
report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('query')
    .get()
)

df = report.to_dataframe()

# Filter for top 10 positions with at least 50 impressions
top_10 = df[(df['position'] <= 10) & (df['impressions'] >= 50)].copy()

# Sort by CTR to find opportunities
opportunities = top_10.nsmallest(20, 'ctr')

print("Ranking Opportunities (Top 10 Position, Low CTR)\n")
for idx, row in opportunities.iterrows():
    print(f"Query: {row['query']}")
    print(f"  Position: {row['position']:.1f} | CTR: {row['ctr']:.2%}")
    print(f"  Clicks: {row['clicks']} | Impressions: {row['impressions']}")
    print(f"  💡 Consider: Optimizing for featured snippets or improving title\n")
```

--------------------------------

### Run tests with uv, pip, tox, or specific test file

Source: https://joshcarty.github.io/google-searchconsole/contributing

Commands to run the test suite using uv, pip, tox (multiple Python versions), or a specific test file.

```bash
# Using uv
uv run python -m unittest tests

# Using pip
python -m unittest tests

# Run with tox (tests multiple Python versions)
tox

# Run specific test file
python -m unittest tests.TestQuery

```

--------------------------------

### Access WebProperty query builder

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows how to access the Query builder for the property. The comment indicates the type is Query.

```python
webproperty.query  # Query
```

--------------------------------

### Select web property by URL or index

Source: https://joshcarty.github.io/google-searchconsole/getting-started

Shows two ways to select a webproperty: by URL string or by index (first property).

```python
# By URL
webproperty = account['https://www.example.com/']

# Or by index
webproperty = account[0]  # First property

```

--------------------------------

### Access report.columns attribute

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows the columns attribute as a list of strings combining dimensions and metrics. The example prints the columns.

```python
report.columns  # List[str]
```

```python
print(report.columns)  # ['query', 'page', 'clicks', 'impressions', 'ctr', 'position']
```

--------------------------------

### Find Underperforming Pages with searchconsole

Source: https://joshcarty.github.io/google-searchconsole/examples

Queries all pages over the last 30 days, filters for pages with at least 100 impressions, and sorts by CTR ascending to find the top 10 underperformers. Prints each page's URL, impressions, clicks, CTR, position, and an opportunity note.

```python
report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('page')
    .get()
)

df = report.to_dataframe()

# Filter for pages with significant impressions
significant_pages = df[df['impressions'] >= 100].copy()

# Sort by CTR (ascending) to find underperformers
underperformers = significant_pages.nsmallest(10, 'ctr')

print("Top 10 Underperforming Pages (High Impressions, Low CTR)\n")
for idx, row in underperformers.iterrows():
    print(f"{row['page']}")
    print(f"  Impressions: {row['impressions']:,} | Clicks: {row['clicks']}")
    print(f"  CTR: {row['ctr']:.2%} | Position: {row['position']:.1f}")
    print(f"  💡 Opportunity: Improve meta description or title tag\n")
```

--------------------------------

### Build and execute a query for last 7 days

Source: https://joshcarty.github.io/google-searchconsole/getting-started

Builds a query for the last 7 days with the 'query' dimension, executes it, and prints each row's query, clicks, impressions, CTR, and position.

```python
# Build the query
query = webproperty.query.range('today', days=-7).dimension('query')

# Execute and get results
report = query.get()

# Print results
print(f"Found {len(report)} rows")

for row in report:
    print(f"Query: {row.query}")
    print(f"  Clicks: {row.clicks}")
    print(f"  Impressions: {row.impressions}")
    print(f"  CTR: {row.ctr:.2%}")
    print(f"  Position: {row.position:.1f}")
    print()

```

--------------------------------

### Iterate over webproperties

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Loops through each web property and prints its URL and permission level.

```python
for prop in account.webproperties:
    print(f"{prop.url} - {prop.permission}")
```

--------------------------------

### Access report.rows attribute

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows the rows attribute as a list of Row named tuples. The example iterates over rows and prints query and clicks.

```python
report.rows  # List[Row]
```

```python
for row in report.rows:
    print(row.query, row.clicks)
```

--------------------------------

### daterange()

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Calculates a date range with offsets. Returns a tuple of two ISO format date strings (start, stop) sorted chronologically.

```APIDOC
## daterange()

### Description
Calculate date range with offsets.

### Method
Function call

### Endpoint
searchconsole.utils.daterange(start=None, stop=None, days=0, months=0)

### Parameters
- **start** (str, datetime.date, or None) - Optional - Start date (default: yesterday)
- **stop** (str, datetime.date, or None) - Optional - End date (default: same as start)
- **days** (int) - Optional - Day offset
- **months** (int) - Optional - Month offset

### Returns
Tuple of two ISO format date strings (start, stop), sorted chronologically

### Example
```python
from searchconsole.utils import daterange

# Last 7 days
start, end = daterange('today', days=-7)
print(start, end)  # ('2024-11-08', '2024-11-15')
```
```

--------------------------------

### Export to Pandas DataFrame and CSV

Source: https://joshcarty.github.io/google-searchconsole/getting-started

Exports the report to a Pandas DataFrame, prints head and total clicks/impressions, and saves to CSV. Requires pandas to be installed.

```python
# Export to pandas (requires pandas to be installed)
df = report.to_dataframe()

print(df.head())
print(f"\nTotal clicks: {df['clicks'].sum()}")
print(f"Total impressions: {df['impressions'].sum()}")

# Save to CSV
df.to_csv('search_data.csv', index=False)

```

--------------------------------

### Project code organization tree

Source: https://joshcarty.github.io/google-searchconsole/contributing

Shows the top-level structure of the project, including the src/ directory, tests, docs, and configuration files. Use this as a reference when adding or modifying files.

```text
google-searchconsole/
├── src/
│   └── searchconsole/
│       ├── __init__.py      # Public API exports
│       ├── auth.py          # Authentication
│       ├── account.py       # Account & WebProperty
│       ├── query.py         # Query & Report
│       └── utils.py         # Utilities
├── tests.py                 # Test suite
├── docs/                    # Documentation
├── pyproject.toml          # Project metadata
└── README.md               # Quick start guide

```

--------------------------------

### Access report.dimensions attribute

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows the dimensions attribute as a list of strings. The example prints the dimensions from a report obtained via query.dimension('query', 'page').get().

```python
report.dimensions  # List[str]
```

```python
report = query.dimension('query', 'page').get()
print(report.dimensions)  # ['query', 'page']
```

--------------------------------

### Interactive OAuth2 Authentication with searchconsole.authenticate

Source: https://joshcarty.github.io/google-searchconsole/authentication

Performs the initial OAuth2 authentication, opening a browser for user login and returning an authenticated Account object.

```python
import searchconsole

# First-time authentication
account = searchconsole.authenticate(client_config='client_secrets.json')

```

--------------------------------

### Build query parameters with build()

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Builds the query parameters without executing. The copy parameter (default True) controls whether a copy of parameters is returned. Returns a dictionary of query parameters.

```python
query.build(copy=True)
```

```python
params = (
    webproperty.query
    .range('today', days=-7)
    .dimension('query')
    .filter('page', '/blog/', 'contains')
    .build()
)

print(params)
# {
#     'startDate': '2024-11-08',
#     'endDate': '2024-11-15',
#     'dimensions': ['query'],
#     'dimensionFilterGroups': [{
#         'filters': [{
#             'dimension': 'page',
#             'expression': '/blog/',
#             'operator': 'contains'
#         }]
#     }],
#     'startRow': 0,
#     'rowLimit': 25000
# }
```

--------------------------------

### Analyze Blog Post Performance with searchconsole

Source: https://joshcarty.github.io/google-searchconsole/examples

Queries all pages containing '/blog/' over the last 30 days, converts to a DataFrame, and prints total posts, clicks, impressions, and the top 10 blog posts by clicks. The title is extracted from the URL by splitting on '/' and replacing hyphens with spaces.

```python
# Get all pages containing '/blog/'
report = (
    webproperty.query
    .range('today', days=-30)
    .dimension('page')
    .filter('page', '/blog/', 'contains')
    .get()
)

df = report.to_dataframe()

print(f"Total blog posts: {len(df)}")
print(f"Total blog clicks: {df['clicks'].sum():,}")
print(f"Total blog impressions: {df['impressions'].sum():,}")

# Top performing blog posts
top_blogs = df.nlargest(10, 'clicks')

print("\nTop 10 Blog Posts:\n")
for idx, row in top_blogs.iterrows():
    # Extract title from URL (customize as needed)
    title = row['page'].split('/')[-2].replace('-', ' ').title()
    print(f"{title}")
    print(f"  URL: {row['page']}")
    print(f"  Clicks: {row['clicks']:,} | Impressions: {row['impressions']:,}")
    print(f"  CTR: {row['ctr']:.2%} | Position: {row['position']:.1f}\n")
```

--------------------------------

### Convert report to list of dictionaries with to_dict()

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Shows the to_dict() method that returns a list of dictionaries. The example prints the first dictionary and saves the data to a JSON file.

```python
report.to_dict()
```

```python
data = report.to_dict()
print(data[0])
# {
#     'query': 'python tutorial',
#     'clicks': 150,
#     'impressions': 2500,
#     'ctr': 0.06,
#     'position': 5.2
# }

# Save to JSON
import json
with open('data.json', 'w') as f:
    json.dump(data, f, indent=2)
```

--------------------------------

### Authenticate with service account using searchconsole.authenticate

Source: https://joshcarty.github.io/google-searchconsole/authentication

Authenticate with a service account JSON key file and run a query. The service account must be granted access to the property in Search Console. Cannot be used with OAuth2 credentials simultaneously and cannot be serialized.

```python
import searchconsole

# Authenticate with service account
account = searchconsole.authenticate(service_account='service_account.json')

# Use as normal
webproperty = account['https://www.example.com/']
report = webproperty.query.range('today', days=-7).get()

```

--------------------------------

### Filter with Common Operators

Source: https://joshcarty.github.io/google-searchconsole/getting-started

Examples of using filter operators like equals, contains, notEquals, notContains, includingRegex, and excludingRegex on dimensions such as country, query, device, page.

```python
.filter('country', 'usa', 'equals')
```

```python
.filter('query', 'python', 'contains')
```

```python
.filter('device', 'tablet', 'notEquals')
```

```python
.filter('page', '/admin/', 'notContains')
```

```python
.filter('page', r'/blog/\d+/', 'includingRegex')
```

```python
.filter('query', r'^test', 'excludingRegex')
```

--------------------------------

### daterange() function signature

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Calculates a date range with optional day and month offsets. Returns a tuple of two ISO format date strings (start, stop) sorted chronologically.

```python
searchconsole.utils.daterange(start=None, stop=None, days=0, months=0)
```

--------------------------------

### Authenticate and serialize credentials

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Authenticates using a client secrets file and then serializes the credentials to a file.

```python
account = searchconsole.authenticate(client_config='client_secrets.json')
account.serialize_credentials('credentials.json')
```

--------------------------------

### Set authentication variables using a .env file

Source: https://joshcarty.github.io/google-searchconsole/contributing

Alternative to environment variables: define the same settings in a .env file for use with python-dotenv.

```bash
# .env
SEARCHCONSOLE_CLIENT_CONFIG={"installed": {...}}
SEARCHCONSOLE_CREDENTIALS={"token": "...", ...}
SEARCHCONSOLE_WEBPROPERTY_URI=https://www.example.com/

```

--------------------------------

### Set authentication environment variables for tests

Source: https://joshcarty.github.io/google-searchconsole/contributing

Export required environment variables for running tests: client config, credentials, and web property URI.

```bash
export SEARCHCONSOLE_CLIENT_CONFIG='{"installed": {...}}'
export SEARCHCONSOLE_CREDENTIALS='{"token": "...", ...}'
export SEARCHCONSOLE_WEBPROPERTY_URI='https://www.example.com/'

```

--------------------------------

### Compare Performance Across Search Types

Source: https://joshcarty.github.io/google-searchconsole/examples

Loops through web, image, video, and news search types, fetches 30-day data for each, and builds a comparison DataFrame. Prints a summary table and a bar chart of clicks and impressions by search type. Handles missing data per type with a try/except.

```python
search_types = ['web', 'image', 'video', 'news']

results = []
for search_type in search_types:
    try:
        report = (
            webproperty.query
            .search_type(search_type)
            .range('today', days=-30)
            .dimension('page')
            .get()
        )

        df = report.to_dataframe()

        results.append({
            'search_type': search_type,
            'clicks': df['clicks'].sum(),
            'impressions': df['impressions'].sum(),
            'ctr': df['ctr'].mean()
        })
    except Exception as e:
        print(f"No data for {search_type}: {e}")

# Display comparison
import pandas as pd
comparison_df = pd.DataFrame(results)

print("Search Type Comparison\n")
print(comparison_df.to_string(index=False))

# Visualize
comparison_df.plot(
    x='search_type',
    y=['clicks', 'impressions'],
    kind='bar',
    title='Clicks and Impressions by Search Type'
)
```

--------------------------------

### Access account.webproperties

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Retrieves the list of web properties accessible to the account. Returns a list of WebProperty objects.

```python
account.webproperties  # List[WebProperty]
```

--------------------------------

### Account.__getitem__(item)

Source: https://joshcarty.github.io/google-searchconsole/api-reference

Access web properties by integer index or URL string.

```APIDOC
## Account.__getitem__(item)

### Description
Access web properties by integer index or URL string.

### Method
Indexing operation

### Endpoint
N/A (SDK indexing)

### Parameters
#### Path Parameters
- **item** (int or str) - Required - Integer index or exact URL string

### Request Example
```python
# By integer index
webproperty = account[0]  # First property
webproperty = account[1]  # Second property

# By URL string
webproperty = account['https://www.example.com/']
webproperty = account['sc-domain:example.com']
```

### Response
#### Success Response
- **Returns** (WebProperty) - WebProperty object

#### Error Response
- **IndexError** - If integer index is out of range
- **KeyError** - If URL not found in accessible properties
```
Tokens:
Raw