Chain store footprint analysis

Access and scope

Set CRAWLORA_API_KEY to your Crawlora key. Prefer the listed Crawlora MCP tools when connected; otherwise use the bundled scripts/crawlora.sh, which sends x-api-key to https://api.crawlora.net/api/v1. Read reference/endpoints.md for exact methods and parameters. Check application code as well as HTTP status; payloads are inside data. Stop on authentication errors, back off on 429, and retry a transient upstream failure once. Bound calls/pages by the requested scope and credit budget. Retain source IDs, URLs, source dates, and observation/crawl times separately.

Map observed branches for specified chains and geographic boundaries. Establish brands/aliases, store versus kiosk/licensed location scope, cities or coordinate boundaries, amenity criteria, source set, and collection budget before counting. This describes observed supply, not sales, foot traffic, demand, or site profitability.

Discover branches under matched geographic scopes

• Use stored Starbucks facets/search/nearby for brand-specific discovery and stable store_number. Dataset country is actual geography; market=us/ca records crawl-host provenance and must not be mistaken for a geographic filter. Preserve exact country/state/city and coordinate evidence.
• Refresh selected locations with live Starbucks locator/nearest-store calls. Either place or a coordinate pair is needed. Its cap is 50 without pagination; result_capped means the local result is incomplete. Distinguish a failed geocode (place_not_found) from a successful search with no returned branches. Canadian operational data should use the Canadian host when requested.
• Other brands can use stored Google Maps business search/facets/nearby, followed by selected live search/place verification. A name-text match is not a verified chain affiliation; check canonical brand/site, address, and location evidence. Google Maps category/country values differ from Starbucks taxonomy/codes.
• McDonald's coordinate locator is a separate source with its own accepted markets, cap, and radius in miles; dataset nearby radii are meters. Convert explicit geographic scopes rather than copying identical numeric radius values. A capped live locator alone cannot establish a whole-country store count.
• Keep a boundary/query ledger, requested/returned pages, cap flags, search result counts, and crawl times. The stored indexes are not automatically an official census of every branch or a proof that a competing chain is absent.

scripts/crawlora.sh /datasets/starbucks-stores/facets facet=country
scripts/crawlora.sh /datasets/starbucks-stores/search country=US city=Seattle page=1 page_size=100
scripts/crawlora.sh /starbucks/stores place="Seattle, WA" market=us
scripts/crawlora.sh /datasets/google-map-businesses/search q="Starbucks" city=Seattle page=1 page_size=10

Reconcile locations and report coverage

Deduplicate the same brand/store ID first; cross-source matches need address and coordinate corroboration. Similar names are not sufficient, and two units/kiosks inside a complex can be distinct branches. Keep relocated, permanently-closed, licensed, and company-operated locations explicit when fields support the labels. An empty schedule/amenity field can mean not published for that market, not closed or unsupported. Mobile-order readiness differs from static capability codes.

Use unique matched branches for area counts. For overlapping radius queries, count each branch once and keep the union boundary explicit; dividing by the sum of overlapping circle areas produces a misleading density. Area density requires a defined area, and per-capita measures require a separately sourced population with matching geography/date. Counts alone are not market share.

Return a branch evidence ledger, deduplicated area/brand matrix, source coverage, observed amenity/ownership breakdowns, and unknown or incomplete areas. A missing branch in a capped/partial sample is an observed coverage gap, not proof of closure or unmet demand. Historical expansion/contraction claims require comparable saved observations and verified changes. Do not contact stores, submit leads, or choose an investment/site solely from this footprint.