SEO ecommerce

E-commerce SEO Analysis#

Comprehensive product page optimization, marketplace intelligence, and competitive pricing analysis. Works standalone (on-page + schema) and with DataForSEO Merchant API for live Google Shopping and Amazon data.

Commands#

1. Product Page Analysis (No DataForSEO Needed)#

Fetch and parse any product page for on-page SEO quality.

Workflow#

1. python3 scripts/render_page.py <url> --mode auto → raw/rendered HTML
2. python3 scripts/parse_html.py --url <url>   → SEO elements
3. Analyze product-specific signals (below)

Product SEO Checklist#

Title Tag#

• Contains primary product keyword
• Includes brand name
• Under 60 characters (no truncation in SERPs)
• Format: [Product Name] - [Key Feature] | [Brand]

Meta Description#

• Contains product keyword + benefit
• Includes price or "from $XX" (triggers rich snippet interest)
• Call-to-action present (Shop now, Buy, Free shipping)
• Under 155 characters

Heading Structure#

• Single H1 matching primary product name
• H2s for: Features, Specifications, Reviews, Related Products
• No duplicate H1 tags across product variants

Product Images#

• Alt text includes product name + distinguishing feature
• File names are descriptive (not IMG_001.jpg)
• WebP format served (with JPEG fallback)
• At least 3 images per product (hero, detail, lifestyle)
• Image dimensions >= 800px for Google Shopping eligibility
• Lazy loading on below-fold images only

Internal Linking#

• Breadcrumb navigation: Home > Category > Subcategory > Product
• Related products section (cross-sell / upsell)
• Link back to category page with keyword-rich anchor
• Reviews section links to full review page (if separate)

Content Quality#

• Unique product description (not manufacturer copy-paste)
• Word count >= 200 for product description body
• Specs table present (not just prose)
• User reviews on-page (UGC signals)

Scoring#

2. Google Shopping Intelligence (DataForSEO Merchant API)#

Live competitive analysis from Google Shopping results.

Cost Guardrail (MANDATORY)#

Before EVERY Merchant API call:

python3 scripts/dataforseo_costs.py check merchant_google_products_search

• "status": "approved" -- proceed
• "status": "needs_approval" -- show cost, ask user
• "status": "blocked" -- stop, inform user

After each call:

python3 scripts/dataforseo_costs.py log merchant_google_products_search <cost>

Workflow#

# Product search: who sells what at what price
python3 scripts/dataforseo_merchant.py search "<keyword>" --marketplace google

# Seller analysis: merchant ratings and dominance
python3 scripts/dataforseo_merchant.py sellers "<keyword>"

# Normalize results for analysis
python3 scripts/dataforseo_normalize.py results.json --module merchant

Analysis Outputs#

Pricing Intelligence#

• Price distribution: min, max, median, P25, P75
• Price outliers (> 2 standard deviations from median)
• Price-to-rating correlation
• Currency normalization to USD (or user-specified)

Seller Landscape#

• Top 10 sellers by listing count
• Merchant rating distribution
• Free shipping prevalence
• New vs established sellers

Product Listing Quality#

• Title keyword patterns in top listings
• Average rating and review count benchmarks
• Image count per listing
• Availability status distribution

Load references/marketplace-endpoints.md for full API parameter details.

3. Amazon Marketplace (DataForSEO)#

Cross-marketplace intelligence comparing Google Shopping and Amazon.

Cost Guardrail (MANDATORY)#

python3 scripts/dataforseo_costs.py check merchant_amazon_products_search

Amazon endpoints are in the warn_endpoints set -- always requires user approval.

Workflow#

# Amazon product search
python3 scripts/dataforseo_merchant.py search "<keyword>" --marketplace amazon

# Cross-marketplace comparison
python3 scripts/dataforseo_merchant.py compare "<keyword>"

Cross-Marketplace Report#

4. Marketplace Keyword Gaps#

Identify mismatches between organic and Shopping visibility.

Workflow#

1. Fetch organic rankings via seo-dataforseo: dataforseo_labs_google_ranked_keywords for domain
2. Fetch Google Shopping presence via Merchant API: merchant_google_products_search for top organic keywords
3. Cross-reference results

Gap Types#

Output Format#

## Keyword Gap Analysis: example.com

### Opportunities: Organic → Shopping (12 keywords)
| Keyword | Organic Pos | Volume | CPC | Recommended Action |
|---------|------------|--------|-----|-------------------|

### Opportunities: Shopping → Organic (8 keywords)
| Keyword | Shopping Rank | Volume | CPC | Content Type Needed |
|---------|-------------|--------|-----|-------------------|

5. Product Schema Enhancement#

Validate and generate Product schema following Google's current requirements.

Required Properties (Google Merchant)#

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "",
  "image": [""],
  "description": "",
  "brand": { "@type": "Brand", "name": "" },
  "offers": {
    "@type": "Offer",
    "url": "",
    "priceCurrency": "USD",
    "price": "0.00",
    "availability": "https://schema.org/InStock",
    "seller": { "@type": "Organization", "name": "" }
  }
}

Recommended Properties (Enhance Rich Results)#

• sku -- product identifier
• gtin13 / gtin14 / mpn -- global trade identifiers
• aggregateRating -- star rating + review count
• review -- individual reviews (minimum 1)
• color, material, size -- variant attributes
• shippingDetails -- ShippingDetails with rate and delivery time
• hasMerchantReturnPolicy -- MerchantReturnPolicy with type and days

Validation Rules#

1. price must be a number string, not "$29.99" (no currency symbol)
2. availability must use full Schema.org URL enum
3. image should be array with >= 1 high-res image URL
4. priceCurrency must be ISO 4217 (USD, EUR, GBP)
5. brand.name must not be empty or "N/A"
6. Dates in priceValidUntil must be ISO 8601
7. If aggregateRating present: ratingValue and reviewCount required

Schema Scoring#

Cross-Skill Integration#

UCP — Universal Commerce Protocol (forward-looking)#

Google-led standard (co-developed with Shopify, Etsy, Walmart, Wayfair, Visa, Mastercard, etc.) for letting AI agents discover, negotiate, and transact with merchants without one-off integrations. Already powers direct buying from AI Mode and Gemini.

Merchants already on Google Merchant Center with clean Product schema can declare a UCP profile at /.well-known/ucp listing capabilities (dev.ucp.shopping.checkout, .fulfillment, .discount). See references/ucp-universal-commerce-protocol.md for audit criteria, capability examples, and the relationship to AP2 (Agent Payments Protocol).

Audit command#

# Discover and validate the UCP profile
python3 scripts/ucp_check.py https://store.example.com --json

# With endpoint reachability probes (HEAD each declared capability)
python3 scripts/ucp_check.py https://store.example.com --probe-endpoints --json

The script returns: profile presence, version, declared capabilities, structural issues (missing fields, unknown capability IDs), and (with --probe-endpoints) per-endpoint reachability. SSRF-blocked endpoints are reported explicitly. Missing profile is reported as opportunity, not failure — UCP adoption is early.

Error Handling#

Output Template#

## E-commerce SEO Report: [URL or Keyword]

### Overall Score: XX/100

### Product Page SEO
- Schema Completeness: XX/100
- Title & Meta: XX/100
- Image Optimization: XX/100
- Content Quality: XX/100
- Internal Linking: XX/100

### Marketplace Intelligence (if DataForSEO available)
- Google Shopping Listings: N products found
- Price Range: $XX - $XX (median: $XX)
- Top Seller: [name] (XX% market share)
- Amazon Comparison: [available/not checked]

### Top Recommendations
1. [Critical] ...
2. [High] ...
3. [Medium] ...

Generate a PDF report? Use `/seo google report`

Supporting file: references/marketplace-endpoints.md#

DataForSEO Merchant API Reference#

Endpoint details for Google Shopping and Amazon marketplace data.

Endpoints#

Google Shopping Products#

Parameters:

• keyword (required) -- search query
• location_code (default: 2840 = US) -- DataForSEO location ID
• language_code (default: "en") -- language
• price_min / price_max (optional) -- filter by price range
• sort_by (optional) -- "relevance", "price_low_to_high", "price_high_to_low", "rating"
• depth (optional, default: 100) -- number of results

Response fields:

• title -- product listing title
• price -- numeric price value
• currency -- currency code (USD, EUR, etc.)
• seller -- merchant name
• rating -- product rating (float, 0-5)
• reviews_count -- number of reviews
• url -- product listing URL
• image_url -- product image URL
• availability -- "in_stock", "out_of_stock", "preorder"
• delivery_info -- shipping details text
• product_id -- Google Shopping product ID

Google Shopping Sellers#

Parameters: Same as products search.

Response fields:

• seller_name -- merchant name
• seller_rating -- merchant rating (float)
• seller_reviews_count -- merchant review count
• price -- price offered by this seller
• delivery_info -- shipping and delivery text
• url -- seller listing URL

Amazon Products#

Parameters:

• keyword (required) -- search query
• location_code (default: 2840 = US)
• language_code (default: "en")
• depth (optional, default: 100)
• sort_by (optional) -- "relevance", "price_low_to_high", "price_high_to_low", "avg_customer_review"

Response fields:

• title -- product title
• price -- numeric price
• currency -- currency code
• seller -- seller/brand name
• rating -- star rating (float, 0-5)
• reviews_count -- review count
• url -- Amazon product URL
• image_url -- product image
• availability -- stock status
• asin -- Amazon Standard Identification Number
• is_prime -- Prime eligibility (boolean)
• is_best_seller -- Best Seller badge (boolean)

Task/Poll Pattern#

All Merchant endpoints use the standard DataForSEO queue pattern:

1. POST task with parameters to create endpoint
2. Poll for results with exponential backoff (2s, 4s, 8s, max 60s)
3. GET completed results by task ID

This saves 60-80% compared to live endpoints.

Rate Limits#

• Max 2000 tasks per minute (across all endpoints)
• Max 30,000 tasks per day on standard plans
• Backoff on HTTP 429: wait 60 seconds, then retry

Data Normalization#

When consuming responses, normalize:

Use scripts/dataforseo_normalize.py --module merchant for automatic normalization.

Cost Reference#

See skills/seo-dataforseo/references/cost-tiers.md for the full pricing table, budget presets, and cost reduction tips. All Merchant endpoints are $0.02/call on standard queue.

Supporting file: references/ucp-universal-commerce-protocol.md#

UCP — Universal Commerce Protocol (May 2026)#

UCP is a Google-led open standard, co-developed with Shopify and endorsed by Etsy, Target, Walmart, Wayfair, plus payment partners (Stripe, Visa, Mastercard, Adyen, Amex). Its purpose: let AI agents discover, negotiate, and transact with merchants without one-off integrations.

For commerce sites, UCP sits next to Google Merchant Center feeds and Google Business Profile as the third leg of agent-era discovery. Adoption is early but the cost of declaring a profile is low.

Primary source: Google AI optimization guide references UCP; the spec itself is co-published at developer.google.com / merchant.google.com (consult Google for the current canonical URL — the standard is moving).

What UCP is and isn't#

Merchants stay Merchant of Record under UCP — they keep customer relationships and post-purchase ownership.

How to declare a UCP profile#

Publish a profile at /.well-known/ucp describing capabilities and versions. The general shape (consult the live spec for exact field names):

{
  "version": "1.0",
  "capabilities": [
    {
      "id": "dev.ucp.shopping.checkout",
      "version": "1.0",
      "endpoint": "https://api.example.com/ucp/checkout"
    },
    {
      "id": "dev.ucp.shopping.fulfillment",
      "version": "1.0",
      "endpoint": "https://api.example.com/ucp/fulfillment"
    },
    {
      "id": "dev.ucp.shopping.discount",
      "version": "1.0",
      "endpoint": "https://api.example.com/ucp/discount"
    }
  ],
  "merchant": {
    "name": "Example Co.",
    "id": "merchant-center-id-here"
  }
}

Platforms (AI Mode in Search, Gemini, and eventually others) auto-discover the profile and negotiate. Google has built a reference implementation powering direct buying from AI Mode and Gemini.

Common capabilities to declare#

Exact identifiers are governed by the live spec. The pattern is dev.ucp.<domain>.<verb> with semantic versioning.

What claude-seo audits#

/seo ecommerce <url> should report:

1. Presence: does /.well-known/ucp resolve to a valid JSON document?
2. Capability coverage: which capabilities are declared? Flag missing checkout / fulfillment / discount as opportunities, not failures (the protocol is early).
3. Endpoint reachability: are declared endpoints HTTPS, valid TLS, not returning 5xx?
4. Version coherence: does the declared protocol version match a known release? Flag pre-release or unrecognized versions.

The audit should not score the absence of UCP as a critical failure today — adoption is early. Frame it as a forward-looking opportunity, especially for merchants already on Google Merchant Center.

How UCP interacts with existing surfaces#

A merchant that already has clean Merchant Center feeds, complete Product schema, and a checkout API can declare a UCP profile in a sprint.

Audit posture#

• Tier 1 (e-commerce sites already on Merchant Center): recommend declaring a UCP profile as a forward-looking opportunity.
• Tier 2 (DTC sites not on Merchant Center): do not recommend UCP yet — Merchant Center is the prerequisite to most flows.
• Tier 3 (informational / B2B sites): ignore UCP entirely.

Last verified#

2026-05-18. The standard is moving fast. Re-check when:

• The canonical spec URL stabilizes (currently published on Google developer docs, but exact path may change).
• AP2 reaches stable release.
• Additional platforms (beyond AI Mode + Gemini) announce UCP consumption.