# Retail Location Intelligence Bundle (`runtime/retail-location-intelligence-bundle`) Actor

Monitor store footprints, store locator scraper outputs, openings, closures, competitor locations, and expansion signals in one scored AI-ready retail location dataset.

- **URL**: https://apify.com/runtime/retail-location-intelligence-bundle.md
- **Developed by:** [scraping automation](https://apify.com/runtime) (community)
- **Categories:** Lead generation, Business, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $70.00 / 1,000 retail location records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Location Intelligence Bundle

Monitor store footprints, openings, closures, competitor locations, and local
expansion signals in one structured retail intelligence workflow.

### What it helps you do

- Track where a brand operates stores by city, country, or market
- Compare competitors' physical retail footprint
- Collect evidence for openings, closures, flagship stores, and local expansion
- Prepare location datasets for spreadsheets, dashboards, CRM enrichment, and AI analysis

### Best for

- Retail strategy and expansion teams
- Real estate analysts
- Competitive intelligence teams
- Market research teams tracking store networks
- Automation workflows that need clean retail-location records

### Example use case

Monitor Dior locations and competitor signals in Paris.

Start with a known store or a small market sample, then expand to competitor and
web-discovery monitoring once the first dataset looks correct.

### Inputs you can use

- Brand or competitor names
- City, country, and market
- Known store locations or source URLs
- Optional discovery keywords
- Maximum number of records to keep runs predictable

### Data you get

- Brand and competitor name
- Store or location name
- Address, city, region, country, and postal code
- Phone, opening hours, and coordinates when available
- Source URL and canonical URL
- Summary of the signal
- Matched keywords
- Relevance and priority scores
- Review status for quality control
- Collection timestamp

### Dataset views

- **Locations**: clean store and address records for mapping or spreadsheets
- **Signals**: scored expansion, competitor, and footprint records
- **Evidence**: source URLs, matched keywords, and review status

### How to get better results

- Start with a specific brand and market instead of a broad worldwide query.
- Use known locations for the first run when you need a predictable sample.
- Add competitors after the base brand output has been checked.
- Keep result limits small for the first run, then increase volume gradually.
- Review source URLs and review status before using the data in reporting.

### Limitations

Public store pages can move, return partial addresses, or hide metadata. Web
discovery can also return pages that mention a brand without being an actual
store page. Always review source URLs and status fields before relying on the
dataset for business decisions.

### Support

If a run returns unexpected data, open an issue from the Actor page with the
input used, the run ID, and the result you expected.

# Actor input Schema

## `mockMode` (type: `boolean`):

Return deterministic sample records for smoke tests without external requests.

## `workflow` (type: `string`):

Monitoring workflow to run.

## `brand` (type: `string`):

Primary brand to monitor.

## `brands` (type: `array`):

Brands to monitor.

## `competitor` (type: `string`):

Primary competitor to monitor.

## `competitors` (type: `array`):

Competitors to monitor.

## `market` (type: `string`):

Primary market, city, region, or country to monitor.

## `markets` (type: `array`):

Markets, cities, regions, or countries to monitor.

## `city` (type: `string`):

Default city for manual records.

## `country` (type: `string`):

Default country for manual records.

## `includeManualLocations` (type: `boolean`):

Normalize manualLocations and sourceItems when provided.

## `manualLocations` (type: `array`):

Known locations, store locator rows, or retail announcements to normalize.

## `sourceItems` (type: `array`):

Alias for manualLocations, useful for bundle pipelines.

## `includeWebDiscovery` (type: `boolean`):

Run direct web search for store locators, openings, closures, and expansion signals.

## `searchQueries` (type: `array`):

Optional exact search queries. Generated queries are used when this is empty.

## `searchProviders` (type: `array`):

Search providers to use for direct discovery.

## `searchMode` (type: `string`):

DuckDuckGo search mode.

## `braveApiKey` (type: `string`):

Optional Brave Search API key. You can also set BRAVE\_SEARCH\_API\_KEY in Apify secrets.

## `maxResults` (type: `integer`):

Maximum normalized records to save.

## `maxWebResults` (type: `integer`):

Maximum web discovery results to normalize.

## `maxWebQueries` (type: `integer`):

Maximum generated or provided web queries to run.

## `requestTimeoutSecs` (type: `integer`):

Timeout for each external discovery request.

## `useApifyProxy` (type: `boolean`):

Use Apify Proxy for web discovery requests.

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

Advanced Apify proxy configuration.

## `failOnNoResults` (type: `boolean`):

Fail the run when no records are produced.

## Actor input object example

```json
{
  "mockMode": false,
  "workflow": "store-footprint-watch",
  "brand": "Dior",
  "market": "Paris",
  "city": "Paris",
  "country": "France",
  "includeManualLocations": true,
  "manualLocations": [
    {
      "provider": "manual-location",
      "brand": "Dior",
      "locationName": "Dior Paris 30 Montaigne",
      "address": "30 Avenue Montaigne",
      "city": "Paris",
      "country": "France",
      "url": "https://www.dior.com/fashion/stores/en_int/france/paris/30-avenue-montaigne",
      "summary": "Dior flagship location in Paris."
    }
  ],
  "includeWebDiscovery": true,
  "searchProviders": [
    "duckduckgo"
  ],
  "searchMode": "default",
  "maxResults": 25,
  "maxWebResults": 25,
  "maxWebQueries": 10,
  "requestTimeoutSecs": 20,
  "useApifyProxy": false,
  "failOnNoResults": true
}
```

# Actor output Schema

## `source` (type: `string`):

Source module

## `provider` (type: `string`):

Store locator, news, manual, or discovery provider

## `workflow` (type: `string`):

Workflow that produced the record

## `signalType` (type: `string`):

store\_location, store\_opening, store\_closure, competitor\_location, or related signal

## `brand` (type: `string`):

Monitored brand

## `competitor` (type: `string`):

Monitored competitor

## `locationName` (type: `string`):

Store or location name

## `address` (type: `string`):

Street address

## `city` (type: `string`):

City

## `region` (type: `string`):

Region or state

## `country` (type: `string`):

Country

## `postalCode` (type: `string`):

Postal code

## `latitude` (type: `string`):

Latitude when available

## `longitude` (type: `string`):

Longitude when available

## `phone` (type: `string`):

Phone number

## `openingHours` (type: `string`):

Opening hours

## `url` (type: `string`):

Primary URL

## `canonicalUrl` (type: `string`):

Canonical URL without tracking parameters

## `sourceTitle` (type: `string`):

Source page or announcement title

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

Summary, snippet, or source note

## `publishedAt` (type: `string`):

Published timestamp when available

## `relevanceScore` (type: `string`):

Completeness and relevance score from 0 to 100

## `priorityScore` (type: `string`):

Priority score including keyword matches

## `matchedKeywords` (type: `string`):

Matched monitored brands, competitors, and markets

## `reviewStatus` (type: `string`):

accepted or needs\_review

## `sourceUrl` (type: `string`):

Original source URL

## `sourceQuery` (type: `string`):

Search query that produced the record

## `sourcePosition` (type: `string`):

Position in source listing or search results

## `sourceData` (type: `string`):

Provider-specific source metadata

## `scrapedAt` (type: `string`):

Timestamp when this record was produced

# 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 = {
    "brand": "Dior",
    "market": "Paris",
    "city": "Paris",
    "country": "France",
    "manualLocations": [
        {
            "provider": "manual-location",
            "brand": "Dior",
            "locationName": "Dior Paris 30 Montaigne",
            "address": "30 Avenue Montaigne",
            "city": "Paris",
            "country": "France",
            "url": "https://www.dior.com/fashion/stores/en_int/france/paris/30-avenue-montaigne",
            "summary": "Dior flagship location in Paris."
        }
    ],
    "includeWebDiscovery": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("runtime/retail-location-intelligence-bundle").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 = {
    "brand": "Dior",
    "market": "Paris",
    "city": "Paris",
    "country": "France",
    "manualLocations": [{
            "provider": "manual-location",
            "brand": "Dior",
            "locationName": "Dior Paris 30 Montaigne",
            "address": "30 Avenue Montaigne",
            "city": "Paris",
            "country": "France",
            "url": "https://www.dior.com/fashion/stores/en_int/france/paris/30-avenue-montaigne",
            "summary": "Dior flagship location in Paris.",
        }],
    "includeWebDiscovery": False,
}

# Run the Actor and wait for it to finish
run = client.actor("runtime/retail-location-intelligence-bundle").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 '{
  "brand": "Dior",
  "market": "Paris",
  "city": "Paris",
  "country": "France",
  "manualLocations": [
    {
      "provider": "manual-location",
      "brand": "Dior",
      "locationName": "Dior Paris 30 Montaigne",
      "address": "30 Avenue Montaigne",
      "city": "Paris",
      "country": "France",
      "url": "https://www.dior.com/fashion/stores/en_int/france/paris/30-avenue-montaigne",
      "summary": "Dior flagship location in Paris."
    }
  ],
  "includeWebDiscovery": false
}' |
apify call runtime/retail-location-intelligence-bundle --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=runtime/retail-location-intelligence-bundle",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/eGdcfhK6onemNje0p/builds/Yabzenr47Jue6cAgn/openapi.json