# 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, 16.7% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## 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 ## Retail Location Intelligence Bundle Monitor store footprints, openings, closures, competitor locations, and expansion signals in one scored workflow. ### Who this is for - Retail strategy teams - Location intelligence teams - Real estate analysts ### What it helps you do - Research store footprints by brand and market - Collect location and expansion signals - Prepare scored records for dashboards ### Inputs you can use - Brand, city, country, or manual locations - Discovery settings - Maximum records ### Data you get - brand - location - address - city - country - signal type - source URL - confidence score ### How to get better results - Start with a narrow, specific query or a small list of source URLs. - Use realistic limits for the first run, then increase the volume once the output looks right. - Keep source URLs, dates, and location context when you need repeatable market monitoring. - Review a few sample records before connecting the dataset to a larger workflow. ### Notes - Results depend on what the public source exposes at run time. - Some pages may hide, delay, rename, or remove fields, so individual records can have partial data. - Use the built-in output table to inspect results before exporting to spreadsheets, dashboards, or automation tools. ### 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 '' with your token const client = new ApifyClient({ 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 '' with your token. client = ApifyClient("") # 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 " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Retail Location Intelligence Bundle", "description": "Monitor store footprints, store locator scraper outputs, openings, closures, competitor locations, and expansion signals in one scored AI-ready retail location dataset.", "version": "0.1", "x-build-id": "ObQp2ytIluekP0ill" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/runtime~retail-location-intelligence-bundle/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-runtime-retail-location-intelligence-bundle", "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/runtime~retail-location-intelligence-bundle/runs": { "post": { "operationId": "runs-sync-runtime-retail-location-intelligence-bundle", "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/runtime~retail-location-intelligence-bundle/run-sync": { "post": { "operationId": "run-sync-runtime-retail-location-intelligence-bundle", "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", "properties": { "mockMode": { "title": "Mock mode", "type": "boolean", "description": "Return deterministic sample records for smoke tests without external requests.", "default": false }, "workflow": { "title": "Workflow", "enum": [ "store-footprint-watch", "competitor-location-watch", "retail-expansion-monitor", "store-locator-normalizer" ], "type": "string", "description": "Monitoring workflow to run.", "default": "store-footprint-watch" }, "brand": { "title": "Brand", "type": "string", "description": "Primary brand to monitor." }, "brands": { "title": "Brands", "type": "array", "description": "Brands to monitor.", "items": { "type": "string" } }, "competitor": { "title": "Competitor", "type": "string", "description": "Primary competitor to monitor." }, "competitors": { "title": "Competitors", "type": "array", "description": "Competitors to monitor.", "items": { "type": "string" } }, "market": { "title": "Market", "type": "string", "description": "Primary market, city, region, or country to monitor.", "default": "Paris" }, "markets": { "title": "Markets", "type": "array", "description": "Markets, cities, regions, or countries to monitor.", "items": { "type": "string" } }, "city": { "title": "City", "type": "string", "description": "Default city for manual records." }, "country": { "title": "Country", "type": "string", "description": "Default country for manual records." }, "includeManualLocations": { "title": "Include manual locations", "type": "boolean", "description": "Normalize manualLocations and sourceItems when provided.", "default": true }, "manualLocations": { "title": "Manual locations", "type": "array", "description": "Known locations, store locator rows, or retail announcements to normalize.", "items": { "type": "object", "properties": { "brand": { "title": "Brand", "type": "string", "description": "Brand name." }, "competitor": { "title": "Competitor", "type": "string", "description": "Competitor name." }, "locationName": { "title": "Location name", "type": "string", "description": "Store or location name." }, "address": { "title": "Address", "type": "string", "description": "Street address." }, "city": { "title": "City", "type": "string", "description": "City." }, "region": { "title": "Region", "type": "string", "description": "Region or state." }, "country": { "title": "Country", "type": "string", "description": "Country." }, "postalCode": { "title": "Postal code", "type": "string", "description": "Postal code." }, "latitude": { "title": "Latitude", "type": "number", "description": "Latitude." }, "longitude": { "title": "Longitude", "type": "number", "description": "Longitude." }, "url": { "title": "URL", "type": "string", "description": "Store or source URL." }, "phone": { "title": "Phone", "type": "string", "description": "Phone number." }, "openingHours": { "title": "Opening hours", "type": "string", "description": "Opening hours." }, "summary": { "title": "Summary", "type": "string", "description": "Source summary or note." }, "publishedAt": { "title": "Published at", "type": "string", "description": "Publication or observation date." }, "signalType": { "title": "Signal type", "type": "string", "description": "Optional signal type override." } } } }, "sourceItems": { "title": "Source items", "type": "array", "description": "Alias for manualLocations, useful for bundle pipelines.", "items": { "type": "object" } }, "includeWebDiscovery": { "title": "Include web discovery", "type": "boolean", "description": "Run direct web search for store locators, openings, closures, and expansion signals.", "default": true }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Optional exact search queries. Generated queries are used when this is empty.", "items": { "type": "string" } }, "searchProviders": { "title": "Search providers", "type": "array", "description": "Search providers to use for direct discovery.", "items": { "type": "string", "enum": [ "duckduckgo", "brave" ] }, "default": [ "duckduckgo" ] }, "searchMode": { "title": "Search mode", "enum": [ "default", "news" ], "type": "string", "description": "DuckDuckGo search mode.", "default": "default" }, "braveApiKey": { "title": "Brave Search API key", "type": "string", "description": "Optional Brave Search API key. You can also set BRAVE_SEARCH_API_KEY in Apify secrets." }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum normalized records to save.", "default": 25 }, "maxWebResults": { "title": "Max web results", "minimum": 0, "maximum": 500, "type": "integer", "description": "Maximum web discovery results to normalize.", "default": 25 }, "maxWebQueries": { "title": "Max web queries", "minimum": 0, "maximum": 100, "type": "integer", "description": "Maximum generated or provided web queries to run.", "default": 10 }, "requestTimeoutSecs": { "title": "Request timeout seconds", "minimum": 5, "maximum": 120, "type": "integer", "description": "Timeout for each external discovery request.", "default": 20 }, "useApifyProxy": { "title": "Use Apify Proxy", "type": "boolean", "description": "Use Apify Proxy for web discovery requests.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Advanced Apify proxy configuration." }, "failOnNoResults": { "title": "Fail on no results", "type": "boolean", "description": "Fail the run when no records are produced.", "default": true } } }, "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 } } } } } } } } } } ```