# Retail Shelf Gap Finder (`seeb/retail-shelf-gap-finder`) Actor

Detect retail shelf gaps from ecommerce category, search, or product pages with availability, price, delivery, assortment, and reseller opportunity signals.

- **URL**: https://apify.com/seeb/retail-shelf-gap-finder.md
- **Developed by:** [Techionik](https://apify.com/seeb) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $25.00 / 1,000 shelf gaps

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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Retail Shelf Gap Finder

Detect retail shelf gaps from ecommerce category, search, or product pages with availability, price, delivery, assortment, and reseller opportunity signals.

Retail Shelf Gap Finder helps ecommerce teams, brands, and resellers spot where demand may be leaking on public shelf pages. It extracts availability gaps, missing variants, delivery limits, price signals, and competitor pressure so users can decide where to replenish, pitch, advertise, or expand assortment.

This actor is designed for focused marketplace research runs. You can give it public URLs, paste copied source text, or combine both. URL fetching is useful for public HTML pages; pasted text is useful when a site uses heavy JavaScript, login walls, CAPTCHA, or restrictive anti-bot controls that should not be bypassed.

### Who Uses It

- Ecommerce operators
- Brand managers and retail media teams
- Marketplace sellers and resellers
- Category managers
- Competitive intelligence analysts

### What It Extracts

- `retailerName` - Retailer, marketplace, or store name inferred from the source.
- `shelfUrl` - Original category, search, product, or pasted snippet source.
- `categoryOrSearchTerm` - Shelf category, query, product family, or merchandising context.
- `productOrBrand` - Product, SKU, brand, flavor, or variant connected to the gap.
- `availabilityStatus` - Stock status such as sold out, low stock, unavailable, pickup unavailable, or delivery available.
- `priceSignal` - Visible price, discount, clearance, or comparable price signal.
- `deliverySignal` - Pickup, delivery, shipping, store availability, or fulfillment signal.
- `assortmentGap` - Missing flavor, size, SKU, brand, or format opportunity.
- `shelfThreat` - Competitive or merchandising threat such as sponsored competitor slots or clearance pressure.
- `resellerOpportunity` - Plain-language action for a brand, reseller, or ecommerce operator.
- `gapPriority` - Priority based on stock, missing assortment, price, and competitive shelf pressure.
- `evidenceText` - Short shelf-specific evidence phrase from the source.

### Why This Actor Is Useful

Retail shelf pages change quickly. This actor turns shelf text into actions: replenish, pitch substitutes, watch competitor pressure, identify missing variants, and spot fulfillment gaps.

### Input

- `startUrls` - Public pages to fetch and analyze.
- `sourceTexts` - Optional pasted source snippets for pages that are blocked, login-gated, JavaScript-heavy, or easier to collect manually.
- `maxPagesPerStartUrl` - Same-domain crawl depth for each URL. Use a low value for precise runs.
- `maxConcurrency` - Parallel request count.
- `proxyConfiguration` - Optional Apify Proxy settings for public pages that rate-limit normal requests.

### Example Input

```json
{
    "startUrls": [
        {
            "url": "https://www.target.com/s?searchTerm=coffee"
        }
    ],
    "sourceTexts": [
        "Target coffee shelf shows BrewNorth Organic Dark Roast 12oz sold out online, pickup unavailable, comparable brands priced at $14.99, and only 3 organic dark roast options visible."
    ],
    "maxPagesPerStartUrl": 2,
    "maxConcurrency": 2
}
```

### Example Output

```json
{
    "retailerName": "Target",
    "shelfUrl": "pasted://retail-shelf-1",
    "categoryOrSearchTerm": "coffee shelf",
    "productOrBrand": "BrewNorth Organic Dark Roast 12oz",
    "availabilityStatus": "sold out online; pickup unavailable",
    "priceSignal": "$14.99 comparable brands",
    "deliverySignal": "pickup unavailable",
    "assortmentGap": "only 3 organic dark roast options visible",
    "shelfThreat": "competitor brands filling available shelf space",
    "resellerOpportunity": "Prioritize replenishment and advertise substitute organic dark roast SKUs.",
    "gapPriority": "high",
    "evidenceText": "BrewNorth Organic Dark Roast 12oz sold out online, pickup unavailable."
}
```

### How It Works

1. The actor normalizes every URL and pasted text item.
2. Public URLs are fetched with a browser-like user agent and a clear timeout.
3. HTML pages are converted into readable page text while scripts, styles, iframes, and hidden noise are removed.
4. The actor applies Retail Shelf Gap Finder-specific extraction rules rather than a generic page-summary template.
5. Only rows with useful actor-specific information are saved to the dataset.
6. A run summary is saved to the key-value store for quick review.

### Practical Workflows

- Monitor product availability across public retailer shelves.
- Find missing sizes, flavors, or formats for assortment planning.
- Track competitor shelf pressure and sponsored placement signals.
- Create replenishment or reseller prospecting lists.

### Reliability Notes

- Best results come from public HTML pages or pasted snippets that visibly contain the target signal.
- For JavaScript-heavy sites, paste the relevant text or use URLs that return readable HTML.
- The actor does not bypass logins, paywalls, CAPTCHA, private systems, or website restrictions.
- Some fields may be empty when the source does not contain that information.
- Use smaller crawl limits for broad portals and larger limits only for well-structured sites.

### Limitations

- This actor extracts public or user-provided visible text only.
- It is not a legal-access tool for restricted procurement portals, private retailer dashboards, closed review platforms, account-only changelogs, or internal documentation.
- Results should be reviewed before making procurement, legal, inventory, engineering, or sales decisions.

### Search Keywords

retail shelf gap finder, retail shelf gap finder, retailer name, shelf url, category or search term, product or brand, availability status, price signal, delivery signal, assortment gap, shelf threat, reseller opportunity, gap priority, evidence text

# Actor input Schema

## `startUrls` (type: `array`):

Add public category/search/product URLs or paste shelf text from ecommerce pages, marketplace listings, or merchandiser notes.

## `sourceTexts` (type: `array`):

Optional pasted snippets. Use this for blocked pages, login-gated portals you can view manually, newsletters, exported notes, or copied page sections.

## `maxPagesPerStartUrl` (type: `integer`):

How many same-domain pages to analyze from each start URL. Keep this low for focused, low-cost runs.

## `maxConcurrency` (type: `integer`):

How many pages to analyze at the same time.

## `proxyConfiguration` (type: `object`):

Optional proxy settings. Use Apify Proxy for public pages that rate-limit normal datacenter requests.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.target.com/s?searchTerm=coffee"
    },
    {
      "url": "https://www.walmart.com/search?q=coffee"
    }
  ],
  "sourceTexts": [
    "Target coffee shelf shows BrewNorth Organic Dark Roast 12oz sold out online, pickup unavailable, comparable brands priced at $14.99, and only 3 organic dark roast options visible.",
    "Walmart search page for protein bars lists FitFuel Chocolate 12-pack at $19.88, delivery tomorrow, but the vanilla flavor is out of stock and several sponsored slots are occupied by competitor brands."
  ],
  "maxPagesPerStartUrl": 3,
  "maxConcurrency": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `rawJson` (type: `string`):

No description

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://www.target.com/s?searchTerm=coffee"
        },
        {
            "url": "https://www.walmart.com/search?q=coffee"
        }
    ],
    "sourceTexts": [
        "Target coffee shelf shows BrewNorth Organic Dark Roast 12oz sold out online, pickup unavailable, comparable brands priced at $14.99, and only 3 organic dark roast options visible.",
        "Walmart search page for protein bars lists FitFuel Chocolate 12-pack at $19.88, delivery tomorrow, but the vanilla flavor is out of stock and several sponsored slots are occupied by competitor brands."
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("seeb/retail-shelf-gap-finder").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrls": [
        { "url": "https://www.target.com/s?searchTerm=coffee" },
        { "url": "https://www.walmart.com/search?q=coffee" },
    ],
    "sourceTexts": [
        "Target coffee shelf shows BrewNorth Organic Dark Roast 12oz sold out online, pickup unavailable, comparable brands priced at $14.99, and only 3 organic dark roast options visible.",
        "Walmart search page for protein bars lists FitFuel Chocolate 12-pack at $19.88, delivery tomorrow, but the vanilla flavor is out of stock and several sponsored slots are occupied by competitor brands.",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("seeb/retail-shelf-gap-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.target.com/s?searchTerm=coffee"
    },
    {
      "url": "https://www.walmart.com/search?q=coffee"
    }
  ],
  "sourceTexts": [
    "Target coffee shelf shows BrewNorth Organic Dark Roast 12oz sold out online, pickup unavailable, comparable brands priced at $14.99, and only 3 organic dark roast options visible.",
    "Walmart search page for protein bars lists FitFuel Chocolate 12-pack at $19.88, delivery tomorrow, but the vanilla flavor is out of stock and several sponsored slots are occupied by competitor brands."
  ]
}' |
apify call seeb/retail-shelf-gap-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,seeb/retail-shelf-gap-finder"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/gUEliLKIpkM1aC3iU/builds/6w1XA89XAsI84O5tN/openapi.json