Build maps and proximity search
Use Proximity to filter by distance from a visitor-entered place. Use Map to display result locations and, optionally, narrow results to the visible bounds.
Prerequisites
- Open Settings → POM Theme → Integrations → Google Maps.
- Enter the Google Maps browser API key.
- Restrict the production key by allowed HTTP referrers and the Google Maps APIs the site requires.
- Ensure published items have valid coordinates.
The theme loads the Maps API only when a configured proximity or map facet needs it.
Choose the location source
For Map, choose Location adapter:
- Latitude/longitude meta pair and enter Latitude meta key plus Longitude meta key;
- Theme locations repeater and choose Primary marker only or All locations.
Latitude must be between -90 and 90; longitude between -180 and 180. With primary mode, POM uses the first valid primary location, or the first valid location when none is marked primary.
Configure proximity
Add a Proximity facet with a Location source. Set:
- Unit to Kilometres or Miles;
- Default radius;
- Minimum radius and Maximum radius;
- Radius step.
The public control uses Google place suggestions, stores coordinates, and displays a numeric radius field plus Clear location. Distance sorting becomes useful after a location has been selected.
Configure the map
Important choices include:
- Marker scope: all filtered results or the current page;
- Locations: primary marker only or all locations;
- Initial view and After filtering;
- Bounds filtering: off, Search this area button, or automatic;
- Other facet changes: preserve or reset map bounds;
- Maximum markers, Clustering, and map height;
- synchronization between cards and markers.
Use Search this area button when visitors should move the map freely before changing results. Automatic bounds filtering should use a sensible debounce.
Verify the experience
Test items with one location, several locations, and no valid location. Confirm marker-to-card and card-to-marker interactions if enabled, reset map area, proximity clearing, distance sort, filtered URL restoration, mobile height, and keyboard access to the equivalent result cards.