Google Ads API for Shopping: Metrics, Segments & Developer Guide

Google Ads API Overview

The Google Ads API lets you programmatically manage Google Ads accounts, including Shopping campaigns. For Shopping specifically, it's the only way to get detailed product-level performance data that isn't available in the UI.

What You Can Do

• Query performance data: Get metrics at product, campaign, ad group levels
• Manage campaigns: Create, update, pause campaigns programmatically
• Adjust bids: Set bids at product group level using various bidding strategies
• Build reports: Create custom reports not possible in the UI
• Automate workflows: Trigger actions based on performance

API vs Scripts vs UI

Capability	API	Scripts	UI
Product-level metrics	Full access	Limited	Basic only
Custom reporting	Full flexibility	Moderate	Predefined
External integration	Yes	Limited	No
Setup complexity	High	Medium	None

Authentication Setup

The Google Ads API uses OAuth 2.0 for authentication. You'll need:

1. Google Cloud Project: Create a project in Google Cloud Console
2. OAuth credentials: Create OAuth 2.0 client ID
3. Developer token: Apply through Google Ads API Center
4. Refresh token: Generated during OAuth flow

Configuration File

Most client libraries use a configuration file:

# google-ads.yaml
developer_token: YOUR_DEVELOPER_TOKEN
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
login_customer_id: YOUR_MCC_ID  # Optional, for MCC accounts

Querying Shopping Data

The Google Ads Query Language (GAQL) lets you query Shopping performance. For product-level data, use the shopping_performance_view resource.

Basic Product Performance Query

SELECT
  segments.product_item_id,
  segments.product_title,
  segments.product_brand,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM shopping_performance_view
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC
LIMIT 100

Key Resources for Shopping

• shopping_performance_view — Product-level performance metrics
• shopping_product — Product feed data
• product_group_view — Product group structure and bids
• campaign — Campaign settings for Shopping campaigns

Key Shopping Metrics

Common metrics for Shopping analysis:

Cost & Engagement

• metrics.impressions — Number of times ads were shown
• metrics.clicks — Number of clicks
• metrics.cost_micros — Cost in micros (divide by 1,000,000 for actual currency)
• metrics.ctr — Click-through rate
• metrics.average_cpc — Average cost per click (micros)

Conversions

• metrics.conversions — Number of conversions
• metrics.conversions_value — Total conversion value
• metrics.conversions_from_interactions_rate — Conversion rate
• metrics.cost_per_conversion — Cost per conversion (micros)
• metrics.value_per_conversion — Average conversion value

Competitive Metrics

• metrics.search_impression_share — Impression share percentage
• metrics.search_budget_lost_impression_share — IS lost due to budget
• metrics.search_rank_lost_impression_share — IS lost due to rank
• metrics.search_click_share — Click share percentage

For the complete metrics reference, see our API metrics guide.

Shopping Segments

Segments let you break down data by dimensions. Shopping-specific segments include:

Product Identifiers

• segments.product_item_id — Your product ID
• segments.product_title — Product title
• segments.product_brand — Product brand

Product Categories

• segments.product_category_level1 through level5 — Google product category hierarchy
• segments.product_type_l1 through l5 — Your product type hierarchy

Custom Labels

• segments.product_custom_attribute0 through attribute4 — Custom label values

Other Useful Segments

• segments.product_channel — ONLINE or LOCAL
• segments.product_condition — NEW, REFURBISHED, USED
• segments.date — Date for time-series analysis

For advanced segmentation techniques, see our Shopping segments guide.

API Versioning

Google releases new API versions regularly. Managing versions is critical for production systems.

Version Lifecycle

• Release: New version announced, available for use
• Sunset announced: Deprecation date published (usually 12 months out)
• Sunset: Old version stops working

Migration Strategy

1. Monitor the Google Ads API blog for release announcements
2. Review breaking changes in release notes
3. Test new version in staging environment
4. Update client library version
5. Deploy and monitor for issues

Practical Examples

Python: Get Top Products by Spend

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("google-ads.yaml")
ga_service = client.get_service("GoogleAdsService")

query = """
    SELECT
        segments.product_item_id,
        segments.product_title,
        metrics.cost_micros,
        metrics.conversions,
        metrics.conversions_value
    FROM shopping_performance_view
    WHERE segments.date DURING LAST_30_DAYS
    ORDER BY metrics.cost_micros DESC
    LIMIT 50
"""

response = ga_service.search_stream(
    customer_id="1234567890",
    query=query
)

for batch in response:
    for row in batch.results:
        product_id = row.segments.product_item_id
        cost = row.metrics.cost_micros / 1_000_000
        conversions = row.metrics.conversions
        roas = (row.metrics.conversions_value / cost) if cost > 0 else 0
        print(f"{product_id}: ${cost:.2f} spend, {conversions} conv, {roas:.1f}x ROAS")

Python: Find Zero-Conversion Products

query = """
    SELECT
        segments.product_item_id,
        segments.product_title,
        metrics.cost_micros,
        metrics.clicks
    FROM shopping_performance_view
    WHERE
        segments.date DURING LAST_30_DAYS
        AND metrics.conversions = 0
        AND metrics.cost_micros > 50000000
    ORDER BY metrics.cost_micros DESC
"""

# Products spending >$50 with zero conversions

Python: Product Impression Share

query = """
    SELECT
        segments.product_item_id,
        metrics.search_impression_share,
        metrics.search_budget_lost_impression_share,
        metrics.search_rank_lost_impression_share
    FROM shopping_performance_view
    WHERE segments.date DURING LAST_7_DAYS
    ORDER BY metrics.impressions DESC
    LIMIT 100
"""

# Note: Impression share is a fraction (0.5 = 50%)

API Best Practices

Query Optimization

• Only select fields you need (reduces response size)
• Use date ranges to limit data volume
• Use search_stream for large result sets
• Implement pagination for very large queries

Rate Limiting

• Implement exponential backoff for retries as recommended by the Google Ads best practices
• Batch requests where possible
• Cache results to reduce API calls
• Monitor your quota usage

Error Handling

• Catch and log all API errors
• Handle partial failures gracefully
• Implement alerting for critical failures
• Validate data before acting on it

Frequently Asked Questions

Build Better Shopping Tools

The Google Ads API unlocks product-level insights that aren't accessible through the UI. Whether you're building automated reporting, bid management, or waste detection, the API provides the data foundation.

Key takeaways:

• Use shopping_performance_view for product-level metrics
• Shopping segments let you slice data by product attributes
• Plan for regular API version updates
• Implement proper error handling and rate limiting
• Cache data to reduce API calls and costs

If you need product-level Shopping analytics without building your own integration, SKU Analyzer handles the API complexity for you—delivering product performance insights through a simple dashboard.