--- description: "E-commerce SEO analysis: Google Shopping visibility, Amazon marketplace intelligence, product schema validation, competitor pricing analysis, and marketplace keyword gaps." --- # 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 | Command | Purpose | DataForSEO? | |---------|---------|-------------| | `/seo ecommerce <url>` | Full e-commerce SEO analysis of a product page or store | Optional | | `/seo ecommerce products <keyword>` | Google Shopping competitive analysis | Required | | `/seo ecommerce gaps <domain>` | Keyword gap: organic vs Shopping visibility | Required | | `/seo ecommerce schema <url>` | Product schema validation and enhancement | No | --- ## 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 | Category | Weight | Criteria | |----------|--------|----------| | Schema completeness | 25% | Required + recommended Product fields | | Title & meta | 15% | Keyword placement, length, format | | Image optimization | 20% | Alt text, format, sizing, count | | Content quality | 20% | Unique description, specs, reviews | | Internal linking | 10% | Breadcrumbs, related products, categories | | Technical | 10% | Page speed, mobile rendering, canonical | --- ## 2. Google Shopping Intelligence (DataForSEO Merchant API) Live competitive analysis from Google Shopping results. ### Cost Guardrail (MANDATORY) Before EVERY Merchant API call: ```bash 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: ```bash python3 scripts/dataforseo_costs.py log merchant_google_products_search <cost> ``` ### Workflow ```bash # 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) ```bash python3 scripts/dataforseo_costs.py check merchant_amazon_products_search ``` Amazon endpoints are in the `warn_endpoints` set -- always requires user approval. ### Workflow ```bash # 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 | Metric | Google Shopping | Amazon | |--------|---------------|--------| | Avg price | $ | $ | | Median rating | X.X | X.X | | Avg review count | N | N | | Top seller share | % | % | | Free shipping % | % | % | --- ## 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 | Gap Type | Meaning | Action | |----------|---------|--------| | **Organic Only** | Ranks organically but no Shopping ads | Create Google Merchant Center feed, bid on these keywords | | **Shopping Only** | Shopping visibility but weak/no organic | Create content (buying guides, comparison pages) for these keywords | | **Both Present** | Visible in both channels | Optimize: ensure price consistency, enhance schema | | **Neither** | No visibility in either | Low priority unless high volume | ### 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) ```json { "@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 | Completeness | Score | |-------------|-------| | All required fields | 50/100 | | + aggregateRating | 65/100 | | + sku/gtin/mpn | 75/100 | | + shippingDetails | 85/100 | | + merchantReturnPolicy | 90/100 | | + reviews (3+) | 100/100 | --- ## Cross-Skill Integration | Skill | Integration Point | |-------|------------------| | **seo-schema** | Delegates Product schema generation; reuses validation logic | | **seo-images** | Product image audit (alt text, format, dimensions) — plus `DigitalSourceType: TrainedAlgorithmicMedia` IPTC label for AI-generated product images (Merchant Center requirement) | | **seo-content** | Product description E-E-A-T and uniqueness analysis | | **seo-dataforseo** | Organic keyword rankings for gap analysis | | **seo-technical** | Core Web Vitals for product pages (LCP on hero image) | | **seo-google** | Google Merchant Center feed validation via GSC | ## 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 ```bash # 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 | Error | Cause | Response | |-------|-------|----------| | No Product schema found | Page lacks JSON-LD | Analyze page content, generate recommended schema | | DataForSEO credentials missing | Env vars not set | Run analysis without marketplace data, note limitation | | Cost check blocked | Daily budget exceeded | Inform user, offer free-only analysis | | Empty Shopping results | No products for keyword | Suggest broader keyword, check location settings | | Amazon API timeout | Network/rate limit | Retry with backoff, fall back to Google-only | | Invalid URL | Malformed input | Validate via `google_auth.validate_url()`, show error | | Non-product page | URL is category/homepage | Detect page type, suggest `/seo ecommerce schema` instead | --- ## 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` ```