# PricePulse AI — Cross-Marketplace Product Intelligence (`entranced_gelato/price-pulse-ai`) Actor Track competitor products across Amazon, eBay, and Walmart and return AI-ready product-intelligence snapshots: cross-marketplace prices, change flags, review summaries, and opportunity insights — in one MCP-friendly call. - **URL**: https://apify.com/entranced\_gelato/price-pulse-ai.md - **Developed by:** [AIDevs](https://apify.com/entranced_gelato) (community) - **Categories:** E-commerce, AI, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $40.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## PricePulse AI — Cross-Marketplace Product Intelligence **One call, one `product_intel_snapshot` per product: aligned prices across Amazon + eBay + Walmart (plus *any* Schema.org storefront via JSON-LD fallback), change flags vs. your baseline, review summaries, opportunity insights, optional webhook alerts on significant price drops, and `vs_reference` comparison against your product. MCP-ready for AI agents. Pay per snapshot, not per row.** > **Disclaimer.** Output is research material generated by automated extraction from public marketplace pages — NOT authoritative pricing, availability, or rating information. Verify every fact against the cited source URL before pricing decisions or customer-facing use. See **Terms of Use** at the bottom. > **What's new in v0.2** — webhook alerts ($0.005/dispatch), JSON-LD universal fallback (Target, Best Buy, Etsy, Shopify, any storefront with Schema.org Product), `reference_label` / `vs_reference` block, `dry_run` preview mode, Apify Residential proxy support, Amazon 2-retry backoff, Amazon locale support, variants + image-gallery extraction, and `keyword_research` un-gated with strict caps. See `CHANGELOG.md` for details. **Keywords this actor ranks for:** cross-marketplace price tracker, multi-marketplace product intelligence, Amazon eBay Walmart price compare, competitor price tracker, MAP enforcement, Buy Box monitor, MCP price intelligence, AI agent product compare, change-detection scraper, price-spread analyzer, brand portfolio monitor, restock alerts, opportunity insights actor. --- ### Why PricePulse AI | Other product / price scrapers | **PricePulse AI** | |---|---| | One marketplace per actor — chain three to compare | **One run, one snapshot, three marketplaces aligned** | | One row per marketplace per product (you do the join) | **One record per *logical product*** — already grouped | | Raw price strings, mixed currencies | Normalized `{price, currency, is_on_sale}` from every site | | No change detection — you store history yourself | **Built-in baseline diffing** with `significant` flag | | No analysis layer — just data | **Opportunity insights**: positioning, undercut alerts, spread % | | Per-row billing scales with marketplace count | **One snapshot = one charge, regardless of marketplaces** | | Fabricates fields when scrape fails | **Never guesses** — surfaces `risk_flags`, returns `candidates_only` | | LLM-locked or LLM-required | **Rule-based by default**, optional Claude Haiku enrichment | | Awkward for MCP / AI agents | **MCP-first schema**: short enums, fixed output, stamped event name | --- ### When to use - **Cross-marketplace tracking.** You sell on Amazon and Walmart and want one record per SKU per day showing where you stand on each. - **Competitor benchmarking.** You name 3–5 competitor ASINs and want a daily who-is-undercutting-whom report. - **MAP enforcement.** You set a price floor; you want flagged any site that drops below it. - **Brand portfolio health.** You ship 25 SKUs; you want a single dataset row per SKU per day across all marketplaces. - **Sale event monitoring.** Black Friday, Prime Day, Cyber Monday — hourly cadence with `change_detection_baseline_key` for live deltas. - **MCP / AI agent workflows.** Claude or GPT calls this every N minutes; gets back a structured `product_intel_snapshot` ready to reason over. ### When NOT to use - **Full review-text extraction** (per-review author + body + helpful votes) → not in v1. We compute themes + rating distribution; full reviews need a dedicated reviews scraper. - **JavaScript-rendered storefronts only** (e.g., some niche Shopify themes) → v1 is HTTP-only. Pages exposing data via JSON-LD or server-rendered HTML work; pure SPAs do not. - **Locale-specific Amazon parsing** (UK, DE, JP) → v1 targets `amazon.com` selectors. Other locales may parse partially. - **Single-marketplace, max-volume scraping** at $0.005/row → use a commodity Amazon-only scraper. We're priced for the joined, enriched, change-detected use case. --- ### Quick start — 6 recipes that cover 90% of real use #### 1. Track your main product on Amazon (cheapest, fastest) ```json { "mode": "product_list", "products": [{"label": "my_main_chair", "asin": "B08N5WRWNW"}], "marketplaces": ["amazon"] } ```` → 1 snapshot, **$0.04**. #### 2. Cross-marketplace snapshot — your product on all 3 sites ```json { "mode": "product_list", "products": [{"label": "my_main_chair", "asin": "B08N5WRWNW"}], "marketplaces": ["amazon", "ebay", "walmart"], "include_reviews_summary": true } ``` → Still **1 snapshot, $0.04**. (Marketplaces are bundled, not billed separately.) #### 3. Daily competitor digest with change detection ```json { "mode": "product_list", "products": [ {"label": "my_chair", "asin": "B08N5WRWNW"}, {"label": "competitor_A", "asin": "B09ZZZ9999"}, {"label": "competitor_B", "asin": "B07YYY0000"} ], "marketplaces": ["amazon", "walmart"], "change_detection_baseline_key": "daily_chairs" } ``` → 3 snapshots = **$0.12/day**. Each snapshot carries `changes.price_change_flags` vs. yesterday's run. #### 4. Brand portfolio (full SKU sweep) See `examples/example6_brand_monitoring.json` — 5 SKUs × 3 marketplaces = **5 snapshots = $0.20/run**. #### 5. MAP enforcement (price-floor watch) See `examples/example7_map_enforcement.json` — every `sites[].price` below your floor is a violation. Pair with Apify's webhook integration to alert legal. #### 6. AI agent quick comparison via MCP ```json { "mode": "product_list", "products": [{"label": "user_question_target", "asin": "B08N5WRWNW"}], "marketplaces": ["amazon", "ebay", "walmart"], "include_reviews_summary": true } ``` → The agent uses `markdown_report` directly as a reply or pulls `opportunity_insights.notes` for a TL;DR. **More:** see the 10 ready-to-run input JSONs in `examples/`. *** ### Built for | Role | What you do with it | |---|---| | **Amazon / FBA seller** | Daily check on your top 5 SKUs across Amazon + Walmart. `priceDelta` against competitors, plus opportunity notes you can paste into a Slack channel. | | **Brand manager** | MAP enforcement: detect resellers selling below your minimum price. Cross-marketplace coverage means you catch eBay-only violators that Amazon-only tools miss. | | **E-commerce ops lead** | Brand portfolio health — 25-SKU sweep once a day. Single dataset row per SKU per day for direct BI ingestion. | | **Pricing analyst** | Price-spread analysis: which marketplace is the cheapest right now, by how much, and is the spread widening or closing? | | **Dropshipper / arbitrage** | Identify cross-marketplace pricing arbitrage. Buy on the marketplace with the lowest `sites[].price`, list on the one with the highest. | | **Agency** | Run on behalf of a client portfolio. One snapshot per client SKU; reports auto-derive from `markdown_report`. | | **AI agent / MCP tool builder** | Plug into Claude Desktop / Cursor / any MCP client. The fixed output shape + stamped event name mean agents discover and call it without prompting acrobatics. | | **BI / data team** | Pipe snapshots into Snowflake/BigQuery. Each record has stable `group_key`, `request_context.finished_at`, and JSON-friendly nested shape. | *** ### Typical costs (worked examples) | Scenario | Snapshots | Cost per run | Cadence | Monthly cost | |---|---|---|---|---| | 1 product, 1 marketplace | 1 | $0.04 | Daily | **~$1.20/mo** | | 5 products, 3 marketplaces (brand portfolio) | 5 | $0.20 | Daily | **~$6/mo** | | 25 products (max), 3 marketplaces | 25 | $1.00 | Daily | **~$30/mo** | | 10 competitor ASINs hourly during Black Friday week | 10 | $0.40 | Hourly × 7 days | **~$67/week** | | Failed validation / Amazon block (`candidates_only`) | 0 | **$0.00** | — | $0.00 | **Compare:** dedicated price-tracking SaaS (Keepa, Prisync, etc.) typically charge $19–$99/month per *tracked product*. At 25 products that's $475–$2,475/month. PricePulse AI gives you a raw cross-marketplace data feed for **$30/month** at the same volume — you keep your data, you control the cadence, you own the analysis layer. *** ### How it works ```mermaid flowchart LR A[products and/or URLs
+ marketplaces] --> B[Pydantic input validation
bound lists, dedupe, mode rules] B --> C[Per-host robots.txt + rate limit
identifying User-Agent] C --> D[Parallel marketplace fetch
httpx + BeautifulSoup] D --> E[Normalize each site
5-anchor extraction confidence] E --> F[Aggregate metrics
min/avg/max, spread, blended rating] F --> G{baseline key?} G -->|yes| H[Diff vs. stored baseline
price/availability/rank flags] G -->|no| I[skip] H --> J[Opportunity insights
rule-based notes] I --> J J --> K{LLM enrichment?} K -->|anthropic + key| L[Claude Haiku
review summary] K -->|none| M[Rule-based summary] L --> N[Stamp billing fields
chargeable_event_count, paid_event_name] M --> N N --> O[Push chargeable records to dataset
Always set OUTPUT key] O --> P[(JSON + markdown + one-pager)] ``` Five-step short version: 1. **Validate** input against a strict Pydantic schema — bail out cleanly on bad input, never charge for invalid runs. 2. **Fetch** the relevant marketplace pages concurrently. `httpx` + `BeautifulSoup`, polite per-host rate limit (0.6s minimum interval), `robots.txt` honoured. 3. **Normalize** each page into the canonical `SiteMetrics` shape. Per-site `extraction_confidence` = (anchors parsed) / 5. 4. **Aggregate + analyze**: compute cross-site stats, diff against your stored baseline (if any), derive reviews summary + opportunity insights. 5. **Stamp + push**: chargeable records (`output_status.code in {ok, partial}`) land in the dataset; the full payload always lands in `OUTPUT` for observability — even when nothing was chargeable. *** ### Sample output (truncated for readability) ```json { "label": "my_main_chair", "group_key": "my_main_chair", "core_profile": { "canonical_title": "ErgoPlus Ergonomic Office Chair", "canonical_brand": "ErgoPlus", "category": "Office Products > Chairs", "image_url": "https://m.media-amazon.com/images/I/example.jpg" }, "sites": [ { "marketplace": "amazon", "url": "https://www.amazon.com/dp/B08N5WRWNW", "currency": "USD", "price": 199.99, "list_price": 249.99, "is_on_sale": true, "availability": "in_stock", "buy_box_seller_type": "amazon", "rating": 4.5, "review_count": 1243, "bestseller_rank": 12, "extraction_confidence": 0.92 }, { "marketplace": "walmart", "url": "https://www.walmart.com/ip/123456789", "currency": "USD", "price": 189.00, "list_price": 219.00, "is_on_sale": true, "availability": "in_stock", "rating": 4.3, "review_count": 578, "extraction_confidence": 0.85 } ], "aggregated_metrics": { "min_price": 189.0, "max_price": 199.99, "avg_price": 194.5, "price_spread_pct": 5.8, "avg_rating": 4.4, "total_review_count": 1821, "marketplace_count": 2 }, "changes": { "price_change_flags": [ {"marketplace": "amazon", "direction": "decrease", "absolute": -20.0, "relative_pct": -9.1, "significant": true} ], "baseline_age_days": 2 }, "reviews_summary": { "summary_text": "Average rating across 2 marketplaces is 4.4 over 1,821 reviews. Recurring positives: comfort, support. Recurring concerns: armrests.", "top_positive_themes": ["comfort", "support"], "top_negative_themes": ["armrests"], "enrichment_source": "rule_based" }, "opportunity_insights": { "positioning": "mid_price_premium_quality", "notes": [ "Walmart currently has the lowest listed price (USD 189.00).", "On sale on amazon, walmart — check timing.", "Cross-marketplace price spread is 5.8% — possible arbitrage signal." ] }, "output_status": {"code": "ok"}, "confidence": {"overall": 0.88, "discovery": 1.0, "extraction": 0.88, "reviews": 0.7, "insights": 0.85}, "chargeable_event_count": 1, "paid_event_name": "product_intel_snapshot", "markdown_report": "> **Disclaimer.** ...\n\n## ErgoPlus Ergonomic Office Chair\n...", "one_pager_text": "PRODUCT INTEL — ErgoPlus Ergonomic Office Chair\n..." } ``` The `markdown_report` and `one_pager_text` are derived from the JSON; embed them straight into Slack, Notion, or an LLM prompt. *** ### How to call it #### From the Apify console (no code) 1. Open the actor page → **Try for free**. 2. Paste ASINs / URLs into `products` in the input form. 3. Pick `marketplaces` (defaults to `["amazon"]`). 4. **Save & Start**. Each input product becomes one dataset record. #### From an MCP-enabled LLM (Claude Desktop, Cursor, etc.) The actor's input schema, output shape, and tool description are written for MCP auto-discovery. Sample agent prompt: > "Use PricePulse AI to compare my product `B08N5WRWNW` against competitors `B09ZZZ9999` and `B07YYY0000` on Amazon and Walmart. Tell me where I'm being undercut and by how much." #### Programmatically — Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ["APIFY_TOKEN"]) run = client.actor("entranced_gelato/price-pulse-ai").call(run_input={ "mode": "product_list", "products": [ {"label": "my_chair", "asin": "B08N5WRWNW"}, {"label": "competitor_A", "asin": "B09ZZZ9999"}, ], "marketplaces": ["amazon", "walmart"], "include_reviews_summary": True, }) for snap in client.dataset(run["defaultDatasetId"]).iterate_items(): print(f"{snap['label']}: min ${snap['aggregated_metrics']['min_price']:.2f} " f"across {snap['aggregated_metrics']['marketplace_count']} sites") for note in snap["opportunity_insights"]["notes"]: print(f" - {note}") ``` #### Programmatically — Node.js / TypeScript ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('entranced_gelato/price-pulse-ai').call({ mode: 'product_list', products: [ { label: 'my_chair', asin: 'B08N5WRWNW' }, { label: 'competitor_A', asin: 'B09ZZZ9999' }, ], marketplaces: ['amazon', 'walmart'], }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); const undercut = items.filter(s => s.changes?.price_change_flags?.some(f => f.direction === 'decrease' && f.significant) ); console.log(`${undercut.length} product(s) saw a significant price decrease since baseline.`); ``` #### Programmatically — curl ```bash curl -X POST -H "Content-Type: application/json" \ -d '{"mode":"product_list","products":[{"label":"my_chair","asin":"B08N5WRWNW"}],"marketplaces":["amazon","walmart"]}' \ "https://api.apify.com/v2/acts/entranced_gelato~price-pulse-ai/run-sync-get-dataset-items?token=$APIFY_TOKEN" ``` #### Scheduling for time-series Pair with [Apify Scheduler](https://docs.apify.com/platform/schedules) to run hourly or daily. Each snapshot stamps `request_context.finished_at`, so the dataset becomes a price-history database queryable via the [Apify dataset API](https://docs.apify.com/api/v2#tag/Datasets): ```bash ## Pull last 24h of my-chair snapshots curl "https://api.apify.com/v2/datasets//items?clean=true&desc=true&limit=24" ``` *** ### Input reference | Field | Type | Default | What it does | |---|---|---|---| | `mode` | enum | `"product_list"` | Pick `product_list` (v1) for explicit ASIN/URL lists; `keyword_research` is scaffolded for v1.1 and gated in v1.0. | | `products` | array of `{label, asin, urls}` | `[]` | One entry per group to track. `asin` OR at least one `urls[]` required per entry. `label` is a stable key for baseline diffing. | | `marketplaces` | array | `["amazon"]` | Subset of `["amazon", "ebay", "walmart"]`. Bundled into the same snapshot — adding sites does NOT add cost. | | `include_reviews_summary` | bool | `true` | Attach a `reviews_summary` block (themes + rating distribution). | | `include_history` | bool | `false` | Attach a recent 30-day history block if prior runs stored in KV. | | `change_detection_baseline_key` | string | `null` | KV key for diffing — first run writes the baseline; later runs diff against it and overwrite. | | `user_notes` | string | `null` | Free-form context, echoed back in `request_context`. Useful for tagging runs. | | `enrichment_model` | enum | `"none"` | `"none"` (rule-based) or `"anthropic"` (Claude Haiku). `anthropic` falls back to rule-based on any LLM failure. | | `anthropic_api_key` | string (secret) | — | Required when `enrichment_model = "anthropic"`. Stored as Apify secret input, never echoed. | | `max_products_per_marketplace` | int | `20` | Cap for `keyword_research` mode only (1–100). Ignored in `product_list`. | | `keyword` | string | — | Used by `keyword_research` mode (gated in v1.0). | *** ### Output reference | Field | Description | |---|---| | `request_context` | Echo of input + `started_at` / `finished_at`. | | `label`, `group_key` | Human label + stable key for baseline lookups. | | `query_inputs` | `{asin, input_urls, keyword, resolved_marketplaces}`. | | `core_profile` | `{canonical_title, canonical_brand, category, image_url}` — unified across sites. | | `sites[]` | Per-marketplace normalized metrics + per-site `extraction_confidence`. | | `aggregated_metrics` | `{min_price, max_price, avg_price, price_spread_pct, avg_rating, total_review_count, marketplace_count}`. | | `changes` | `{price_change_flags[], availability_changes[], rank_changes[], baseline_age_days}` vs. baseline. | | `reviews_summary` | `{summary_text, top_positive_themes, top_negative_themes, rating_distribution, enrichment_source}`. | | `opportunity_insights` | `{positioning, notes[]}` — rule-based, 1–5 short notes. | | `confidence` | `{overall, discovery, extraction, reviews, insights}` in \[0, 1]. | | `sources[]` | Every URL fetched + status. Citation trail. | | `risk_flags[]` | Data-quality warnings (`info` / `warn` / `error`). | | `output_status` | `{code, reason}` — drives billing (`ok`/`partial` charged; `candidates_only`/`failed` not). | | `disclaimer` | Legal disclaimer; rendered atop every derived format. | | `chargeable_event_count`, `paid_event_name` | Billing transparency. | | `markdown_report`, `one_pager_text` | Embed-ready derived formats. | #### Trust contract — what this actor will / won't do - **Never fabricates** prices, ratings, review counts, or stock state. If a field can't be parsed, it is `null`. - **Always cites** every URL it fetched in `sources[]`. - **Distinguishes** rule-based vs. LLM-derived enrichment via `reviews_summary.enrichment_source`. - **Honors** `robots.txt` for every host; surfaces blocks as `risk_flag` entries. - **Identifies itself** with a clear `User-Agent`; **no spoofing**; per-host minimum interval of 0.6s. - **Returns `candidates_only`** (non-chargeable) rather than guessing when nothing resolves. *** ### Pricing **$0.04 per `product_intel_snapshot`.** One snapshot = one fully processed product group, regardless of how many marketplaces you queried. - Non-chargeable runs (`candidates_only`, `failed`, validation errors) push nothing to the dataset. - 50-result free trial for new users. - Plus standard Apify platform compute & proxy (typically a fraction of a cent per run; paid by you to Apify). *** ### FAQ **Q: I asked for 3 marketplaces — why is it only 1 snapshot?** A: A snapshot is one record per *logical product group*, not per marketplace. We bundle all marketplaces for a given product into one snapshot. Charge is **$0.04 regardless of marketplace count**. **Q: My run returned `candidates_only` for an Amazon ASIN. Am I billed?** A: No. Amazon serves bot-detection pages to non-residential traffic and that fraction of runs can't be parsed. We mark them `candidates_only` and **don't push to the dataset**, so you're not charged. **Q: How do I track changes over time?** A: Pass any string as `change_detection_baseline_key`. First run writes the baseline; subsequent runs read it, compute price/availability/rank deltas, then overwrite with the new state. **Q: Can I use Claude Haiku for richer review summaries?** A: Yes — set `enrichment_model = "anthropic"` and supply `anthropic_api_key` (it's stored as an Apify secret, never echoed in output). Falls back to rule-based on any LLM failure. **Q: Does this work for Amazon UK / .de / .co.jp?** A: v1 targets `amazon.com` selectors. Other locales accept URLs as inputs but may have partial extraction. Full locale support is on the v1.2 roadmap. **Q: Does this scrape full customer reviews?** A: Not in v1. We compute themes from rating distributions and (with LLM enrichment) a small sample of public review snippets. No reviewer names or PII retained. For full review-text extraction, use a dedicated reviews scraper. **Q: Is keyword research available?** A: It's in the input schema but **gated in v1.0** to avoid surprise bills while per-marketplace SERP scrapers are battle-tested. Runs in this mode return `failed` with a clear message. Planned for v1.1. **Q: Can I run 1,000 products in one run?** A: No — capped at 25 product groups per run for reliability and to keep your bill predictable. For larger universes, run multiple actor calls (each $0.04 × N). **Q: How accurate is the price field?** A: Prices come from server-rendered HTML selectors and JSON-LD blocks (eBay, Walmart) or Amazon-specific selectors. Currency derives from the listing or symbol. Sale price → `price`, list price → `list_price` when both present. Per-site `extraction_confidence` shows how many of the 5 anchor fields parsed; below 0.5 you should treat the row as unreliable. **Q: Does it support webhook alerts?** A: Not natively in v1, but pair with Apify's [generic webhook integration](https://docs.apify.com/platform/integrations/webhooks) — fire on every run, your endpoint reads `changes.price_change_flags[].significant` to decide whether to alert. **Q: Is this legal?** A: This actor reads HTML that any anonymous web visitor can see; it honours `robots.txt` and uses an identifying User-Agent. **You** are responsible for ensuring your use complies with each marketplace's Terms of Service and applicable law. Don't redistribute the marketplaces' product images, descriptions, or reviews beyond what your usage rights allow. See `TERMS.md` for the full Terms of Use. *** ### Limitations - JavaScript-rendered pages (rare on Amazon/eBay/Walmart product pages; common on niche storefronts) → not supported in v1. - Amazon's anti-bot serves CAPTCHAs to a portion of anonymous requests → mitigated by `risk_flags` + non-chargeable `candidates_only`, but the failure rate is non-zero. - `keyword_research` mode is gated in v1.0 (see FAQ). - 25 product groups max per run. *** ### Changelog - **0.2.0** (2026-05-22) — Webhook alerts, JSON-LD universal fallback, `vs_reference`, `dry_run`, Apify Residential proxy, Amazon retry/locale, variants + images, `keyword_research` un-gated. 165 tests. - **0.1.0** (2026-05-22) — Initial release with cross-marketplace bundle, change detection, opportunity insights. 94 tests. ### Related work Looking for something more specific? These other actors in the same broader space may be a better fit: - **Single-marketplace, max-volume scraping** at $0.005/row — search "Amazon product scraper" / "Walmart product scraper" on the Apify Store. - **Full review-text extraction** with author + helpful votes — search "Amazon reviews scraper". - **Shopify / WooCommerce / Etsy / niche storefront scraping** — search "Shopify scraper". - **Generic JSON-LD scraping of any storefront** — search "ecommerce JSON-LD scraper". PricePulse AI complements these — it's the **opinionated aggregation + intelligence layer** on top of single-source row dumps. *** ### For developers #### Architecture ``` .actor/ ## Apify metadata + input schema src/ ## Production code marketplaces/ ## One module per marketplace (amazon, ebay, walmart) models.py ## Input + output Pydantic models — the spec utils.py ## HTTP, parsing, rate limit helpers robots.py ## robots.txt cache normalizer.py ## cross-marketplace aggregates + profile merge reviews.py ## rule-based summary + optional LLM enrichment insights.py ## rule-based opportunity insights changes.py ## baseline diff computation llm.py ## Anthropic enrichment helper assembler.py ## canonical FinalOutput builder main.py ## Actor entrypoint with top-level exception handler ``` #### Confidence math ``` overall = 0.3·discovery + 0.4·extraction + 0.1·reviews + 0.2·insights ``` - `discovery` = resolved\_marketplaces / requested\_marketplaces - `extraction` = mean of per-site extraction\_confidence (anchors\_parsed / 5) - `reviews` = 0 / 0.7 (rule-based) / 0.9 (Anthropic) - `insights` = 0 / 0.5 (1 site) / 0.85 (≥2 sites) #### Run locally ```bash pip install -r requirements-dev.txt APIFY_LOCAL_STORAGE_DIR=./storage python main.py < sample_input.json ``` #### Tests ```bash pytest -q ## 94 tests, ~0.3s ``` #### Extending — add a marketplace Implement `src/marketplaces/.py` with the same `fetch_(...) -> MarketplaceResult` signature, register it in `FETCHERS` (in `src/extraction.py`), add a `tests/test_.py`. The assembler picks up new marketplaces automatically. *** ### Terms of Use (summary) By using this actor you agree to (a) verify all output against the cited source URLs, (b) comply with the Terms of Service of each marketplace you query, and (c) accept that output is provided **AS IS**, with the Operator's aggregate liability capped at the greater of 12 months of fees paid or USD 100. Marketplace and brand names are used nominatively; no affiliation is implied. The actor does not retain your inputs or outputs outside the run. See **TERMS.md** for the complete text. # Actor input Schema ## `mode` (type: `string`): How to find products. 'product\_list' tracks the ASINs/URLs you supply. 'keyword\_research' discovers the top-N products per marketplace for a search term (strict cap via max\_products\_per\_marketplace). ## `products` (type: `array`): One entry per logical product group. Each entry needs either an ASIN or at least one URL on a supported marketplace OR any storefront with Schema.org Product JSON-LD. 'label' is your stable grouping key — pick something memorable like 'my\_main\_chair'. Max 25 entries per run. ## `marketplaces` (type: `array`): Which dedicated marketplaces to query. Subset of \['amazon', 'ebay', 'walmart']. All bundled into ONE snapshot — pay $0.04 once whether you query one site or all three. Any URL on a non-listed host (Target, Best Buy, Etsy, Shopify, etc.) falls through to the JSON-LD universal parser automatically. ## `include_reviews_summary` (type: `boolean`): Attach a reviews\_summary block per product: themes + rating distribution. Rule-based by default (free, deterministic). Set enrichment\_model='anthropic' for LLM-quality. ## `include_history` (type: `boolean`): If true AND prior runs stored data in the KV store, attach a 30-day history block. ## `change_detection_baseline_key` (type: `string`): Any string — first run writes a baseline; later runs with the same key diff against it and overwrite. Use one key per tracking cadence (e.g., 'daily\_chairs', 'hourly\_bf2026'). ## `reference_label` (type: `string`): v0.2: when set, the product whose label/ASIN matches becomes the reference. Every OTHER snapshot gets a vs\_reference block with price\_delta + is\_undercut vs. the reference. Useful for 'how do my competitors stack up against my product' questions. ## `alert_webhook_url` (type: `string`): v0.2: when a snapshot's changes.price\_change\_flags contains a flag with abs(relative\_pct) >= alert\_undercut\_pct AND significant=true, POST to this URL. Each successful POST is one chargeable webhook\_alert\_dispatched event at $0.005. Use HTTPS endpoints; query-string secrets are redacted from the snapshot record. ## `alert_undercut_pct` (type: `integer`): Minimum absolute relative price-change (in %) that fires an alert. Default 5. Higher values = fewer, more important alerts. ## `use_apify_proxy` (type: `boolean`): v0.2: dramatically reduces Amazon CAPTCHA rate. Proxy bandwidth is billed by Apify to YOUR account (not bundled into this Actor's price). Recommended for daily/hourly runs on Amazon. ## `dry_run` (type: `boolean`): v0.2: build snapshots, write them to OUTPUT, but DO NOT push to the dataset and DO NOT charge. Lets you preview the output shape and verify the schema before committing to a paid run. ## `amazon_locale` (type: `string`): v0.2: which amazon. host to use when only an ASIN (not a full URL) is provided. URLs you pass directly always override this. ## `user_notes` (type: `string`): Any context you want preserved in request\_context. Useful for tagging runs in BI dashboards. ## `enrichment_model` (type: `string`): 'none' (default) = rule-based, no extra cost. 'anthropic' = call Claude Haiku for higher-quality themes (requires anthropic\_api\_key). Falls back to rule-based on any LLM failure. ## `anthropic_api_key` (type: `string`): Your Anthropic API key. Stored as a secret Apify input (never echoed in output, never logged). Get one at https://console.anthropic.com. ## `max_products_per_marketplace` (type: `integer`): v0.2: cap how many products keyword\_research discovers per marketplace. Default 10, hard cap 50. Total products in the run is also bounded at 25 (global cap). ## `keyword` (type: `string`): Search term to discover top products. Used when mode='keyword\_research'. Ignored otherwise. ## Actor input object example ```json { "mode": "product_list", "products": [ { "label": "my_main_chair", "asin": "B08N5WRWNW", "urls": [] } ], "marketplaces": [ "amazon" ], "include_reviews_summary": true, "include_history": false, "change_detection_baseline_key": "", "reference_label": "", "alert_webhook_url": "", "alert_undercut_pct": 5, "use_apify_proxy": false, "dry_run": false, "amazon_locale": "us", "user_notes": "", "enrichment_model": "none", "max_products_per_marketplace": 10, "keyword": "" } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "products": [ { "label": "my_main_chair", "asin": "B08N5WRWNW", "urls": [] } ] }; // Run the Actor and wait for it to finish const run = await client.actor("entranced_gelato/price-pulse-ai").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "products": [{ "label": "my_main_chair", "asin": "B08N5WRWNW", "urls": [], }] } # Run the Actor and wait for it to finish run = client.actor("entranced_gelato/price-pulse-ai").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "products": [ { "label": "my_main_chair", "asin": "B08N5WRWNW", "urls": [] } ] }' | apify call entranced_gelato/price-pulse-ai --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=entranced_gelato/price-pulse-ai", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "PricePulse AI — Cross-Marketplace Product Intelligence", "description": "Track competitor products across Amazon, eBay, and Walmart and return AI-ready product-intelligence snapshots: cross-marketplace prices, change flags, review summaries, and opportunity insights — in one MCP-friendly call.", "version": "0.2", "x-build-id": "R8eTQFzsQYcgml4uN" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/entranced_gelato~price-pulse-ai/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-entranced_gelato-price-pulse-ai", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/entranced_gelato~price-pulse-ai/runs": { "post": { "operationId": "runs-sync-entranced_gelato-price-pulse-ai", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/entranced_gelato~price-pulse-ai/run-sync": { "post": { "operationId": "run-sync-entranced_gelato-price-pulse-ai", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "product_list", "keyword_research" ], "type": "string", "description": "How to find products. 'product_list' tracks the ASINs/URLs you supply. 'keyword_research' discovers the top-N products per marketplace for a search term (strict cap via max_products_per_marketplace).", "default": "product_list" }, "products": { "title": "Products to track", "type": "array", "description": "One entry per logical product group. Each entry needs either an ASIN or at least one URL on a supported marketplace OR any storefront with Schema.org Product JSON-LD. 'label' is your stable grouping key — pick something memorable like 'my_main_chair'. Max 25 entries per run.", "default": [] }, "marketplaces": { "title": "Marketplaces (bundled — adding sites does NOT add cost)", "uniqueItems": true, "type": "array", "description": "Which dedicated marketplaces to query. Subset of ['amazon', 'ebay', 'walmart']. All bundled into ONE snapshot — pay $0.04 once whether you query one site or all three. Any URL on a non-listed host (Target, Best Buy, Etsy, Shopify, etc.) falls through to the JSON-LD universal parser automatically.", "default": [ "amazon" ], "items": { "type": "string" } }, "include_reviews_summary": { "title": "Include reviews summary", "type": "boolean", "description": "Attach a reviews_summary block per product: themes + rating distribution. Rule-based by default (free, deterministic). Set enrichment_model='anthropic' for LLM-quality.", "default": true }, "include_history": { "title": "Include price/rank history (last 30 days)", "type": "boolean", "description": "If true AND prior runs stored data in the KV store, attach a 30-day history block.", "default": false }, "change_detection_baseline_key": { "title": "Change-detection baseline key", "type": "string", "description": "Any string — first run writes a baseline; later runs with the same key diff against it and overwrite. Use one key per tracking cadence (e.g., 'daily_chairs', 'hourly_bf2026').", "default": "" }, "reference_label": { "title": "Reference product label (for vs-reference comparisons)", "type": "string", "description": "v0.2: when set, the product whose label/ASIN matches becomes the reference. Every OTHER snapshot gets a vs_reference block with price_delta + is_undercut vs. the reference. Useful for 'how do my competitors stack up against my product' questions.", "default": "" }, "alert_webhook_url": { "title": "Webhook URL for significant price-change alerts", "type": "string", "description": "v0.2: when a snapshot's changes.price_change_flags contains a flag with abs(relative_pct) >= alert_undercut_pct AND significant=true, POST to this URL. Each successful POST is one chargeable webhook_alert_dispatched event at $0.005. Use HTTPS endpoints; query-string secrets are redacted from the snapshot record.", "default": "" }, "alert_undercut_pct": { "title": "Webhook trigger threshold (% price drop)", "minimum": 0, "maximum": 99, "type": "integer", "description": "Minimum absolute relative price-change (in %) that fires an alert. Default 5. Higher values = fewer, more important alerts.", "default": 5 }, "use_apify_proxy": { "title": "Route fetches through Apify Residential proxy", "type": "boolean", "description": "v0.2: dramatically reduces Amazon CAPTCHA rate. Proxy bandwidth is billed by Apify to YOUR account (not bundled into this Actor's price). Recommended for daily/hourly runs on Amazon.", "default": false }, "dry_run": { "title": "Dry run (preview without charging)", "type": "boolean", "description": "v0.2: build snapshots, write them to OUTPUT, but DO NOT push to the dataset and DO NOT charge. Lets you preview the output shape and verify the schema before committing to a paid run.", "default": false }, "amazon_locale": { "title": "Amazon locale (for ASIN-derived URLs)", "enum": [ "us", "uk", "de", "fr", "jp", "in", "ca", "au" ], "type": "string", "description": "v0.2: which amazon. host to use when only an ASIN (not a full URL) is provided. URLs you pass directly always override this.", "default": "us" }, "user_notes": { "title": "Free-form notes (echoed in output for traceability)", "type": "string", "description": "Any context you want preserved in request_context. Useful for tagging runs in BI dashboards.", "default": "" }, "enrichment_model": { "title": "Optional LLM enrichment for review summaries", "enum": [ "none", "anthropic" ], "type": "string", "description": "'none' (default) = rule-based, no extra cost. 'anthropic' = call Claude Haiku for higher-quality themes (requires anthropic_api_key). Falls back to rule-based on any LLM failure.", "default": "none" }, "anthropic_api_key": { "title": "Anthropic API key (only used if enrichment_model='anthropic')", "type": "string", "description": "Your Anthropic API key. Stored as a secret Apify input (never echoed in output, never logged). Get one at https://console.anthropic.com." }, "max_products_per_marketplace": { "title": "Max products per marketplace (keyword_research mode)", "minimum": 1, "maximum": 50, "type": "integer", "description": "v0.2: cap how many products keyword_research discovers per marketplace. Default 10, hard cap 50. Total products in the run is also bounded at 25 (global cap).", "default": 10 }, "keyword": { "title": "Search keyword (keyword_research mode)", "type": "string", "description": "Search term to discover top products. Used when mode='keyword_research'. Ignored otherwise.", "default": "" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```