Skip to content

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.

PieceWhere in the repoNotes
Adminapp/routes/app.*Remix + Polaris, embedded in the Shopify admin
Public APIapp/routes/api.v1.*Unauthenticated, CDN-cached, CORS-open JSON
Widgetwidget/srcVanilla TypeScript. Draws with Leaflet, or Mapbox GL when the map provider is Mapbox. Bundled with esbuild.
Theme blockextensions/store-locatorTheme app extension that ships the widget as an app block
Dataprisma/Postgres + PostGIS on Supabase
Migration scriptsscripts/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.

StoreTheme templateMap IDLocations (approx.)Notes
Ark Naturalstemplates/page.custom-store-locator.jsonm_wfrr48n89x6,600Heading "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 Bakeryshopify/templates/page.custom-store-locator.jsonm_5aeffm9djt8,300Class content-area, accent #2d2a26. Imported from the bb-locations-export file. See Bocce's store locator.
Super Snoutstemplates/page.custom-store-locator.jsonm_8yuz6eure66,400See Super Snouts store locator page.
My Perfect Petshopify/templates/page.custom-store-locator.jsonm_a8b3mndxgy1,600
Poke'stemplates/page.custom-store-locator.jsonm_gz2wjfe2k9267Accent #65113b. Page at try-pokes.myshopify.com/pages/store-locator (trypokes.com redirects to boccesbakery.com). See Poke's Store Locator.
Antelope Petsshopify/templates/page.store-locator-february.jsonm_etzcamkvjf0App 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-afd3a5e788ba

Poke'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 GeocodeCache shared 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 /geocode route.
  • 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 in app/lib/search.server.ts must stay byte-identical to the one in that migration, or radius search silently falls back to a sequential scan.
  • The lock_down_data_api migration revokes Supabase's default anon grants and enables RLS, so the Session table (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.

RoutePurpose
/api/v1/{tag}/configWidget configuration (provider, public map key, colours, units, radii, labels, filters)
/api/v1/{tag}/locations/allEvery 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-locationApproximate visitor location from Vercel's edge geo headers, falling back to ipapi.co (not cached)

Where it's deployed ​

Repositorygithub.com/crupko93/store-locator, branch main
Shopify app recordPinpoint Store Locator, handle pinpoint-locator, client_id b1dfc7d10db437af215494874cbdbcf9, Public distribution (not listed on the App Store)
App URLhttps://store-locator-eta.vercel.app (also in application_url and the three redirect_urls in shopify.app.toml)
Webhooksapp/uninstalled, plus the mandatory customers/data_request, customers/redact, shop/redact (relative URIs under /webhooks/...)
VercelProject store-locator, framework Remix, functions pinned to cle1 in vercel.json. Git-connected: production deploys from main, other branches get previews.
DatabaseSupabase project in us-east-2 (Ohio): Postgres + PostGIS + pg_trgm. Transaction pooler for the app, session pooler for migrations.
MapsMapbox (all live maps), MapTiler (shared fallback key MAPTILER_DEFAULT_KEY), or keyless OpenStreetMap
Dev storedev-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 ​

  1. 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.
  2. 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.
  3. Match the storefront. Accent colour, distance unit, search radii, map provider/key and the wording of the search box are in Settings.
  4. 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 use Filter: <name> columns or one Filters / Tags column.
  • 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) ​

SettingKeyDefaultNotes
Map providermapProviderosmosm (no key, demo only), maptiler, mapbox
Map keymapKey(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 stylemapStylestreets-v12streets-v12, light-v11, dark-v11, outdoors-v12, navigation-day-v1
Accent colourfeatureColor#1a73e8Pins, buttons, distances. A colour set on the theme block overrides it.
Distance unitdistanceUnitmimi or km
Search radiisearchRadii10, 25, 50, 100In the chosen unit
Limit to countriescountries(worldwide)Makes postcode searches much more accurate. Set it.
Ask for the visitor's location when the map loadsautoGeolocateoffUses the silent IP lookup only, never a permission prompt
Search box placeholdersearchPlaceholder"Enter your zip code or city"
No results messagenoResultsText"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 ​

  1. In the app, open Add to your theme and press Open the theme editor. The block is preselected.
  2. Paste the Map ID into the block's Map ID field if it isn't prefilled. Save.
  3. If the editor opens with nothing selected (no published page template), add it by hand: Add section → Apps → Store locator.

Theme block settings ​

SettingIDTypeDefaultNotes
Map IDmap_tagtext(empty)Copy from Add to your theme
Headingheadingtext"Find a store near you"Rendered above the locator (.store-locator-heading)
Accent colourfeature_colorcolor(empty)Empty uses the colour from Settings
CSS classcustom_classtextcontainerAdded next to store-locator-block. Clear it for full-bleed.
Heightmin_heightrange 400–900 px560
Zoom with the scroll wheel right awayscroll_zoomcheckboxoffOff: one click on the map hands it the wheel
Layoutlayoutselectsideside (list beside the map) or stacked (full-width map, list below)
Results list widthpanel_widthrange 260–520 px360Only 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 inShips withCommand
app/, prisma/, vercel.json (admin, API, database)VercelMerge 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)ShopifySHOPIFY_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):

VariablePurpose
SHOPIFY_API_KEYApp client ID
SHOPIFY_API_SECRETApp client secret
SHOPIFY_APP_URLhttps://store-locator-eta.vercel.app. Must match application_url. Also needed when building the widget.
SCOPESEmpty. The app requests none.
DATABASE_URLSupabase transaction pooler (port 6543) with connection_limit=1
DIRECT_URLSupabase session pooler (port 5432, pooler host). Not "Direct connection", which is IPv6-only and fails on Vercel.
MAPTILER_DEFAULT_KEYShared fallback tile key for maps without their own
GEOCODER_CONTACT_EMAILContact address in the Nominatim User-Agent. Nominatim blocks callers without one.

Local development:

shell
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 ​

ScriptUse
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.csvFor 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 ​

shell
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 closed

API smoke test (read-only):

shell
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 ​

SymptomCause
Map area grey, list worksMap key missing or rejected (check domain restrictions on the key). Use Test in Settings.
Map not found from the widgetThe Map ID in the block doesn't match. Copy it again from Add to your theme.
Widget requests /api/v1/... on the storefront domainWidget built without SHOPIFY_APP_URL. Rebuild and npm run deploy.
P1001: Can't reach database serverDATABASE_URL points at 5432 instead of 6543, or the password has an unescaped character
Too many connectionsconnection_limit=1 missing from DATABASE_URL
Import finishes but pins never appearGeocoding still running (see the Import page backlog). If it stalls, check GEOCODER_CONTACT_EMAIL.
Re-import duplicates every locationIDs aren't round-tripping. Run npm run verify:csv on the file.
OAuth loops back to installapplication_url / redirect_urls don't match the Vercel domain exactly
Block missing in the theme editorExtension 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 editThe API is CDN-cached for 5 minutes. Hard-refresh or wait.
Deployment fails with no build logvercel.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/all is refused above 2,000 locations. Large maps rely on bounds and search.
  • Online-only stores (no address) can't be placed on the map.

Antelope Themes Documentation

Enter the password to access this site.