Skip to content

Getting started

LookAlike is hosted at app.lookalikeiq.com. Access is invite-only: request a magic link with the email address that was invited, open the link, and you land in the workspace for the retail client you have been granted access to. You can register a passkey afterwards from the /account page so later sign-ins do not need email.

The rest of this page tours the interface. Everything in it applies to the hosted app.

The repository also runs front-end-only, without accounts, against the committed data copy:

  1. Enter the web directory and install dependencies:

    Terminal window
    cd web
    pnpm install
  2. Start the development server:

    Terminal window
    pnpm dev
  3. Open the app in your browser: Navigate to http://localhost:5180. You will see the main interface loading 83,000 U.S. census tracts.

The top of the left panel holds a searchable brand picker: a single dropdown that lists the 99 curated brands, any brands you have saved, and an action row to add a new one. Examples include Trader Joe’s, Whole Foods Market, Chipotle, Starbucks, Costco, Dollar General, Sephora, REI, Sweetgreen, Shake Shack, 7-Eleven, and Walgreens.

Store counts vary by brand and by store source. Each brand uses All The Places (CC0) when it covers at least 80% as many tracts as OpenStreetMap, otherwise OpenStreetMap. Store points within 250 m merge into one site, and sites farther than 1 km from any continental tract are dropped. The Brand panel names each brand’s source and count. You can also add any other United States chain from OpenStreetMap by name (see step 7).

Open the picker and choose a brand to begin. You can type in the search box to filter the list, or move through it with the arrow keys and press Enter to select; pressing Escape or clicking outside closes it. Switching among curated brands is instant, because each brand’s national scores are computed once and then kept in memory, so returning to a brand you have already viewed does not re-score the country. Below the picker, you will see:

  • The number of store tracts used to fit that brand’s presence model (one observation per tract, so a Costco fuel station and warehouse do not double-count).
  • Footprint coherence: a validation badge showing whether the brand occupies a consistent kind of place. Distinctive chains (93 or above, such as Sephora at 99.2) rank higher because they cluster geographically; diffuse chains (below 85, such as Circle K at 75.5) rank lower because they operate almost everywhere. Across the 99 brands the median is 92.0.

The national choropleth shows census tracts colored by fit to the brand’s pattern:

  • Brighter colors = higher fit percentile (closer to 100th).
  • Dark gray areas = median tracts and weaker matches — left uncolored intentionally so you focus on where to look.
  • White dots ringed in the brand color (if “Show stores” is toggled on) = existing store locations.

Each neighborhood is a census tract — a statistical geography unit of roughly 4,000 people. The color is computed live in the browser as you adjust filters and weights.

Click any tract on the map or pick one from the ranked candidate list (right panel). The detail panel opens with:

  • Fit percentile: a within-brand rank (0–100, where ~100 best matches that brand’s pattern nationally).
  • Fit band: a Strong / Moderate / Weak chip measured against the brand’s own store tracts. It does not measure absolute fit across brands.
  • Low ACS reliability badge (when applicable): flags a small-population tract or a large income margin of error.
  • Radar fingerprint: a visual comparison of the tract vs. the brand’s typical store tract across the scored themes.
  • Why it matches: the features that raise the score most.
  • What works against it: the features that lower the score most, with the brand’s typical value for each.
  • Full feature table: the 18 scored features grouped by theme, with the tract’s actual values and the brand’s typical values.
  • Plain-English assessment: a summary of fit.
  • Robustness badge: whether the high rank is robust or hinges on one theme.
  • Nearby chains: which of the tracked brands have a store within 6 km.
  • Existing store info: whether the tract already has a brand location and distance to the nearest one.
  • “Not a fit?” control: flag a wrong lookalike to hide it and learn what your rejected tracts share.

On the left:

  • Open markets only: hide tracts that already contain a store.
  • Min. fit: show only tracts above a percentile threshold.
  • State: filter to a single state (the list re-pools and ranks within the state).
  • Competition: keep tracts at least a chosen distance from your own stores, or with no competitor within 6 km. Competitors are the other curated brands in the same category unless you choose others.
  • Special-use tracts: rankings leave out airports, parks, military bases, prisons, water, and other tracts with fewer than 500 residents. Turn on Include special-use tracts to show them.
  • Focus a metro: zoom to one of 383 Census metro areas and rank only that metro’s neighborhoods, or open Top metros to rank the metros against each other by open, high-rank neighborhood count.

All filters apply live. The map and candidate list re-rank instantly.

Expand “Tuning the factors” to reweight the five scored themes:

  • Income, wealth & housing cost
  • Education
  • Density & transportation
  • Age & household type
  • Retail & dining context

Each slider ranges from 0 (off) to 2× (doubled). At 1× the score is the fitted model; other weights scale each theme’s contribution. Presets include Balanced, Affluence-led, Urbanism-led, and Household-led. Each group also opens an Advanced per-feature layer for weighting a single feature within a group. The map and rankings re-score live as you drag.

Select a second brand from the ”⇄ Compare vs” dropdown. The map shifts to a diverging lean map:

  • Color hue shows which brand a neighborhood leans toward, using a fixed, colorblind-safe blue-and-orange pair (blue for A, orange for B).
  • Brightness shows how strongly it resembles either.
  • The candidate list shows three rankings: Leans A / Resembles both / Leans B.

Click a tract to see side-by-side percentiles for both brands and which features drive the lean.

Open the brand picker and choose the “Add a brand (CSV or OpenStreetMap)…” row to bring in your own CSV of store locations:

  • CSV columns: lat, lon (required); revenue or sales or value (optional); status (optional, values like closed, failed, low).
  • Authenticated uploads are saved as private, versioned client datasets; quick unauthenticated Vite development remains browser-only.
  • National scoring is computed client-side using the same scoring logic as the pipeline.

Once added, the tool fits a presence model on your stores and ranks all 83,000 tracts by fit to your winners. Higher performers get more weight in the fit, and a second model on your failure tracts penalizes failure lookalikes. In the authenticated product, reopen a published version from Saved customer datasets in the upload dialog.

If you don’t have a store list but want a chain that isn’t built in, use the same “Add a brand (CSV or OpenStreetMap)…” row and switch to the OpenStreetMap tab: type the chain’s name and the tool fetches its United States store points live from OpenStreetMap and scores them the same way (subject to how completely that chain is mapped). A fetched brand is saved in your browser just like a CSV upload. See custom upload.

Click the star icon on any neighborhood to add it to your shortlist. From the Shortlist panel (right side), you can:

  • Annotate each neighborhood with notes.
  • Export a PDF report (per-tract stat tables vs. brand average, drivers, and a disclaimer).
  • Export a CSV (all saved neighborhoods and features, plus the fit band and reliability flag, formula-injection-safe). The separate ranked-list CSV export additionally carries the competition columns.

To keep several analyses side by side, save the current view (brand, weights, compare, metro, filters) as a named scenario and switch between them later. Use the Copy link button to put the current view on your clipboard to share.

  • Understand the method: Read How it works for a detailed explanation of the scoring, feature set, and validation.
  • Data sources: See Data sources for URLs, licenses, and coverage caveats.
  • Custom uploads: Upload your own stores for a fuller walkthrough with performance weighting and failure avoidance.
  • FAQ: Check Frequently asked questions for common questions about predictions, limitations, and data freshness.