From 2d9ee68285df137553275b78beb61cf54c46ce9d Mon Sep 17 00:00:00 2001 From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com> Date: Wed, 15 Jul 2026 10:15:48 +0530 Subject: [PATCH] feat(amazon): add Amazon Product API connector with detailed documentation and use cases --- .../lib/connectors-marketing/amazon.tsx | 315 ++++++++++++++++++ .../lib/connectors-marketing/index.ts | 2 + 2 files changed, 317 insertions(+) create mode 100644 surfsense_web/lib/connectors-marketing/amazon.tsx diff --git a/surfsense_web/lib/connectors-marketing/amazon.tsx b/surfsense_web/lib/connectors-marketing/amazon.tsx new file mode 100644 index 000000000..b98ac38b6 --- /dev/null +++ b/surfsense_web/lib/connectors-marketing/amazon.tsx @@ -0,0 +1,315 @@ +import { IconBrandAmazon } from "@tabler/icons-react"; +import type { ConnectorPageContent } from "./types"; + +export const amazon: ConnectorPageContent = { + slug: "amazon", + name: "Amazon", + cardTitle: "Amazon Product API", + icon: IconBrandAmazon, + + metaTitle: "Amazon Product Scraper API for Price & Review Data | SurfSense", + metaDescription: + "Scrape public Amazon product data as structured JSON: prices, ratings, reviews, offers, sellers, and best-seller ranks. Query by URL or search term via API or MCP. Start free.", + keywords: [ + "amazon product api", + "amazon scraper api", + "amazon price scraper", + "scrape amazon product data", + "amazon product data api", + "amazon review scraper", + "amazon best sellers api", + "amazon asin lookup", + "amazon price tracking api", + "amazon competitor monitoring", + "amazon offers scraper", + "ecommerce product api", + ], + + h1: "Amazon Product Scraper API for Price, Review, and Offer Data", + heroLede: + "The SurfSense Amazon Product API scrapes public Amazon listings as structured JSON: price and list price, rating and review breakdown, availability, marketplace offers, sellers, best-seller ranks, and on-page reviews. Point your AI agents at a search term or product URL and track prices, monitor competitors, and mine reviews — no login, only public data.", + + transcript: { + prompt: "Track the price and rating of the top mechanical keyboards on Amazon", + toolCall: + 'amazon.scrape({ search_terms: ["mechanical keyboard"],\n max_items: 5, max_offers: 3 })', + rows: [ + { + primary: "Keychron K8 Pro — $89.99 (was $99.99)", + secondary: "4.7 stars · 12,431 ratings · In Stock", + tag: "-10%", + }, + { + primary: "3 marketplace offers, cheapest $84.50 used", + secondary: "sold by 2 third-party sellers", + tag: "offers", + }, + { + primary: "#2 in Computer Keyboards best-sellers", + secondary: "Electronics › Accessories › Keyboards", + tag: "rank", + }, + ], + resultSummary: "5 products · 14 offers · 5 best-seller ranks · surfaced in 3.1s", + }, + + extractIntro: + "Give the API a list of product/search/category/best-seller URLs or search terms and a domain. It returns one structured item per product, with pricing, ratings, offers, and provenance parsed into their own fields.", + extractFields: [ + { + label: "Product core", + description: + "Title, ASIN, brand, price, list price, availability, condition, and canonical URL for every product.", + }, + { + label: "Ratings & reviews", + description: + "Star rating, review count, the 5-to-1-star histogram, and on-page customer reviews with text, author, and date.", + }, + { + label: "Marketplace offers", + description: + "Additional buy-box offers with price, condition, delivery, and the third-party seller behind each.", + }, + { + label: "Sellers", + description: + "Public seller profile summaries — name, rating, and feedback count — for the featured and offer sellers.", + }, + { + label: "Best-seller ranks", + description: + "Category rank positions and best-seller list placements, for demand and category monitoring.", + }, + { + label: "Variants & media", + description: + "Variant ASINs and attributes (color, size), per-variant prices, gallery and high-resolution images.", + }, + ], + + useCasesHeading: "What teams do with the Amazon Product API", + useCases: [ + { + title: "Price and buy-box tracking", + description: + "Watch your own and competitors' prices, list prices, and marketplace offers across marketplaces. Feed each run to an agent that diffs prices and alerts you when a competitor undercuts or the buy box changes hands.", + }, + { + title: "Review mining and product research", + description: + "Pull ratings, the star histogram, and on-page reviews to understand what customers love and complain about, then brief an agent to summarize themes and inform your roadmap or listing copy.", + }, + { + title: "Best-seller and category monitoring", + description: + "Track best-seller ranks in the categories you care about to spot rising products and demand shifts before they show up anywhere else.", + }, + { + title: "Catalog and seller intelligence", + description: + "Enrich a catalog by ASIN with structured attributes, variants, and images, and see which third-party sellers are winning offers on the products that matter to you.", + }, + ], + + comparison: { + heading: "An Amazon scraper API built for agents", + intro: + "Most Amazon data APIs bill per request, meter add-ons separately, and leave the discovery-to-detail logic to you. Here is how SurfSense compares.", + columnLabel: "Typical Amazon data API", + rows: [ + { + feature: "Pricing", + official: "Per-request pricing that climbs fast at scale", + surfsense: "Pay per product returned, with a free tier to start", + }, + { + feature: "Discovery", + official: "Separate search and detail endpoints you stitch together", + surfsense: "One verb takes search terms, product, category, or best-seller URLs", + }, + { + feature: "Offers & sellers", + official: "Often separate paid endpoints", + surfsense: "Offers and seller profiles enriched inline on the product", + }, + { + feature: "Data access", + official: "Requires accounts, keys, or approval for many providers", + surfsense: "Public, anonymous data only — no login or seller account", + }, + { + feature: "Agent-ready", + official: "No; you wire the harness yourself", + surfsense: "MCP server exposes amazon.scrape as a native tool", + }, + ], + }, + + api: { + platform: "amazon", + verb: "scrape", + mcpTool: "amazon.scrape", + requestBody: { + search_terms: ["mechanical keyboard"], + max_items: 5, + max_offers: 3, + }, + }, + + schema: { + requestNote: + "Provide urls or search_terms (at least one). Up to 20 combined sources per call.", + request: [ + { + name: "urls", + type: "string[]", + description: + "Amazon product, search, category, best-seller, or short (a.co / amzn.to) URLs. Provide urls or search_terms.", + }, + { + name: "search_terms", + type: "string[]", + description: + "Search phrases run on the Amazon domain, e.g. 'wireless earbuds'. Provide search_terms or urls.", + }, + { + name: "max_items", + type: "integer", + defaultValue: "10", + description: "Max products per search term or category/best-seller URL, 1 to 100.", + }, + { + name: "domain", + type: "string", + defaultValue: '"www.amazon.com"', + description: "Amazon marketplace domain, e.g. 'www.amazon.co.uk'.", + }, + { + name: "include_details", + type: "boolean", + defaultValue: "true", + description: + "Fetch full product detail pages. false returns faster card-only results.", + }, + { + name: "max_offers", + type: "integer", + defaultValue: "0", + description: + "Extra marketplace offers to fetch per product, 0 to 100. 0 returns the featured offer only.", + }, + { + name: "include_sellers", + type: "boolean", + defaultValue: "false", + description: "Enrich the product and each offer with the seller's public profile.", + }, + { + name: "max_variants", + type: "integer", + defaultValue: "0", + description: "Product variants to return as separate results, 0 to 100.", + }, + { + name: "include_variant_prices", + type: "boolean", + defaultValue: "false", + description: "Attach per-variant prices (one extra request per variant).", + }, + { + name: "country_code", + type: "string", + description: "Two-letter delivery country for localized pricing, e.g. 'us'.", + }, + { + name: "zip_code", + type: "string", + description: "Delivery ZIP/postal code for localized availability, e.g. '10001'.", + }, + { + name: "language", + type: "string", + description: "Content language for the domain, e.g. 'en'.", + }, + ], + responseNote: + "The response is { items: [...] } with one item per product. One returned product is one billable unit; error items are never billed.", + response: [ + { + name: "title / asin / brand", + type: "string", + description: "Product identity: display title, ASIN, and brand.", + }, + { + name: "price / listPrice", + type: "object", + description: "Current price and strike-through list price, each with value and currency.", + }, + { + name: "stars / reviewsCount / starsBreakdown", + type: "object", + description: + "Average rating, total review count, and the 5-to-1-star distribution as fractions.", + }, + { + name: "offers", + type: "object[]", + description: + "Marketplace offers with price, condition, delivery, seller, and pinned-offer flag.", + }, + { + name: "seller", + type: "object", + description: "Featured seller profile: id, name, url, rating, and feedback count.", + }, + { + name: "bestsellerRanks", + type: "object[]", + description: "Category rank positions and best-seller list placements.", + }, + { + name: "variantAsins / variantDetails / variantAttributes", + type: "object[]", + description: "Related variant ASINs and their attributes and per-variant prices.", + }, + { + name: "productPageReviews", + type: "object[]", + description: "On-page customer reviews with text, author, rating, and date.", + }, + ], + }, + + faq: [ + { + question: "What is an Amazon product API?", + answer: + "An Amazon product API returns a listing's data as structured JSON instead of raw HTML. The SurfSense Amazon API scrapes public product pages and gives you price, rating, review breakdown, offers, sellers, and best-seller ranks as clean JSON your agents can read.", + }, + { + question: "Can I track Amazon prices with it?", + answer: + "Yes. Each product returns its current price, list price, and marketplace offers. Run the same URLs or search terms on a schedule and diff the prices to build price and buy-box tracking, without maintaining scrapers or proxies yourself.", + }, + { + question: "Does it only use public data?", + answer: + "It does. The scraper collects public, anonymous product data only — no login, seller account, or authenticated APIs. That covers product details, ratings, on-page reviews, offers, public seller profiles, and best-seller rankings.", + }, + { + question: "How do I look up a product by ASIN or search term?", + answer: + "Pass a product URL (which contains the ASIN) in urls, or a phrase in search_terms to discover products on the domain. You can also pass search, category, and best-seller URLs. One verb, amazon.scrape, handles all of them.", + }, + ], + + related: [ + { label: "Google Search API", href: "/google-search" }, + { label: "Google Maps API", href: "/google-maps" }, + { label: "Web Crawl API", href: "/web-crawl" }, + { label: "Reddit API", href: "/reddit" }, + { label: "SurfSense MCP Server", href: "/mcp-server" }, + { label: "Read the docs", href: "/docs" }, + ], +}; diff --git a/surfsense_web/lib/connectors-marketing/index.ts b/surfsense_web/lib/connectors-marketing/index.ts index 826a1f261..7d79efd9b 100644 --- a/surfsense_web/lib/connectors-marketing/index.ts +++ b/surfsense_web/lib/connectors-marketing/index.ts @@ -1,3 +1,4 @@ +import { amazon } from "./amazon"; import { googleMaps } from "./google-maps"; import { googleSearch } from "./google-search"; import { instagram } from "./instagram"; @@ -17,6 +18,7 @@ const CONNECTOR_LIST: ConnectorPageContent[] = [ tiktok, googleMaps, googleSearch, + amazon, webCrawl, ];