Marketplace SEO API¶

Analyze and score AWS Marketplace listings for SEO performance. Supports async processing with polling, real-time data enrichment, and trend tracking.

Base URL: https://api.vell.ai/api/v1 Authentication: Bearer token Prefix: /marketplace

Endpoints¶

Get SEO Score¶

GET /marketplace/listings/{listingId}/seo-score

Parameter	Type	Location	Required	Default	Description
`listingId`	string	path	Yes	—	AWS Marketplace listing ID
`refresh`	boolean	query	No	`false`	Force re-calculation (skip 24h cache)
`category`	string	query	No	`default`	Category code for benchmarking
`brand_keyword`	string	query	No	—	Brand keyword for analysis
`use_realtime_data`	boolean	query	No	`false`	Include real-time data sources
`include_content_analysis`	boolean	query	No	`false`	Include content quality analysis

Response (cached — 200):

{
  "success": true,
  "data": {
    "listing_id": "prod-abc123",
    "overall_score": 85,
    "grade": "A",
    "breakdown": {
      "title": 90,
      "description": 80,
      "highlights": 85,
      "keywords": 75,
      "images": 95
    },
    "analyzed_at": "2026-02-26T08:00:00Z"
  },
  "cached": true,
  "status": "completed"
}

Response (processing — 202):

{
  "success": true,
  "id": 456,
  "status": "pending",
  "message": "Score calculation started. Poll /status/{id} for results."
}

Async processing

SEO analysis may take several seconds. If not cached, the endpoint returns 202 with a job ID. Poll the status endpoint for results.

Analyze Listing URL¶

POST /marketplace/seo-score/analyze

Parameter	Type	Required	Default	Description
`listing_url`	string	Yes	—	AWS Marketplace listing URL or ID
`category_code`	string	No	`default`	Category for benchmarking
`brand_keyword`	string	No	—	Brand keyword
`partner_domain`	string	No	—	Partner website domain
`use_realtime_data`	boolean	No	`false`	Use real-time data sources
`include_content_analysis`	boolean	No	`false`	Include content quality
`sync`	boolean	No	`false`	Force synchronous processing

The listing_url accepts:

Full URL: https://aws.amazon.com/marketplace/pp/prodview-abc123
Partial path: marketplace/pp/prodview-abc123
Bare listing ID: prodview-abc123 (must be >10 characters)

Response (async — 202):

{
  "success": true,
  "id": 456,
  "status": "pending",
  "message": "Score calculation started. Poll /status/{id} for results."
}

Response (sync — 200):

{
  "success": true,
  "id": 456,
  "status": "completed",
  "data": {}
}

Check Analysis Status¶

GET /marketplace/seo-score/status/{id}

Parameter	Type	Location	Description
`id`	integer	path	Analysis job ID

Response (completed):

{
  "success": true,
  "id": 456,
  "status": "completed",
  "started_at": "2026-02-26T10:00:00Z",
  "completed_at": "2026-02-26T10:00:08Z",
  "data": {}
}

Response (processing with stale data):

{
  "success": true,
  "id": 456,
  "status": "processing",
  "data": {},
  "stale": true,
  "stale_age_hours": 2.5,
  "message": "Showing previous results while fresh analysis is calculated.",
  "confidence": "cached"
}

Response (failed):

{
  "success": true,
  "id": 456,
  "status": "failed",
  "error": "Unable to fetch listing data from AWS Marketplace"
}

Automatic fallback

If a job has been pending for >15 seconds, the status endpoint automatically falls back to synchronous processing. It may also serve stale cached data while processing.

Use Cases¶

Score a Single Listing¶

import requests
import time

API = "https://api.vell.ai/api/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Start analysis
resp = requests.post(f"{API}/marketplace/seo-score/analyze", headers=HEADERS, json={
    "listing_url": "https://aws.amazon.com/marketplace/pp/prodview-abc123",
    "include_content_analysis": True,
})
job = resp.json()

# Poll for results
while job["status"] in ("pending", "processing"):
    time.sleep(3)
    resp = requests.get(f"{API}/marketplace/seo-score/status/{job['id']}", headers=HEADERS)
    job = resp.json()

print(f"Score: {job['data']['overall_score']} ({job['data']['grade']})")

Monitor Listing SEO Over Time¶

Set up a weekly cron to call GET /marketplace/listings/{id}/seo-score?refresh=true
Track score changes in your analytics system
Use the breakdown field to identify which areas need improvement

Compare Listings¶

Analyze multiple listings with POST /marketplace/seo-score/analyze
Use the same category_code for fair benchmarking
Compare overall_score and breakdown fields across listings