Dealer / Distributor Locator Extractor

Turn brand store-locator pages into structured dealer lists — name, address, phone, website, coordinates.

Standalone Apify actor for channel mapping, CEE/EU sales coverage, and distributor shortlists. Pairs well with the Google Maps CEE Supplier Shortlist Builder when you already know the brand locator URL.

Optional enrichment: pipe dealer website URLs into the sibling Website Intelligence + Contact Extractor for emails, tech stack, and EU compliance flags.

What it does

• Fetches one or more store / dealer locator pages (HTTP first, Playwright + residential proxy fallback).
• Discovers concrete store/dealer detail links on the locator.
• Optionally enriches each detail page for address, phone, and geo signals.
• Parses JSON-LD (Store / LocalBusiness), embedded physicalStore blobs (IKEA-style), and common dealer JSON shapes.
• Optional country filter (ISO alpha-2) when country metadata exists.
• Returns structured JSON/CSV/Excel ready for CRM / n8n / Make / Zapier.
• Built for n8n, Make, Zapier, and vibe-coder agent workflows.

Who it's for

1. Sales / channel teams mapping brand dealer networks by country.
2. Market researchers comparing retail footprint across markets.
3. Agencies building distributor shortlists for clients.
4. Vibe coders wiring locator → CRM / n8n / Make / Zapier / Apify.
5. Procurement-adjacent teams checking coverage density before outreach.

What this actor is — and is not

This actor helps you extract public locator page signals. It does not verify franchise agreements, stock levels, authorized-partner status, or exclusive territory rights.

Use the output for:

• channel / coverage maps
• distributor shortlist preparation
• outreach prioritization

Do not treat it as an official partner directory or the sole basis for channel contracts.

What data you get

Field	Description
name	Dealer / store display name
address, city, postalCode, countryCode	Place fields when present
phone, website	Contact / store page URL
latitude, longitude	Coordinates when embedded in the page
tier	Type hint (store, JSON-LD @type, etc.)
sourceLocatorUrl	Locator URL that produced this row
scrapedAt	ISO timestamp
error	Set when the locator itself failed

How to use it

1. Configure input — locator URL(s), optional country code, max dealers, proxy.
2. Run on Apify cloud (recommended) or locally with apify run.
3. Download dataset as JSON, CSV, or Excel from the run page.

Input presets

IKEA Hungary stores (Store / QA example)

{
  "locatorUrls": ["https://www.ikea.com/hu/hu/stores/"],
  "countryCode": "HU",
  "maxDealers": 5,
  "enrichDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Store input prefill uses this small cap so Apify automated QA finishes within 5 minutes. For real channel maps, raise maxDealers (e.g. 50–200).

Published Store example: IKEA Hungary store locator — dealer addresses.

Production run (raise the cap)

{
  "locatorUrls": ["https://www.example-brand.com/dealers/"],
  "countryCode": "DE",
  "maxDealers": 100,
  "enrichDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Multi-country brand (separate runs)

{
  "locatorUrls": ["https://www.example-brand.com/hu/stores/"],
  "countryCode": "HU",
  "maxDealers": 50,
  "enrichDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Prefer one country locator URL per run when the brand splits markets by path (/hu/, /de/). Use countryCode to filter when metadata is present.

Output example

{
  "name": "Örs vezér téri IKEA",
  "address": "Örs vezér tere 22, 1148, Budapest",
  "city": "Budapest",
  "postalCode": "1148",
  "countryCode": "HU",
  "phone": null,
  "website": "https://www.ikea.com/hu/hu/stores/budapest/",
  "latitude": null,
  "longitude": null,
  "tier": "store",
  "sourceLocatorUrl": "https://www.ikea.com/hu/hu/stores/",
  "scrapedAt": "2026-07-20T08:30:38.665Z",
  "error": null
}

Proxy and blocked brands

Feature	Support
Apify Proxy RESIDENTIAL	Recommended default — many brands block datacenter IPs
Browser fallback	Used when HTTP returns 4xx/5xx or a thin body
Usable 5xx shells	Some CDNs (e.g. IKEA) return HTTP 500 with usable HTML; the actor still continues

If a run saves zero rows, confirm Proxy is Apify Proxy + RESIDENTIAL, keep maxDealers modest for demos, and check the Dataset error field. The Console message “URL isn’t accessible” after a finished run usually refers to the temporary container URL — check the Dataset instead.

Tips to avoid Store QA timeouts

• Keep Store prefill / public-task demos at maxDealers: 5.
• Prefer a single trendy locator over many brands in QA.
• Raise maxDealers only for paid production runs.

Secrets and local development

• Never commit apify/dealer-distributor-locator/.env — it is listed in .gitignore.
• apify push excludes .env via .gitignore and .actorignore.
• Docker builds exclude .env via .dockerignore.
• On Apify cloud, customers configure Proxy via input — not from your local .env.
• For local runs only, copy .env.example → .env and add APIFY_TOKEN if you call the platform.
• Only .env.example (placeholders, no real keys) is in git.

FAQ

How is this different from a Google Maps scraper?
This actor reads brand store / dealer locator pages you already know. Maps discovers unknown places by search term; this actor expands a known brand’s published network.

Does it work outside CEE?
Yes. Marketing ICP is CEE/Europe; any public locator URL worldwide can work if the page exposes parseable store data.

Why do I see HTTP 500 in the logs for IKEA?
Some brands return 500 on plain HTTP while still serving HTML. The actor tries the browser, then falls back to a usable HTTP body when needed. A successful run with saved dealers is fine.

Do I need an LLM key?
No. Extraction is deterministic (HTTP + optional browser). There is no Apify AI event fee on this actor.

How many dealers can I get per run?
Up to 500 (maxDealers). Prefill/demo stays at 5 so Store QA finishes under 5 minutes.

Local development

cd apify/dealer-distributor-locator
npm install
npm test
npm run build
npm run dry-run
# or: npx tsx src/smoke.ts "https://www.ikea.com/hu/hu/stores/" 5 HU
apify run --input-file=INPUT.smoke.json

Dry run defaults to IKEA HU with 5 dealers. Install Playwright Chromium once for local browser fallback: npx playwright install chromium.

Pricing

Pay-per-event: $3.00 per 1,000 dealer records (dealer event @ $0.003), minimum charge $0.10 per run.

Enable Pay per event + usage in Apify Console so platform compute/proxy costs are passed through to users. That keeps developer margins healthy while remaining competitive for structured location rows rather than raw HTML dumps.

Related actors (suite)

Actor	Role
Google Maps CEE Supplier Shortlist	Discover local suppliers
Website Intelligence + Contact	Enrich websites (contacts, tech, compliance)
Dealer / Distributor Locator (this Actor)	Expand brand locator pages
PDF Procurement Document Extractor	Find certs / reports / datasheets
Website Change Monitor	Watch pages for changes

Each Actor runs standalone; use them as an optional suite when chaining discovery → enrichment → monitoring.

Feedback

Open an issue on the actor’s Apify page or contact Vibe Coder's Life.