Store Locator Page Extractor

Turn public store-locator pages into capped branch records with extraction provenance and locator coverage diagnostics.

What it does

• Extracts visible location, store, branch, and locator-result cards.
• Normalizes LocalBusiness, Store, Restaurant, Place, and Organization JSON-LD.
• Captures branch URL, address, phone, hours, distance, result position, and page position.
• Detects visible locator API endpoint strings when present in page markup.
• Deduplicates records and applies optional city or ZIP text filters.

Input

• startUrls, locatorUrls, sitemapUrls, or htmlInputs.
• searchLocations and searchRadiusMiles for supplied locator evidence.
• maxLocations, maxResultsPerQuery, and maxLocatorQueries.
• paginationLimit, maxBrowserPages, maxPages, and maxDepth.
• maxChargeUsd for an estimated PPE spend ceiling.

Important behavior

The extractor processes returned HTML and embedded structured data. If a locator requires a JavaScript form, provide the rendered result HTML or a permitted public locator response. Setting interactWithSearchForm without rendered results produces an explicit diagnostic.

Dataset output

Each dataset item is one JSON object. The schema includes:

• locator and branch URLs.
• location name, address, phone, and hours.
• distance and result position.
• pagination page.
• observed endpoint evidence.
• extraction method.

The actor also writes a Markdown summary, CSV records, JSON issues, evidence excerpts, and run metadata to key-value storage. Raw HTML is excluded unless includeRawSnapshots is enabled.

Pricing and charge safety

This actor uses pay per event with Apify platform-usage pass-through disabled. Charges are accepted before paid dataset or report output. maxChargeUsd stops the run before the next event would exceed the configured amount, including when the limit is zero.

Event	Price
actor-start	$0.08000
locator-page-rendered	$0.02750
locator-result-record-extracted	$0.00950
locator-issue-detected	$0.01950
report-generated	$0.18000

Example input

{
  "htmlInputs": [
    {
      "sourceUrl": "https://example.com/locations",
      "html": "<article class=\"location-card\"><h2>Downtown Branch</h2><p>100 Broadway, Nashville, TN 37201</p><p>615-555-0100</p><p class=\"hours\">Mon–Fri 8–6</p><a href=\"/locations/downtown\">Details</a></article>"
    }
  ],
  "maxPages": 1,
  "maxLocations": 10,
  "maxResultsPerQuery": 10,
  "interactWithSearchForm": false,
  "maxChargeUsd": 50
}

Result quality

• Public URL fetching rejects localhost and private IPv4 targets.
• Domain allowlists, timeouts, request delays, crawl depth, and actor-specific limits are enforced.
• Missing or blocked source evidence produces an explicit diagnostic instead of invented values.
• Every dataset row follows the declared dataset schema.
• Reports include the evidence reference and recommended next action for each finding.

Responsible use

Only process public pages or content you are authorized to analyze. Respect site terms, robots policies, rate limits, privacy obligations, and applicable law.