Pinpoint Store Locator
Overview
Pinpoint Store Locator is our own Shopify app that puts a searchable map of retail locations on a storefront. The brand stores use it in place of Stockist.
| Piece | Where in the repo | Notes |
|---|---|---|
| Admin | app/routes/app.* | Remix + Polaris, embedded in the Shopify admin |
| Public API | app/routes/api.v1.* | Unauthenticated, CDN-cached, CORS-open JSON |
| Widget | widget/src | Vanilla TypeScript. Draws with Leaflet, or Mapbox GL when the map provider is Mapbox. Bundled with esbuild. |
| Theme block | extensions/store-locator | Theme app extension that ships the widget as an app block |
| Data | prisma/ | Postgres + PostGIS on Supabase |
| Migration scripts | scripts/ | Stockist import/harvest, CSV geocoding, Bocce's export conversion, verification |
What it does:
- Locations with full address, contact details, image, notes, priority and visibility
- Spreadsheet import and export, drop-in compatible with Stockist's CSV format (plus Latitude/Longitude)
- Address lookup at import, with a shared geocode cache so the same address is never looked up twice
- Search filters and custom fields
- Storefront widget: search by place or store name, radius, filters, geolocation (IP first, browser only when needed), clustering, directions routed from what the shopper searched
- An in-app manual at
/app/guide("How to use the store locator") - A public JSON API for headless storefronts
Deliberately not in scope: analytics, heatmaps, search reports, Google Sheets sync.
The app requests no access scopes. Locations live in the app's own database, so the install screen asks the merchant to approve nothing, and the app stays out of the protected-customer-data review track.
Where it's used
All six brand themes reference the app block. Every live map uses the Mapbox provider, miles, and radii 10 / 25 / 50 / 100.
| Store | Theme template | Map ID | Locations (approx.) | Notes |
|---|---|---|---|---|
| Ark Naturals | templates/page.custom-store-locator.json | m_wfrr48n89x | 6,600 | Heading "Store Locator", accent #0057c2 (from Settings). Followed by an Other brands section linking to the Bocce's, Super Snouts and MPP locator pages. See Ark Store Locator. |
| Bocce's Bakery | shopify/templates/page.custom-store-locator.json | m_5aeffm9djt | 8,300 | Class content-area, accent #2d2a26. Imported from the bb-locations-export file. See Bocce's store locator. |
| Super Snouts | templates/page.custom-store-locator.json | m_8yuz6eure6 | 6,400 | See Super Snouts store locator page. |
| My Perfect Pet | shopify/templates/page.custom-store-locator.json | m_a8b3mndxgy | 1,600 | |
| Poke's | templates/page.custom-store-locator.json | m_gz2wjfe2k9 | 267 | Accent #65113b. Page at try-pokes.myshopify.com/pages/store-locator (trypokes.com redirects to boccesbakery.com). See Poke's Store Locator. |
| Antelope Pets | shopify/templates/page.store-locator-february.json | m_etzcamkvjf | 0 | App installed, but the section is disabled and the map is empty. |
Every theme stores the block reference exactly as:
shopify://apps/pinpoint-store-locator/blocks/locator/019fd12c-653c-7cce-a605-afd3a5e788baPoke's theme also contains a Stockist widget
The Stockist embed is in the Poke's theme code: sections/store-locator.liquid (widget tag u21861) and the default templates/page.json (Stockist CSS overrides). A page created on the default page template shows Stockist, not Pinpoint. Use the custom-store-locator template.
Handle vs. block reference
The app's handle is pinpoint-locator (in shopify.app.toml). That is what appears in admin URLs (/admin/apps/pinpoint-locator/...) and in the extension's CDN asset path (.../pinpoint-locator-15/assets/locator.js, locator-mapbox.js, locator.css).
The theme block reference uses pinpoint-store-locator instead. Shopify resolves the block by the trailing UUID; the pinpoint-store-locator segment is not the handle (that handle is held by another app, and handles are global). DEPLOYMENT.md in the repo uses pinpoint-store-locator as the handle in its text; the value that counts is the one in shopify.app.toml.
Don't hand-edit block references, handle or app name
Copy block references exactly as the theme editor writes them. Changing the handle or the app name can break every page that has the widget. If you must, test on a development store first.
Architecture
Shopify admin (embedded) Storefront (theme app block)
└── Remix + Polaris /app/* └── locator.js / locator-mapbox.js + locator.css
│ (session: Prisma) │ fetch {SHOPIFY_APP_URL}/api/v1/{mapTag}/...
▼ ▼
Vercel project "store-locator" ── functions pinned to cle1 (Cleveland = AWS us-east-2)
│
▼
Supabase Postgres + PostGIS + pg_trgm (us-east-2)
tables: Session, Shop, Map, Location, Filter, LocationFilter,
CustomFieldDef, GeocodeCache, ImportJob- One map per shop (
Map.key = "default"). The widget addresses maps by a random public tag (m_…), so the tag in page source can't be used to enumerate other merchants' maps. - Geocoding: Nominatim (OpenStreetMap) at import, one address per second, with a
GeocodeCacheshared across every merchant. Maps with a Mapbox or MapTiler key geocode visitor searches in the browser with the merchant's key. Only keyless OSM maps use the app's/geocoderoute. - Uninstall only marks the shop (
uninstalledAt); locations stay.shop/redact(48 h later) is what erases. - PostGIS lives outside the Prisma schema. The spatial and trigram indexes are in the hand-written migration
prisma/migrations/*_postgis. The geography expression inapp/lib/search.server.tsmust stay byte-identical to the one in that migration, or radius search silently falls back to a sequential scan. - The
lock_down_data_apimigration revokes Supabase's defaultanongrants and enables RLS, so theSessiontable (merchant tokens) is not readable through Supabase's public Data API.
Public API
All routes are GET, unauthenticated, CORS-open, and cached (s-maxage=300, stale-while-revalidate=86400) unless noted.
| Route | Purpose |
|---|---|
/api/v1/{tag}/config | Widget configuration (provider, public map key, colours, units, radii, labels, filters) |
/api/v1/{tag}/locations/all | Every visible location. Refuses above 2,000 locations with too_many_locations (Ark, Bocce's and Super Snouts are above it). |
/api/v1/{tag}/locations/bounds?north=&south=&east=&west=&filters= | Locations inside the visible map rectangle (max 500). What large maps show before a search. |
/api/v1/{tag}/locations/search?latitude=&longitude=&distance=&filters=&q= | Radius search, sorted by priority then distance (max 250). distance is in the map's unit. |
/api/v1/{tag}/geocode?q= | Address lookup for keyless OSM maps (cached 7 days) |
/api/v1/{tag}/ip-location | Approximate visitor location from Vercel's edge geo headers, falling back to ipapi.co (not cached) |
Where it's deployed
| Repository | github.com/crupko93/store-locator, branch main |
| Shopify app record | Pinpoint Store Locator, handle pinpoint-locator, client_id b1dfc7d10db437af215494874cbdbcf9, Public distribution (not listed on the App Store) |
| App URL | https://store-locator-eta.vercel.app (also in application_url and the three redirect_urls in shopify.app.toml) |
| Webhooks | app/uninstalled, plus the mandatory customers/data_request, customers/redact, shop/redact (relative URIs under /webhooks/...) |
| Vercel | Project store-locator, framework Remix, functions pinned to cle1 in vercel.json. Git-connected: production deploys from main, other branches get previews. |
| Database | Supabase project in us-east-2 (Ohio): Postgres + PostGIS + pg_trgm. Transaction pooler for the app, session pooler for migrations. |
| Maps | Mapbox (all live maps), MapTiler (shared fallback key MAPTILER_DEFAULT_KEY), or keyless OpenStreetMap |
| Dev store | dev-store-749237498237499044.myshopify.com |
Region pinning
vercel.json pins functions to cle1 because the database is in us-east-2. An import is one database round trip per row. With functions and database on different continents a 400-row batch takes over five minutes and hits the function timeout. If you move the database, move the region too.
How to use (merchant / admin)
Open the app from Apps → Pinpoint Store Locator in the store admin. The in-app guide (How to use the store locator, /app/guide) has the full manual.
Set-up in four steps
- Import locations. Import accepts a spreadsheet exported from another locator as-is (Stockist CSV works directly). Or add locations one at a time under Locations.
- Check the pins. The home page counts locations with no coordinates. They exist in the app but never appear on the map. Usually the address couldn't be geocoded.
- Match the storefront. Accent colour, distance unit, search radii, map provider/key and the wording of the search box are in Settings.
- Put it on a page. Add to your theme shows the Map ID and opens the theme editor with the block ready to place.
Import
- Merge (default) matches rows on the ID column. Existing locations are updated, new ones added, nothing deleted.
- Replace everything removes existing locations and imports the file as the complete list. Export first.
- Rows with Latitude/Longitude import instantly and are never re-geocoded. Rows without them are geocoded in the background at about one per second. Leave the Import page open. It drives the geocoder and shows what's left.
- Recognised headings include Stockist's (
Stockist ID,Name,Address line 1, …). Unrecognised columns can be kept as custom fields. Filters useFilter: <name>columns or oneFilters/Tagscolumn. - Save as CSV UTF-8 if names contain accents.
- Locations → Delete all locations empties a map in one action, behind a typed confirmation.
Settings (per map)
| Setting | Key | Default | Notes |
|---|---|---|---|
| Map provider | mapProvider | osm | osm (no key, demo only), maptiler, mapbox |
| Map key | mapKey | (empty) | Mapbox public token (pk.…) or MapTiler key. The Test button checks it. Empty falls back to the shared MapTiler key, then to OSM. Never paste a secret sk. token. |
| Mapbox style | mapStyle | streets-v12 | streets-v12, light-v11, dark-v11, outdoors-v12, navigation-day-v1 |
| Accent colour | featureColor | #1a73e8 | Pins, buttons, distances. A colour set on the theme block overrides it. |
| Distance unit | distanceUnit | mi | mi or km |
| Search radii | searchRadii | 10, 25, 50, 100 | In the chosen unit |
| Limit to countries | countries | (worldwide) | Makes postcode searches much more accurate. Set it. |
| Ask for the visitor's location when the map loads | autoGeolocate | off | Uses the silent IP lookup only, never a permission prompt |
| Search box placeholder | searchPlaceholder | "Enter your zip code or city" | |
| No results message | noResultsText | "No locations found. Try a wider search radius." | |
| Filters | — | — | Create filters here before importing files that reference them |
Map keys are public
Every web map ships its key in page source. All six live maps use the same Mapbox public token. Protect it by restricting the token to the storefront domains in the Mapbox dashboard, not by hiding it.
Add the block to a theme
- In the app, open Add to your theme and press Open the theme editor. The block is preselected.
- Paste the Map ID into the block's Map ID field if it isn't prefilled. Save.
- If the editor opens with nothing selected (no published
pagetemplate), add it by hand: Add section → Apps → Store locator.
Theme block settings
| Setting | ID | Type | Default | Notes |
|---|---|---|---|---|
| Map ID | map_tag | text | (empty) | Copy from Add to your theme |
| Heading | heading | text | "Find a store near you" | Rendered above the locator (.store-locator-heading) |
| Accent colour | feature_color | color | (empty) | Empty uses the colour from Settings |
| CSS class | custom_class | text | container | Added next to store-locator-block. Clear it for full-bleed. |
| Height | min_height | range 400–900 px | 560 | |
| Zoom with the scroll wheel right away | scroll_zoom | checkbox | off | Off: one click on the map hands it the wheel |
| Layout | layout | select | side | side (list beside the map) or stacked (full-width map, list below) |
| Results list width | panel_width | range 260–520 px | 360 | Only for side layout |
Every widget class is prefixed sl- (e.g. .sl-result-name, .sl-pin-inner, .sl-search-input), so a theme's own CSS or the section's Custom CSS can restyle any part. The Bocce's, Poke's and Ark templates do this.
How to update & deploy
Two things ship independently:
| Change in | Ships with | Command |
|---|---|---|
app/, prisma/, vercel.json (admin, API, database) | Vercel | Merge to main. Vercel runs npm run vercel-build = prisma generate && prisma migrate deploy && npm run widget:build && remix vite:build. |
widget/src, extensions/store-locator (storefront) | Shopify | SHOPIFY_APP_URL=https://store-locator-eta.vercel.app npm run deploy (= widget:build + shopify app deploy) |
Rebuild the widget before every extension deploy
The built assets in extensions/store-locator/assets are gitignored. shopify app deploy ships whatever is in that folder. The widget's API base is baked in at build time from SHOPIFY_APP_URL, and widget:build refuses to run without it. Built without it, the widget would call /api/v1/... on the merchant's storefront and 404.
Environment variables (names only; values live in Vercel, Production and Preview, and in a local .env copied from .env.example):
| Variable | Purpose |
|---|---|
SHOPIFY_API_KEY | App client ID |
SHOPIFY_API_SECRET | App client secret |
SHOPIFY_APP_URL | https://store-locator-eta.vercel.app. Must match application_url. Also needed when building the widget. |
SCOPES | Empty. The app requests none. |
DATABASE_URL | Supabase transaction pooler (port 6543) with connection_limit=1 |
DIRECT_URL | Supabase session pooler (port 5432, pooler host). Not "Direct connection", which is IPv6-only and fails on Vercel. |
MAPTILER_DEFAULT_KEY | Shared fallback tile key for maps without their own |
GEOCODER_CONTACT_EMAIL | Contact address in the Nominatim User-Agent. Nominatim blocks callers without one. |
Local development:
git clone git@github.com:crupko93/store-locator.git && cd store-locator
npm install
cp .env.example .env
npx prisma migrate deploy
npm run widget:build # needs SHOPIFY_APP_URL
npm run dev # shopify app dev: tunnel, admin, extensions
npm run widget:dev # rebuild the widget on change (second terminal)shopify app dev rewrites application_url to its tunnel and restores it on exit. If it crashes, the app record can be left pointing at a dead tunnel. Re-run npm run dev once, or fix the URL in the Dev Dashboard.
Prisma migrations
prisma migrate dev diffs against schema.prisma alone and may emit DROP statements for the PostGIS/trigram indexes it doesn't know about. Read every generated migration before applying it.
Migrating a store off Stockist
| Script | Use |
|---|---|
npm run import:stockist -- --tag <u…> --shop <shop>.myshopify.com [--dry-run] | Reads Stockist's public /locations/all JSON (with coordinates) into the app. Safe to re-run: keyed on Stockist ID. Works for older Stockist maps such as Poke's (u21861). |
npm run harvest:stockist -- --tag <map_…> --out file.csv | For Stockist maps that block /locations/all. Quadtree sweep over /locations/search (100 per request), writes a CSV with coordinates. Used for Ark. |
npx tsx scripts/convert-bb-export.ts input.csv [output.csv] | Converts the Bocce's bb-locations-export file into the import format with stable IDs |
npx tsx --env-file-if-exists=.env scripts/geocode-csv.ts input.csv [output.csv] | Fills in missing coordinates before import, so misses are fixable in the file |
Then replace the Stockist section with the Store locator app block, port any .stockist-* CSS to the matching .sl-* classes, run both side by side for a few days, and uninstall Stockist.
Testing
npm run typecheck
npm run lint
npm run verify:csv -- ../stockist-locations.csv
npm run verify:search # seeds 10,000 rows in a scratch DB; fails if radius search stops using the spatial index
npm run verify:db # after migrate deploy: PostGIS/trigram indexes exist, Supabase Data API closedAPI smoke test (read-only):
curl https://store-locator-eta.vercel.app/api/v1/nope/config # {"error":"Map not found"}: function + DB reachable
curl https://store-locator-eta.vercel.app/api/v1/m_gz2wjfe2k9/config
curl "https://store-locator-eta.vercel.app/api/v1/m_gz2wjfe2k9/locations/search?latitude=39.7392&longitude=-104.9903&distance=100"Storefront checklist: pins cluster; typing a city shows suggestions; results sort by distance; the radius dropdown changes the count; the locate button works; clicking a result opens its pin; Directions opens Google Maps from the searched place; below 760 px the map moves above the list.
Admin checklist: export CSV, re-import the same file. It must report updates N, creates 0. If it creates rows, IDs are not round-tripping.
Troubleshooting & known limits
| Symptom | Cause |
|---|---|
| Map area grey, list works | Map key missing or rejected (check domain restrictions on the key). Use Test in Settings. |
Map not found from the widget | The Map ID in the block doesn't match. Copy it again from Add to your theme. |
Widget requests /api/v1/... on the storefront domain | Widget built without SHOPIFY_APP_URL. Rebuild and npm run deploy. |
P1001: Can't reach database server | DATABASE_URL points at 5432 instead of 6543, or the password has an unescaped character |
| Too many connections | connection_limit=1 missing from DATABASE_URL |
| Import finishes but pins never appear | Geocoding still running (see the Import page backlog). If it stalls, check GEOCODER_CONTACT_EMAIL. |
| Re-import duplicates every location | IDs aren't round-tripping. Run npm run verify:csv on the file. |
| OAuth loops back to install | application_url / redirect_urls don't match the Vercel domain exactly |
| Block missing in the theme editor | Extension not deployed, or a stale shopify app dev session pins the store to a dev version: shopify app dev clean --store <store> |
| Storefront doesn't show an edit | The API is CDN-cached for 5 minutes. Hard-refresh or wait. |
| Deployment fails with no build log | vercel.json has an unrecognised key. It is validated before the build runs. |
- A location whose address can't be geocoded is marked with an error and not retried. Fix the address or type coordinates.
/locations/allis refused above 2,000 locations. Large maps rely onboundsandsearch.- Online-only stores (no address) can't be placed on the map.