Uploading your own stores
LookAlike’s flagship feature lets you upload your own store list and instantly discover neighborhoods that resemble your footprint using the same method the tool applies to the built-in brands. In the authenticated product, the source CSV is stored in a private customer-data bucket, normalized rows are stored under the selected retail client, and the interactive scoring still runs in the browser. The source file is never exposed through the public national-data route.
To start, open the brand picker at the top of the left panel and choose the “Add a brand (CSV or OpenStreetMap)…” row. That opens the upload modal, which has a tab for pasting or dropping a CSV and a tab for fetching a brand from OpenStreetMap.
What you get
Section titled “What you get”When you upload a CSV of store locations, the tool:
- Assigns each store to the census tract that contains it, then fits a presence model on your store tracts against a national background
- Ranks every continental-US census tract by how well it fits your model
- Surfaces the exact features driving each match on the map and in neighborhood detail panels
- Optionally applies performance weighting (if you include revenue/sales data) to give higher-performing locations more weight in the fit
- Optionally flags locations to avoid (closures, failures, underperformers) so the tool shows neighborhoods that look like your winners but NOT like your failures
This is fit and discovery, not sales prediction. The labels — revenue, closed, failed — are your ground truth, not a statistical model. Use this to find neighborhoods worth visiting and vetting, not to shortlist sites automatically.
CSV format
Section titled “CSV format”Your upload must include latitude and longitude. Everything else is optional.
Required columns:
lat(orlatitude,y) — decimal degrees, −90 to 90lon(orlng,long,longitude,x) — decimal degrees, −180 to 180
Optional columns:
- Performance column — named
revenue,sales,value,volume,performance,perf,score,weight, or similar. Numeric values. When present, the Weight by performance toggle becomes available; turning it on gives locations with higher values more weight in the fit. - Status column — named
status,label,group,tier,segment,outcome,result, orclass. Values likeclosed,failed,low,bad(or their variations) mark a location as a failure. Alternatively, a boolean column namedfailedwith valuestrue,1,yes, ory. When present, the Avoid my failed/low locations toggle becomes available; turning it on downranks neighborhoods that look like your flagged failures. If no status column exists but you have performance data, locations below the bottom-third cutoff are treated as lower performers. Equal values that cross the cutoff stay together and are not flagged automatically.
The upload modal accepts .csv files or plain text pasted directly (tab, comma, or semicolon delimited). It proposes a column mapping, then requires you to confirm latitude, longitude, store identifier, performance, status, and failure columns before saving.
Example CSV
Section titled “Example CSV”lat,lon,revenue,status40.7128,-74.0060,2400000,open34.0522,-118.2437,610000,closed42.3601,-71.0589,1890000,open39.7392,-104.9903,540000,failed41.8781,-87.6298,2100000,open47.6062,-122.3321,280000,lowIn this example:
- Winners (colored dots on the map): the open and closed stores with higher revenue (New York, Boston, Denver, Chicago, Seattle)
- Failures (red-ringed dots): the failed location in Denver and the low-revenue location in Seattle
When you enable Avoid my failed/low locations, the scoring penalizes neighborhoods that resemble the failures. The final score for each tract becomes: resemblance-to-winners − (avoidance-strength) × resemblance-to-failures.
How winners and failures appear
Section titled “How winners and failures appear”Winners show as solid colored dots on the map (the same hue as the uploaded brand). They form the core of your model fit.
Failures show as dots ringed in red. They are excluded from the main model fit; instead, they define what to penalize.
When you select a neighborhood in the detail panel, you’ll see a winners-vs-failures breakdown — how similarly that neighborhood ranks to each group.
The two main toggles
Section titled “The two main toggles”Weight by performance
Section titled “Weight by performance”Available only if your CSV includes a numeric performance column (revenue, sales, or similar) with non-empty values in at least some rows.
When enabled, higher performers get more weight in the model fit. The default transformation uses percentile ranks rather than raw revenue: each valid store is ranked within the uploaded metric, then receives a stable 0–1 weight. This prevents one flagship location, malformed value, or currency scale from dominating the fit. You must also state whether higher or lower values represent better performance.
When disabled, all non-failed locations are weighted equally in the fit.
Avoid my failed/low locations
Section titled “Avoid my failed/low locations”Available if your CSV includes explicit failure flags (a status column with closed/failed/low values, or a boolean failed column) or if you have performance data.
When enabled, tracts are scored as resemblance-to-winners − (avoidance-strength) × resemblance-to-failures.
- If you flagged failures explicitly (status column), those locations fit the second (failure) model.
- If you only provided performance data, locations strictly worse than the bottom-third cutoff are treated as lower performers. A tie across the cutoff stays in the positive set, so fewer than one third may be flagged.
- The avoidance-strength slider controls the penalty weight (0–100%). At 60%, the penalty accounts for 60% of a unit of resemblance-to-failures. Higher values make failure lookalikes rank lower relative to winner lookalikes.
When disabled, all uploaded locations are treated equally.
Saved datasets
Section titled “Saved datasets”Authenticated CSV uploads become immutable, versioned datasets under the selected retail client. LookAlike stores the original CSV privately, normalized store rows and quality flags in D1, the selected performance definition, and the national-data release used for tract assignment. A baseline analysis records the scoring-engine version and configuration.
- It survives reloads. Open the upload dialog and load any published dataset available to your client account.
- Versions are immutable. Uploading a corrected file creates another version instead of changing the rows behind an existing analysis.
- Access is client-scoped. Owners and administrators can access all clients; analysts and viewers see only explicitly granted clients, and viewers cannot upload or delete.
- Deletion is complete. Deleting a dataset removes its normalized records, recorded analyses, and private source object while preserving a non-sensitive audit event.
The unauthenticated pnpm dev workflow remains browser-only for quick interface development. CSV profiles created in that mode use local browser storage and are not customer records.
Add a brand from OpenStreetMap
Section titled “Add a brand from OpenStreetMap”If you want to analyze a chain that isn’t one of the 99 curated brands and you don’t have a store list of your own, the tool can fetch one from OpenStreetMap for you. Open the brand picker, choose the “Add a brand (CSV or OpenStreetMap)…” row, switch to the OpenStreetMap tab, type the chain’s name (or pick one of the suggested chains, which attaches a Wikidata identifier for a more reliable match), and the browser queries the Overpass API directly for that chain’s United States store points, dedupes them on a 150 m grid, and routes them into the same custom-profile flow described above — labeled with the brand name. The fetched brand is then saved in your browser like any other custom brand.
This mirrors the pipeline’s OpenStreetMap store fetch (the fallback source when All The Places coverage is thin): a union query on brand:wikidata plus the exact name on shops and amenities, within a continental-US bounding box. The query runs from your browser; the two public Overpass endpoints are tried in turn, and very large chains are capped (with the truncation reported) so the request stays manageable.
What is NOT happening
Section titled “What is NOT happening”This is a descriptive neighborhood-resemblance tool, not a predictive sales model. The scoring:
- Does NOT assume resemblance causes revenue or store success
- Does NOT adjust for local competition, rent, visibility, traffic patterns, or any other factor beyond census neighborhood characteristics
- Does NOT validate that your category works in similar neighborhoods
- Is NOT comparable in prediction strength across different brand categories (a grocery store’s model and a coffee chain’s differ profoundly, but both are valid for discovery)
The fit percentile (0–100) ranks tracts within your own upload — it is not comparable to the percentile of a built-in brand. Two different custom uploads will have different national ranking scales based on their own fitted models.
How it works under the hood
Section titled “How it works under the hood”The browser computes the entire analysis client-side using the same method as the Python pipeline:
- Each store is assigned to the tract polygon that contains it (read from the release file
tracts/boundaries.binwith range requests), or to the nearest tract boundary within 1 km. Stores outside the continental US coverage are left out and counted in a notice. - The browser fits a presence model on your store tracts against a national background, over the same 18 scored features — using your performance weights if enabled
- Each tract is scored by the fitted model
- The model score is converted to a 0–100 fit percentile — higher = more like your winners. The browser also computes the reference from your own locations, so each tract gets a Strong / Moderate / Weak fit band measured against your footprint, exactly as it is for the built-in brands.
- If you enable failure avoidance, a second model is fit on your failure tracts and the final score subtracts a penalty for fit to failures
The Worker validates and persists the source file, mapping, normalized locations, metric definition, quality summary, tract assignments, and release lineage. The scoring calculation itself happens in the browser so factor changes remain immediate. Production logs must not contain raw rows, performance values, addresses, session tokens, or source files.