Dealer Locator

The Dealer Locator feature allows customers to find authorized Scottsdale Mint dealers near them. It displays dealer locations on an interactive map powered by the Google Maps API.

---

Plugin

• Plugin: suma-dealer-locator (custom, located at web/app/plugins/suma-dealer-locator/)

---

Features

• Interactive map — Google Maps embed with dealer location markers
• Location search — Customer enters city, state, or zip code to find nearby dealers
• Dealer info cards — Clicking a marker shows dealer name, address, phone, website, and specialty categories
• Radius filter — Show dealers within 10, 25, 50, or 100 miles
• Dealer type filter — Filter by dealer category (coins, bullion, jewelry, etc.)

---

Data Storage

Dealer records are stored as a custom post type in WordPress:

CPT	suma_dealer
Supports	Title, thumbnail, custom fields
Meta fields	Address, city, state, zip, latitude, longitude, phone, website, dealer categories

Geocoding (latitude/longitude) is performed:

1. When a dealer record is saved in the WP admin
2. The plugin calls the Google Geocoding API to convert the address to coordinates
3. Coordinates are stored in _dealer_lat and _dealer_lng post meta

---

REST API Endpoint

The dealer locator uses a REST API endpoint to fetch nearby dealers:

GET /wp-json/suma/v1/dealer-locator/search

Query Parameters:

Parameter	Type	Description
lat	float	User's latitude
lng	float	User's longitude
radius	int	Search radius in miles (default: 50)
category	string	Dealer category filter (optional)

Response:

{
  "dealers": [
    {
      "id": 42,
      "name": "ABC Coin Shop",
      "address": "123 Main Street",
      "city": "Phoenix",
      "state": "AZ",
      "zip": "85001",
      "phone": "602-555-1234",
      "website": "https://abccoins.example.com",
      "lat": 33.4484,
      "lng": -112.0740,
      "distance_miles": 8.3,
      "categories": ["coins", "bullion"]
    }
  ],
  "total": 1
}

---

Embedding the Map

The dealer locator map is embedded on pages using the [suma_dealer_locator] shortcode:

[suma_dealer_locator]

Optional attributes:

Attribute	Default	Description
default_radius	50	Default search radius in miles
default_lat	33.4484	Default map center latitude (Phoenix, AZ)
default_lng	-112.0740	Default map center longitude
zoom	6	Default map zoom level

---

Configuration

ENV Variable	Description
GOOGLE_MAPS_API_KEY	Google Maps API key (used for map display AND geocoding)

The Google Maps API key must have the following APIs enabled:

• Maps JavaScript API (for the map display)
• Geocoding API (for dealer address geocoding)
• Places API (for location search autocomplete)

tip

Use a separate API key for server-side geocoding vs. frontend map display. Apply API key restrictions:

• Frontend key: HTTP referrer restriction to *.scottsdalemint.com/*
• Server key: IP restriction to WordPress server/Lambda IPs

---

Adding / Editing Dealers

Dealers are managed in the WP admin:

1. Navigate to WP Admin → Dealers → Add New
2. Fill in dealer details (name, address, phone, website)
3. Select dealer categories
4. Click Publish — geocoding runs automatically and stores lat/lng
5. Dealer appears on the map immediately (no cache to clear)

---

Troubleshooting

Issue	Action
Map not displaying	Verify GOOGLE_MAPS_API_KEY is set and Maps JavaScript API is enabled
Dealer not showing on map	Check that lat/lng are saved (_dealer_lat, _dealer_lng post meta); re-save the dealer record
Geocoding failing	Verify Geocoding API is enabled on the Google API key; check API quota
Search not returning nearby dealers	Verify coordinates are correctly stored; check radius parameter