### Retrieve Raw DataFrame with show_data()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Use `show_data()` to get the underlying Pandas DataFrame after performing analysis. This is useful for inspection or exporting results.

```python
df = report.show_data()
# page                               query         clicks  impressions   ctr  position
# https://example.com/blog/post-1    seo tips          45         1200  3.75       4.2
# https://example.com/blog/post-2    python seo        12          340  3.53       6.1
```

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

### Get CTR Yield Curve

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Generate a CTR yield curve report. Requires 'query' or 'date' dimensions and 'clicks', 'impressions', or 'position' metrics. Useful for analyzing CTR performance across different positions.

```python
(
    report 
    .ctr_yield_curve()
)
```

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

### Get Response Codes for Pages

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Retrieves HTTP response codes for pages listed in the report. Use with caution on large datasets as it's not optimized for large-scale crawling. Includes an optional wait time parameter to avoid rate limiting.

```python
(report.get_response_codes(
 wait_time=0
))
```

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

### Initialize GSC Wrapper and Select Web Property

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

Authenticate with Google Search Console using a client secret file and select a specific web property for further operations.

```python
import gscwrapper

#authentificate 
account = gscwrapper.generate_auth(
    'config/client_secret_mvp.json', 
    serialize='config/credentials.json'
)

#we choose the website we want 
webproperty = account['https://www.exemple.com/']
#we create the sitemap obkect 
sitemap = (webproperty.sitemap)
```

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

### Authenticate and Initialize GSC Wrapper

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

Authenticates with Google Search Console using a client secret file and serializes credentials. Choose the desired website from the authenticated account.

```python
import gscwrapper

#authentificate 
account = gscwrapper.generate_auth(
    'config/client_secret_mvp.json', 
    serialize='config/credentials.json'
)

#we choose the website we want 
webproperty = account['https://www.exemple.com/']
#we create the sitemap obkect 
inspect = (webproperty.inspect)
```

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

### report.get_response_codes()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Fetches the HTTP status codes for pages listed in the report. This method iterates through unique page URLs and uses the `requests` library to get their response codes, appending a 'response_code' column to the report. Requires the 'page' dimension.

```APIDOC
## report.get_response_codes()

### Description
Fetches HTTP status codes for report pages. Iterates over unique page URLs and returns their HTTP response codes using the `requests` library. Appends a `response_code` column to the report. Requires the `page` dimension.

### Parameters
- **wait_time** (float) - Optional - The time in seconds to wait between requests to avoid overwhelming the server (default is 0.5s).

### Request Example
```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-03-31')
    .dimensions(['page'])
    .get()
)

with_codes = report.get_response_codes(wait_time=0.5)  # 0.5s between requests
```

### Response
#### Success Response
- **with_codes** (Report object) - The report object with an added 'response_code' column.

### Response Example
```
# page                             clicks  response_code
# https://example.com/blog/post-1      45            200
# https://example.com/old-page          2            301
# https://example.com/deleted           0            404
```
```

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

### List Webproperties

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

Lists all webproperties linked to the authenticated account along with their permission levels. Requires prior authentication.

```python
account.list_webproperties()
```

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

### Compare Branded vs. Non-Branded Traffic with brand_vs_no_brand()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Compares branded vs. non-branded traffic over time by splitting clicks and impressions into groups daily. Requires `query` and `date` dimensions. Use `brand_variants` to specify terms considered branded.

```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-01-31')
    .dimensions(['query', 'date'])
    .get()
)

bvnb = report.brand_vs_no_brand(brand_variants=['acme', 'acme corp'])
print(bvnb)
# date        clicks_brand  impressions_brand  clicks_no_brand  impressions_no_brand
# 2024-01-01           0.0                4.0               60                  4917
# 2024-01-02           1.0               10.0               84                  6648
```

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

### List and Select Web Properties with account.list_webproperties()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Retrieves a Pandas DataFrame of all accessible GSC web properties. Supports filtering by permission level or property type, and allows selection by URL or index.

```python
# List all properties
df = account.list_webproperties()
# siteUrl                             permissionLevel
# https://www.example.com/          siteOwner
# sc-domain:example.com               siteOwner

# Filter to owned properties only
owned = account.list_webproperties(permissionLevel='siteOwner')

# Filter to domain properties only
domain_props = account.list_webproperties(is_domain_property=True)

# Select a web property by URL or integer index
webproperty = account['https://www.example.com/']
webproperty = account[0]
```

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

### Querying Search Analytics Data

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

This section covers how to query data from Google Search Console's Search Analytics. You can filter data by date range, dimensions, specific filters, search type, and limit the number of results. The `get()` method is used to retrieve the report.

```APIDOC
## Querying Search Analytics

### Description
Query data from search analytics by filtering based on date range, dimensions, filters, search type, and result limits.

### Method Signature
```python
webproperty.query.range(start: str, stop: str).dimensions(list[str]).filter(dimension: str, value: str, operator: str).search_type(str).limit(int).get()
```

### Parameters
#### `range` (Method)
- **start** (str) - Required - The start date for the query in YYYY-MM-DD format.
- **stop** (str) - Required - The end date for the query in YYYY-MM-DD format.

#### `dimensions` (Method)
- **dimensions** (list[str]) - Required - A list of dimensions to include in the report. At least one dimension must be specified.
  - Supported dimensions: `date`, `hour`, `query`, `page`, `country`, `device`, `searchAppearance`.

#### `filter` (Method)
- **dimension** (str) - Required - The dimension to filter on.
- **value** (str) - Required - The value to filter by.
- **operator** (str) - Required - The operator to use for filtering. Supported operators: `equals`, `notEquals`, `contains`, `notContains`, `includingRegex`, `excludingRegex`.

#### `search_type` (Method)
- **type** (str) - Optional - The type of search to query. Defaults to 'web'. Other options are available.

#### `limit` (Method)
- **limit** (int) - Optional - The maximum number of results to retrieve.

#### `data_state` (Method)
- **state** (str) - Optional - The state of the data to retrieve. Options: `all` (fresh data), `final` (default, finalized data), `hourly_all` (hourly breakdown, including partial data).

### Request Example
```python
report = (
    webproperty
    .query
    .range(start="2023-01-01", stop="2023-02-01")
    .dimensions(["date"])
    .filter("page", "blog", "contains")
    .search_type('discover')
    .limit(50)
    .get()
)
```

### Response
- Returns a `Report` object containing the queried data.
```

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

### Initialize URL Inspection

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

Initializes the Inspect object by authenticating and selecting a web property. This is the first step before adding URLs for inspection.

```APIDOC
## Initialize URL Inspection

### Description
Initializes the Inspect object by authenticating and selecting a web property. This is the first step before adding URLs for inspection.

### Method
```python
import gscwrapper

# Authenticate
account = gscwrapper.generate_auth(
    'config/client_secret_mvp.json',
    serialize='config/credentials.json'
)

# Select the website
webproperty = account['https://www.exemple.com/']

# Create the inspect object
inspect = webproperty.inspect
```
```

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

### Build and Execute Search Analytics Queries

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Uses a fluent builder to construct Google Search Console Search Analytics API requests. Supports chaining methods for date ranges, dimensions, filters, search types, data states, and limits before fetching data.

```python
import gscwrapper

account = gscwrapper.generate_auth(
    'config/client_secret.json',
    credentials='config/credentials.json'
)
webproperty = account['https://www.example.com/']

# Basic query: clicks and impressions by page for January 2024
report = (
    webproperty
    .query
    .range(start='2024-01-01', stop='2024-01-31')
    .dimensions(['page', 'query'])
    .get()
)

# With a dimension filter (page contains "blog") and search type
report = (
    webproperty
    .query
    .range(start='2024-01-01', stop='2024-01-31')
    .dimensions(['page', 'date'])
    .filter('page', 'blog', 'contains')
    .filter('device', 'MOBILE', 'equals')
    .search_type('web')           # web | image | video | discover | googleNews | news
    .data_state('all')            # all | final (default) | hourly_all
    .limit(500)                   # cap results; default fetches all available rows
    .get()
)

# Load a Report from an existing DataFrame (no API call)
import pandas as pd
df = pd.read_csv('gsc_export.csv')
report = gscwrapper.query.from_dataframe(df, webproperty)

print(report)
# <searchconsole.account.Report(
#     webproperty='https://www.example.com/',
#     dimensions='page - date',
#     metrics='clicks - impressions - ctr - position',
#     from_date='2024-01-01',
#     to_date='2024-01-31'
```

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

### Understand Weekly Seasonality with seasonality_per_day()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Quickly understand weekly seasonality in your data. This method returns a table showing daily 'clicks' and 'impressions' aggregated by day of the week.

```python
(report.seasonality_per_day())
```

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

### Compare Content Performance with winners_losers()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Use this method to quickly identify content generating more or fewer clicks between two distinct periods. It requires 'page' or 'date' dimensions and 'clicks' metric.

```python
(report.winners_losers(period_from=['2023-01-01', '2023-01-15'], period_to=['2023-01-16', '2023-01-31']))
```

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

### account.list_webproperties()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Returns a Pandas DataFrame of all web properties accessible to the authenticated account, with optional filtering by permission level or domain-property type.

```APIDOC
## account.list_webproperties()

### Description
Returns a Pandas DataFrame of all web properties accessible to the authenticated account, with optional filtering by permission level or domain-property type.

### Method
```python
df = account.list_webproperties(
    permissionLevel: str = None,
    is_domain_property: bool = None
)
```

### Parameters
#### Query Parameters
- **permissionLevel** (str) - Optional - Filters properties by permission level (e.g., 'siteOwner').
- **is_domain_property** (bool) - Optional - Filters properties to include only domain properties.

### Response Example
```
# List all properties
df = account.list_webproperties()
# siteUrl                             permissionLevel
# https://www.example.com/        siteOwner
# sc-domain:example.com           siteOwner

# Filter to owned properties only
owned = account.list_webproperties(permissionLevel='siteOwner')

# Filter to domain properties only
domain_props = account.list_webproperties(is_domain_property=True)
```

### Usage
```python
# Select a web property by URL or integer index
webproperty = account['https://www.example.com/']
webproperty = account[0]
```
```

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

### List Sitemaps in Google Search Console

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

Retrieve a list of all sitemaps registered in Google Search Console for the selected web property. The output is a DataFrame.

```python
(
    sitemap
    .list_sitemaps()
)
```

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

### gscwrapper.generate_auth()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Authenticates with the Google Search Console API using OAuth 2.0 or a service account key file and returns an Account object. Credentials can be serialized to disk to skip the browser consent flow on subsequent runs.

```APIDOC
## gscwrapper.generate_auth()

### Description
Authenticates with the Google Search Console API using OAuth 2.0 or a service account key file and returns an `Account` object. Credentials can be serialized to disk to skip the browser consent flow on subsequent runs. Supports standard desktop/web OAuth flows, Google Colab environments, and service accounts.

### Method
```python
account = gscwrapper.generate_auth(
    client_config: str,
    serialize: str = None,
    credentials: str = None,
    service_account_auth: bool = False,
    google_colab: bool = False
)
```

### Parameters
#### Path Parameters
- **client_config** (str) - Required - Path to the client configuration file (e.g., `client_secret.json` or `service_account.json`).

#### Query Parameters
- **serialize** (str) - Optional - Path to save serialized credentials for future use.
- **credentials** (str) - Optional - Path to existing serialized credentials.
- **service_account_auth** (bool) - Optional - Set to `True` to use service account authentication.
- **google_colab** (bool) - Optional - Set to `True` for Google Colab environments.

### Request Example
```python
# --- OAuth: first-time authentication (opens browser) ---
account = gscwrapper.generate_auth(
    client_config='config/client_secret.json',
    serialize='config/credentials.json'   # saves token for reuse
)

# --- OAuth: subsequent runs using saved credentials ---
account = gscwrapper.generate_auth(
    client_config='config/client_secret.json',
    credentials='config/credentials.json'
)

# --- Google Colab: paste the authorization code or full redirect URL ---
account = gscwrapper.generate_auth(
    client_config='config/client_secret.json',
    serialize='config/credentials.json',
    google_colab=True
)

# --- Service account: no browser interaction needed ---
account = gscwrapper.generate_auth(
    client_config='service_account.json',
    service_account_auth=True
)
```
```

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

### Aggregate Clicks/Impressions by Day of Week

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Sums clicks and impressions per weekday (Monday–Sunday) to reveal traffic seasonality patterns. Requires the 'date' dimension.

```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-03-31')
    .dimensions(['date'])
    .get()
)

season = report.seasonality_per_day()
# date       clicks  impressions
# Monday       2218       352148
# Tuesday      2456       399690
# Wednesday    2532       414933
# Saturday      827       142410
# Sunday       1267       210677
```

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

### Extract Search Volume with DataForSEO

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Use this method to retrieve search volume for keywords using DataForSEO. Ensure `calculate_cost` is set to `False` to perform the extraction. Currently supports Google only.

```python
(
    report 
    .extract_search_volume(
        #the location code from DataForSEO
        ## 2250 is France 
        location_code=2250, 
        #credentials for the API 
        client_email="xxxx@website.com", 
        client_password="xxxxx", 
        #If you just want to calculate the cost 
        calculate_cost=True
    )
)
```

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

### Sitemap Management

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

This section details how to manage sitemaps using the `Sitemap` object. It includes methods to list all sitemaps and check their response codes.

```APIDOC
## Sitemaps

### Initialization
To manage sitemaps, first create a `Sitemap` object associated with a specific web property.

```python
# Assuming 'webproperty' is an authenticated web property object
sitemap = webproperty.sitemap
```

### list_sitemaps()

#### Description
Lists all sitemaps currently registered in Google Search Console for the selected web property.

#### Method Signature
```python
sitemap.list_sitemaps()
```

#### Response Example
Returns a DataFrame with the following columns:
- **path**: The URL of the sitemap.
- **lastSubmitted**: The date and time the sitemap was last submitted.
- **isPending**: Boolean indicating if the sitemap is pending processing.
- **isSitemapsIndex**: Boolean indicating if the sitemap is a sitemap index.
- **lastDownloaded**: The date and time the sitemap was last downloaded by Google.
- **warnings**: The number of warnings associated with the sitemap.
- **errors**: The number of errors associated with the sitemap.
- **contents**: A list of dictionaries detailing the content types and counts (submitted, indexed).
- **type**: The type of the sitemap.

### check_sitemaps()

#### Description
Checks if all registered sitemaps are returning a 200 response code. Note that the response code obtained by this method might differ from Google's perspective due to network policies.

#### Method Signature
```python
sitemap.check_sitemaps()
```

#### Response Example
Returns a DataFrame with the following columns:
- **path**: The URL of the sitemap.
- **response_code**: The HTTP response code received when checking the sitemap.
```

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

### webproperty.query

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Exposes a fluent builder (`Query` class) for constructing GSC Search Analytics requests. Chain methods before calling `.get()` to retrieve a `Report` object.

```APIDOC
## webproperty.query

### Description
`webproperty.query` exposes a fluent builder (`Query` class) for constructing GSC Search Analytics requests. Chain `.range()`, `.dimensions()`, `.filter()`, `.search_type()`, `.data_state()`, and `.limit()` before calling `.get()` to retrieve a `Report` object.

### Method
```python
report = (
    webproperty
    .query
    .range(start: str, stop: str)
    .dimensions(dimensions: list[str])
    .filter(dimension: str, expression: str, operator: str)
    .search_type(search_type: str)
    .data_state(data_state: str)
    .limit(limit: int)
    .get()
)
```

### Parameters
#### Query Builder Methods
- **range(start, stop)**: Sets the date range for the query.
  - **start** (str) - Required - Start date in 'YYYY-MM-DD' format.
  - **stop** (str) - Required - End date in 'YYYY-MM-DD' format.
- **dimensions(dimensions)**: Specifies the dimensions for the query.
  - **dimensions** (list[str]) - Required - List of dimensions (e.g., 'page', 'query', 'date').
- **filter(dimension, expression, operator)**: Applies a filter to the query.
  - **dimension** (str) - Required - The dimension to filter on (e.g., 'page', 'device').
  - **expression** (str) - Required - The value to filter by.
  - **operator** (str) - Required - The filter operator (e.g., 'contains', 'equals').
- **search_type(search_type)**: Specifies the search type.
  - **search_type** (str) - Optional - Type of search ('web', 'image', 'video', 'discover', 'googleNews', 'news'). Defaults to 'web'.
- **data_state(data_state)**: Specifies the data state.
  - **data_state** (str) - Optional - Data state ('all', 'final', 'hourly_all'). Defaults to 'final'.
- **limit(limit)**: Sets a limit on the number of rows returned.
  - **limit** (int) - Optional - Maximum number of rows to retrieve. Defaults to fetching all available rows.

### Request Example
```python
import gscwrapper

account = gscwrapper.generate_auth(
    'config/client_secret.json',
    credentials='config/credentials.json'
)
webproperty = account['https://www.example.com/']

# Basic query: clicks and impressions by page for January 2024
report = (
    webproperty
    .query
    .range(start='2024-01-01', stop='2024-01-31')
    .dimensions(['page', 'query'])
    .get()
)

# With a dimension filter (page contains "blog") and search type
report = (
    webproperty
    .query
    .range(start='2024-01-01', stop='2024-01-31')
    .dimensions(['page', 'date'])
    .filter('page', 'blog', 'contains')
    .filter('device', 'MOBILE', 'equals')
    .search_type('web')           # web | image | video | discover | googleNews | news
    .data_state('all')            # all | final (default) | hourly_all
    .limit(500)                   # cap results; default fetches all available rows
    .get()
)
```

### Response
#### Success Response
- **Report** - A `Report` object containing the query results, which can be further analyzed or converted to a Pandas DataFrame.

### Response Example
```python
print(report)
# <searchconsole.account.Report(
#     webproperty='https://www.example.com/',
#     dimensions='page - date',
#     metrics='clicks - impressions - ctr - position',
#     from_date='2024-01-01',
#     to_date='2024-01-31'
# )
```

### Usage
```python
# Load a Report from an existing DataFrame (no API call)
import pandas as pd
df = pd.read_csv('gsc_export.csv')
report = gscwrapper.query.from_dataframe(df, webproperty)
```
```

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

### show_data()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Returns the downloaded GSC data as a Pandas DataFrame. This is useful for inspecting the raw data or performing custom analyses not covered by other methods.

```APIDOC
## show_data()

### Description
Returns your data as a Pandas DataFrame. Useful to check what the API has returned and perform ad-hoc analysis that are not covered by the other methods from this library.

### Required dimensions
None

### Required metrics
None

### Output
pd.DataFrame
```

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

### uqc()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Returns the number of unique queries per page, aiding in content performance analysis.

```APIDOC
## uqc()

### Description
This method is used to return the number of (unique) queries per page.

### Method
uqc

### Parameters
This method does not require any parameters.

### Output
pd.DataFrame

### Request Example
```python
(report.uqc())
```
```

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

### Authenticate with Service Account

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

Authenticates using a service account JSON key file. No credential serialization is needed for this method.

```python
account = (
    gscwrapper
    .generate_auth(
        client_config="service_account.json", 
        service_account_auth=True
    )
)
```

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

### Count Unique Queries Per Page with uqc()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

This method returns the count of unique queries associated with each page. It requires 'query' and 'page' dimensions.

```python
(report.uqc())
```

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

### Query GSC BigQuery Export with Cost Estimation

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Run analyses directly on the GSC BigQuery export. All methods return a cost estimate by default; set .define_estimate_cost(False) to run the actual query.

```python
from google.oauth2 import service_account
from gscwrapper.query_bq import Query_BQ

credentials = service_account.Credentials.from_service_account_file(
    'service_account.json',
    scopes=['https://www.googleapis.com/auth/bigquery']
)

bq = Query_BQ(
    credentials=credentials,
    dataset='my-gcp-project.my_gsc_dataset'
)

# Explore available tables and date ranges
summary = bq.data_summary()

# Build a report (same interface as REST API)
report_bq = (
    bq
    .range(start='2024-01-01', stop='2024-03-31')
    .filter('search_type', 'web', 'equals')
    .get()
)

# By default methods return estimated BigQuery cost ($)
cost = report_bq.ctr_yield_curve()
print(f'Estimated cost: ${cost}')

# Disable cost estimation to actually run queries
report_bq.define_estimate_cost(False)

curve  = report_bq.ctr_yield_curve()
weekly = report_bq.group_data_by_period('W')
cannibal = report_bq.cannibalization(brand_variants=['mybrand'])
decay = report_bq.find_content_decay(
    threshold_decay=0.25,
    metric='clicks',
    threshold_metric=100,
    type='url',
    period='month'
)
```

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

### Check Active Pages from Sitemap

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Determine the percentage of active pages from a list of URLs by comparing them against GSC data. Can accept a sitemap URL to automatically fetch all URLs. Requires 'page' dimension and 'clicks' or 'impressions' metrics.

```python
(
    report
    .active_pages(
        sitemap_url = "https://www.website.com/sitemap_index.xml"
    )
)
```

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

### Authenticate with GSC API using gscwrapper.generate_auth()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Handles authentication for the Google Search Console API using OAuth 2.0 or service accounts. Credentials can be serialized to avoid re-authentication.

```python
import gscwrapper

# --- OAuth: first-time authentication (opens browser) ---
account = gscwrapper.generate_auth(
    client_config='config/client_secret.json',
    serialize='config/credentials.json'   # saves token for reuse
)

# --- OAuth: subsequent runs using saved credentials ---
account = gscwrapper.generate_auth(
    client_config='config/client_secret.json',
    credentials='config/credentials.json'
)

# --- Google Colab: paste the authorization code or full redirect URL ---
account = gscwrapper.generate_auth(
    client_config='config/client_secret.json',
    serialize='config/credentials.json',
    google_colab=True
)

# --- Service account: no browser interaction needed ---
account = gscwrapper.generate_auth(
    client_config='service_account.json',
    service_account_auth=True
)
```

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

### Authenticate with Saved Credentials

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

Authenticates using a client secret JSON file and previously saved credentials from a specified file path.

```python
account = gscwrapper.generate_auth(
    'config/client_secret_mvp.json',
    credentials='config/credentials.json'
)
```

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

### seasonality_per_day()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Analyzes the weekly seasonality in your data by providing daily clicks and impressions.

```APIDOC
## seasonality_per_day()

### Description
This method allows you to quickly understand the weekly seasonality you have in your data.

### Method
seasonality_per_day

### Parameters
This method does not require any parameters.

### Output
pd.DataFrame

### Request Example
```python
(report.seasonality_per_day())
```
```

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

### report.brand_vs_no_brand()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Compares branded vs. non-branded traffic over time by splitting clicks and impressions into branded and non-branded groups by day. Requires `query` and `date` dimensions.

```APIDOC
## report.brand_vs_no_brand()

### Description
Compare branded vs. non-branded traffic over time. Splits clicks and impressions into branded and non-branded groups by day. Requires `query` and `date` dimensions.

### Method
`report.brand_vs_no_brand(brand_variants)`

### Parameters
#### Query Parameters
- **brand_variants** (list of strings) - Required - A list of brand terms to identify branded traffic.

### Request Example
```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-01-31')
    .dimensions(['query', 'date'])
    .get()
)

bvnb = report.brand_vs_no_brand(brand_variants=['acme', 'acme corp'])
print(bvnb)
```

### Response
- **DataFrame**: A DataFrame comparing branded and non-branded traffic metrics over time.

### Response Example
```
# date        clicks_brand  impressions_brand  clicks_no_brand  impressions_no_brand
# 2024-01-01           0.0                4.0               60                  4917
# 2024-01-02           1.0               10.0               84                  6648
```
```

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

### report.add_first_found()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Records the first time each page or query appeared in the dataset. It adds a 'first_found_page' or 'first_found_query' column to the report, indicating the earliest date a specific URL or query was encountered. Requires the 'date' dimension plus either 'page' or 'query'.

```APIDOC
## report.add_first_found()

### Description
Records when each page or query first appeared. Adds a `first_found_page` or `first_found_query` column to the report containing the earliest date that URL or query was seen in the dataset. Requires `date` plus either `page` or `query` dimension.

### Parameters
- **dimension** (string) - Required - The dimension to track ('page' or 'query').

### Request Example
```python
report = (
    webproperty.query
    .range(start='2023-01-01', stop='2024-03-31')
    .dimensions(['page', 'date'])
    .get()
)

with_first_found = report.add_first_found('page')
```

### Response
#### Success Response
- **with_first_found** (Report object) - The report object with an added 'first_found_page' or 'first_found_query' column.

### Response Example
```
# page                         date        clicks  first_found_page
# https://example.com/post-1   2024-01-15       5       2023-03-01
# https://example.com/post-2   2024-01-15       2       2024-01-10  ← new content
```
```

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

### Track Pages Published Per Day with pages_per_day()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Designed with Google Discover in mind, this method helps determine the number of pages that appeared per day. It returns a table with 'date' and 'page' columns.

```python
(report.pages_per_day())
```

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

### Check Sitemaps for Response Codes

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

Verify if all registered sitemaps return a 200 OK response code. Note that the response code obtained by this method might differ from Google's.

```python
(
    sitemap
    .check_sitemaps()
)
```

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

### Find Potential Content to Remove

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Identify underperforming content by providing a sitemap URL and optional thresholds for clicks and impressions. This helps in streamlining content strategy by flagging pages that may need removal or updates.

```python
(
    report 
    .find_potential_contents_to_kill(
        #my sitemap 
        "https://www.website.com/sitemap_index.xml", 
        #the threshold 
        clicks_threshold=0, 
        impressions_threshold=0,
    )
)
```

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

### cannibalization()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Identifies cannibalization issues by finding queries where multiple pages rank and represent a significant portion of clicks, or where a query represents a significant portion of a page's clicks. It helps in identifying potential content overlap and optimization opportunities. It's important to provide common branding structures to filter out false positives.

```APIDOC
## cannibalization()

### Description
Analyzes Google Search Console data to identify keyword cannibalization issues. This method helps find queries where multiple pages rank, or where a single query drives a significant percentage of clicks for both a specific page and overall.

### Method
`cannibalization`

### Parameters
#### Optional Parameters
- **brand_variants** (list) - A list of strings representing common branding terms to exclude from the analysis, preventing false positives on branded terms.

### Output
A pandas DataFrame containing information about pages and queries exhibiting cannibalization, including:
- `page`: The URL of the page.
- `query`: The search query.
- `clicks_query`: Clicks for the query on the specific page.
- `impressions`: Impressions for the query on the specific page.
- `click_pct`: Percentage of total clicks for the query that went to this page.
- `clicks_page`: Total clicks for the page.
- `click_pct_page`: Percentage of the page's total clicks attributed to this query.

### Request Example
```python
report.cannibalization(brand_variants=['brand', 'mybrand'])
```

### Response Example
```
| page                       | query   | clicks_query | impressions | click_pct | clicks_page | click_pct_page |
|----------------------------|---------|--------------|-------------|-----------|-------------|----------------|
| https://www.website.com/blog/content_1 | xxxxx   | 11           | 385         | 57.89       | 44          | 25.00          |
| https://www.website.com/blog/content_2 | xxxxx   | 8            | 191         | 42.10       | 23          | 34.78          |
| https://www.website.com/blog/content_1 | yyyyy   | 15           | 387         | 62.50       | 44          | 34.09          |
| https://www.website.com/blog/content_2 | yyyyy   | 9            | 148         | 37.50       | 23          | 39.13          |
```
```

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

### Check Sitemap HTTP Response Codes

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Fetches each registered sitemap URL and reports its HTTP response code. Useful for catching sitemaps that have become inaccessible.

```python
sitemap = webproperty.sitemap

health = sitemap.check_sitemaps()
# path                                      response_code
# https://example.com/sitemap_index.xml               200
# https://example.com/old-sitemap.xml                 404
```

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

### webproperty.sitemap.check_sitemaps()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Fetches each registered sitemap URL and reports its HTTP response code. Useful for catching sitemaps that have become inaccessible.

```APIDOC
## webproperty.sitemap.check_sitemaps()

### Description
Fetches each registered sitemap URL and reports its HTTP response code. Useful for catching sitemaps that have become inaccessible.

### Method
```python
sitemap = webproperty.sitemap

health = sitemap.check_sitemaps()
# path                                      response_code
# https://example.com/sitemap_index.xml               200
# https://example.com/old-sitemap.xml                 404
```
```

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

### Enrich Keywords with DataForSEO Search Volume

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Calls the DataForSEO API to append a 'search_volume' column to the report. Requires 'query' dimension and valid DataForSEO credentials. Set 'calculate_cost=False' to run extraction (default estimates cost).

```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-03-31')
    .dimensions(['query'])
    .get()
)

# Estimate cost first (default behaviour)
report.extract_search_volume(
    location_code=2840,           # 2840 = United States
    client_email='user@example.com',
    client_password='secret',
    calculate_cost=True           # prints estimated cost, no API call
)
# The cost of the extraction will be $X.XX
```

```python
# Run the actual extraction
enriched = report.extract_search_volume(
    location_code=2840,
    client_email='user@example.com',
    client_password='secret',
    calculate_cost=False
)
# query           clicks  impressions  search_volume
# python seo         45         1200           2400
```

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

### Build CTR Yield Curve with ctr_yield_curve()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Calculates the weighted average CTR for each rounded position (1–10). Requires `query` and `date` dimensions, along with `clicks`, `impressions`, and `position` metrics. This method helps visualize CTR performance across different average positions.

```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-03-31')
    .dimensions(['query', 'date'])
    .get()
)

curve = report.ctr_yield_curve()
print(curve)
# position   ctr   clicks  impressions  kw_count
# 1.0       19.02    807         4242      1516
# 2.0       11.66    476         4084      1026
# 3.0       15.10    340         2252       637
```

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

### Analyze Content Decay

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Detects content that may be suffering from decay by comparing recent performance against historical peaks. Configure with a metric (clicks or impressions), a threshold for peak performance, a decay threshold, and the analysis period (week or month).

```python
(
    report 
    .find_content_decay(
        threshold_metric=100,
        #to choose between clicks and impressions 
        metric = 'clicks', 
        threshold_decay=0.1, 
        #choose between query or page 
        type='query', 
        #to choose between week and month 
        period='month')
 )
)
```

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

### pages_per_day()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Calculates the number of pages that appeared per day, designed with Google Discover in mind.

```APIDOC
## pages_per_day()

### Description
This method has been designed thinking about Google Discover. You can easily know how many pages has appeared per day using this method.

### Method
pages_per_day

### Parameters
This method does not require any parameters.

### Output
pd.DataFrame

### Request Example
```python
(report.pages_per_day())
```
```

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

### Generate Authentication for Google Colab

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README.md

Use this method to generate authentication credentials compatible with Google Colab. Ensure you have your client_secret.json file available.

```python
( 
           gscwrapper
           .generate_auth(
               client_config = "/client_secret.json", 
               serialize="/credentials.json",
               #extra param to make it work with Colab
               google_colab=True
           )
)
```

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

### Identify Low-Traffic Content for Pruning

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Cross-references a sitemap against the report and returns URLs below specified clicks and impressions thresholds. Requires 'page' dimension.

```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-03-31')
    .dimensions(['page'])
    .get()
)

to_kill = report.find_potential_contents_to_kill(
    sitemap_url='https://www.example.com/sitemap_index.xml',
    clicks_threshold=5,
    impressions_threshold=50
)
# loc                                         clicks  impressions
# https://example.com/blog/old-post-2019         0.0          0.0
# https://example.com/blog/thin-content          3.0         12.0
```

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

### Count Unique Queries Per Page (UQC)

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Returns the number of unique queries associated with each page, sorted descending. Requires 'query' and 'page' dimensions.

```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-03-31')
    .dimensions(['page', 'query'])
    .get()
)

uqc = report.uqc()
# page                              uqc
# https://example.com/blog/post-1  4598
# https://example.com/blog/post-2  3456
```

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

### Detect Cannibalization with cannibalization()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Identifies keyword cannibalization issues where multiple pages compete for the same query. This method requires `page` and `query` dimensions and flags queries where two or more pages each claim ≥10% of clicks for that query and the query represents ≥10% of the page's clicks. Brand terms can be excluded using `brand_variants`.

```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-03-31')
    .dimensions(['page', 'query'])
    .get()
)

cannibal = report.cannibalization(brand_variants=['mybrand', 'my brand'])
print(cannibal)
# page                             query        clicks_query  impressions  click_pct  clicks_page  click_pct_page
# https://example.com/blog/post-1  seo tips              11          385      57.89           44           25.00
# https://example.com/blog/post-2  seo tips               8          191      42.10           23           34.78
```

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

### Apply Redirect Mapping to Page URLs

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Replaces old URLs in the report with their redirect targets for accurate before/after traffic comparison during site migrations. Requires the 'page' dimension.

```python
import pandas as pd

redirects = pd.DataFrame({
    'from': ['https://example.com/old-page', 'https://example.com/another-old'],
    'to':   ['https://example.com/new-page', 'https://example.com/another-new']
})

report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-03-31')
    .dimensions(['page'])
    .get()
)

updated = report.update_urls(redirect_mapping=redirects)
# updated.show_data() now contains the new URLs instead of the old ones
after_df = updated.show_data()
```

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

### webproperty.sitemap.list_sitemaps()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Lists all sitemaps registered within Google Search Console for the specified web property. This method returns a DataFrame containing metadata for each sitemap, including its path, last submission date, pending status, sitemap index status, and error counts.

```APIDOC
## webproperty.sitemap.list_sitemaps()

### Description
Lists all sitemaps registered in GSC. Returns a DataFrame of all sitemaps submitted to Google Search Console for the web property, including metadata such as last submission date, error counts, and content types.

### Parameters
None

### Request Example
```python
sitemap = webproperty.sitemap

df = sitemap.list_sitemaps()
```

### Response
#### Success Response
- **df** (DataFrame) - A DataFrame containing information about registered sitemaps.

### Response Example
```
# path                                      lastSubmitted              isPending  isSitemapsIndex  errors
```
```

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

### Perform Keyword Gap Analysis

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Compares keywords in the Report object against an external list to identify keywords not present in the report. Requires a DataFrame with keywords and the column name.

```python
(report.keyword_gap(df, column='keyword'))
```

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

### report.seasonality_per_day()

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

Aggregates clicks and impressions by the day of the week to reveal traffic seasonality patterns. Requires the 'date' dimension.

```APIDOC
## report.seasonality_per_day()

### Description
Aggregates clicks/impressions by day of week. Sums clicks and impressions per weekday (Monday–Sunday) to reveal traffic seasonality patterns. Requires the `date` dimension.

### Parameters
This method does not take any parameters.

### Request Example
```python
report = (
    webproperty.query
    .range(start='2024-01-01', stop='2024-03-31')
    .dimensions(['date'])
    .get()
)

season = report.seasonality_per_day()
```

### Response
Returns a report with columns `date` (day of the week), `clicks`, and `impressions`, showing aggregated values for each day.
```

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

### webproperty.inspect

Source: https://context7.com/antoineeripret/gsc_wrapper/llms.txt

The Inspect object allows bulk URL inspection via the GSC URL Inspection API. Add URLs with add_urls(), optionally remove some with remove_urls(), then call execute() to retrieve inspection results as a normalized DataFrame.

```APIDOC
## URL Inspection API

### `webproperty.inspect` — Inspect URLs for indexing status

The `Inspect` object allows bulk URL inspection via the GSC URL Inspection API. Add URLs with `add_urls()`, optionally remove some with `remove_urls()`, then call `execute()` to retrieve inspection results as a normalized DataFrame.

```python
inspect = webproperty.inspect

# Add URLs to inspect
inspect.add_urls([
    'https://www.example.com/blog/post-1',
    'https://www.example.com/blog/post-2',
    'https://www.example.com/product/widget'
])

# Check how many URLs are queued
print(inspect.len())  # 3

# Remove a URL before executing
inspect.remove_urls(['https://www.example.com/product/widget'])

# Execute (1 API call per unique URL, ~1s wait between calls)
results = inspect.execute()

# If execution fails mid-way, retrieve partial results
partial = inspect.results

print(results.columns.tolist())
# ['indexStatusResult.verdict', 'indexStatusResult.robotsTxtState',
#  'indexStatusResult.indexingState', 'indexStatusResult.lastCrawlTime',
#  'mobileUsabilityResult.verdict', ..., 'inspectionUrl']
```
```

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

### Detect CTR Outliers with find_ctr_outliers()

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

This method identifies CTR outliers by comparing expected CTR (based on position) with real CTR (based on clicks & impressions). It's advised to filter the Report object to avoid mixing different SERP layouts.

```python
(report.find_ctr_outliers())
```

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

### Add First Found Date for Pages or Queries

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-METHODS.md

Adds a column indicating the first time a page or query was encountered in the report data. Ensure sufficient data history for meaningful results.

```python
(report.add_first_found("page").show_data())
```

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

### Save Credentials for Future Use

Source: https://github.com/antoineeripret/gsc_wrapper/blob/master/README-API.md

Authenticates using a client secret JSON file and saves the generated credentials to a specified file path for future use, avoiding repeated OAuth consent.

```python
account = gscwrapper.generate_auth(
    'config/client_secret_mvp.json', 
    serialize='config/credentials.json'
)
```