# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Start with Search results performance + 3 dimensions</strong></td><td>Select the Search results performance report with Date, Query, and Page dimensions. This gives you the most actionable SEO dataset — keyword rankings over time with page-level detail. Add Country or Device dimensions later once you've validated the base export.</td></tr><tr><td><strong>Use the Final data state for dashboards</strong></td><td>The <strong>Final</strong> data state (default) returns settled data that won't change. Use this for recurring dashboards and reports. Only switch to <strong>All</strong> if you specifically need the freshest data and can tolerate minor revisions in the most recent 2–3 days.</td></tr><tr><td><strong>Run the "by appearance" report to discover filter values</strong></td><td>Before adding a Search appearance filter to your main Search results performance report, run the <strong>Search results performance by appearance</strong> report once. It returns all active search appearance types for your site, which you can then use as filter values.</td></tr><tr><td><strong>Separate data flows per site for clarity</strong></td><td>Although you can select multiple sites in a single data flow, creating one flow per site makes it easier to manage schedules, debug issues, and build site-specific dashboards. Use a single multi-site flow only when building a cross-property comparison.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Daily refresh is sufficient for most use cases</strong></td><td>GSC data has a 2–3 day processing delay — refreshing more than once per day rarely adds new data. A daily morning refresh keeps dashboards current. Coupler.io's data freshness TTL for GSC is 6 hours, so intra-day refreshes will return cached data within that window.</td></tr><tr><td><strong>Account for the data lag in your date range</strong></td><td>Set your End date to today. The GSC API automatically handles the processing delay — the most recent 2–3 days will simply have zero or partial data with Final state. Do not manually offset the end date to "3 days ago" unless you want to hide incomplete rows entirely.</td></tr><tr><td><strong>Use "Replace" mode for performance reports</strong></td><td>Use "Replace" (overwrite) destination mode for performance reports. This ensures your destination always has the latest numbers. Avoid "Append" mode — it would accumulate duplicate rows across refreshes since historical data can be slightly revised by Google.</td></tr><tr><td><strong>Schedule URL inspection flows weekly</strong></td><td>URL indexing status changes slowly. A weekly schedule is usually sufficient for the URLs index performance report. This also helps stay within the URL Inspection API's daily quota limits.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Limit date range for dimension-heavy exports</strong></td><td>Each dimension multiplies the number of rows. A 12-month export with Date + Query + Page + Country + Device can produce millions of rows. Start with 30–90 day ranges and increase only if your destination and data flow can handle the volume.</td></tr><tr><td><strong>Use dimension filters to reduce row count</strong></td><td>Add filters at the API level (in Coupler.io's "Filters by dimensions") rather than filtering in your destination. API-level filtering reduces data transfer time and avoids timeout issues. For example, filter by Country = USA or Page contains "/blog/" to scope the export.</td></tr><tr><td><strong>Split large URL inspection lists across flows</strong></td><td>The URL Inspection API has a per-property daily quota. If you need to inspect hundreds of URLs, split them across multiple data flows scheduled at different times or on different days. Each flow can handle up to 20 URLs concurrently.</td></tr><tr><td><strong>Remove unnecessary dimensions</strong></td><td>If you don't need Device-level breakdowns, don't include the Device dimension. Fewer dimensions = fewer rows = faster exports. You can always add dimensions back later.</td></tr></tbody></table>

## Dashboard accuracy

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Recalculate CTR and Position when aggregating</strong></td><td>CTR and Position are per-row averages. They are <strong>not summable</strong> across rows. To calculate aggregate CTR, use <code>Sum(clicks) ÷ Sum(impressions)</code>. For aggregate position, use an impression-weighted average: <code>Sum(position × impressions) ÷ Sum(impressions)</code>.</td></tr><tr><td><strong>Understand the difference between aggregation methods</strong></td><td>"By Page" aggregates by canonical URL — one impression per page per query. "By Property" aggregates across the property — one impression per property per query. "Auto" lets Google choose. For page-level SEO dashboards, use "By Page". For overall property health, use "By Property".</td></tr><tr><td><strong>Handle the "(other)" query bucket</strong></td><td>When using the Query dimension, low-volume queries are grouped under "(other)". This is a GSC API limitation. Your dashboard should either exclude "(other)" from keyword-level analysis or display it as a separate "Long tail" category. Do not treat it as a single keyword.</td></tr><tr><td><strong>Match GSC UI settings when comparing</strong></td><td>If you need your Coupler.io export to match the GSC web interface exactly, use: Search results type = Web, Aggregate data by = Auto, Data state = Final, and identical date range and dimensions. Any difference in these settings will produce different numbers.</td></tr></tbody></table>

## Combining GSC data with other sources

Google Search Console data is most powerful when combined with other marketing and analytics data in your destination.

#### Example: GSC + GA4 landing page analysis

**Data flow 1 — GSC Search results performance**

Dimensions: Date, Page

This gives you clicks, impressions, CTR, and position per page per day from Google Search.

**Data flow 2 — GA4 with Landing page dimension**

Metrics: Sessions, Engaged sessions, Key events

This gives you on-site engagement data per landing page per day from Google Analytics.

**Joining the data**

Join on the page URL column from GSC with the landing page column from GA4. Note that GSC uses full URLs (e.g., `https://example.com/blog/post`) while GA4 uses path-only (e.g., `/blog/post`). You may need a formula column to extract the path from the GSC page URL before joining.

{% hint style="info" %}
GSC and GA4 count clicks and sessions differently. A single click in GSC may result in zero or multiple sessions in GA4 due to bounce behavior, redirects, or tracking differences. Treat these as complementary metrics, not equivalent ones.
{% endhint %}

## Common pitfalls to avoid

{% columns %}
{% column %}
**Do**

* Use the **Final** data state for settled, reliable numbers
* Recalculate CTR and Position when aggregating across rows
* Run the "by appearance" report first to discover valid search appearance filter values
* Use API-level dimension filters instead of filtering in your destination
* Check the GSC UI first if Discover or Google News reports return no data
  {% endcolumn %}

{% column %}
**Don't**

* Don't sum CTR or Position values across rows — they are per-row averages
* Don't expect data from the most recent 2–3 days to be complete — GSC has a processing delay
* Don't query data older than 16 months — GSC does not retain data beyond this limit
* Don't use "Append" mode for recurring performance exports — it creates duplicate rows
* Don't inspect hundreds of URLs in a single data flow — split them to avoid quota limits
  {% endcolumn %}
  {% endcolumns %}

{% hint style="danger" %}
**Google Search Console in-app reports and comparison features are not available via the API.** Coupler.io exports raw performance data only. Comparison views, trend annotations, and the "Search appearance" groupings visible in the GSC UI must be recreated in your destination tool (Google Sheets, Looker Studio, Power BI, etc.).
{% endhint %}