Skip to main content

Google Maps Setup

Multiforum supports Google Maps integration for event locations. Users can search for venues, display event locations on maps, and discover nearby events.

Features​

With Google Maps enabled:

  • Location Search - Search for venues when creating events
  • Place Autocomplete - Get address suggestions as you type
  • Map Display - Show event locations on interactive maps
  • Marker Clustering - Group nearby events on map views
  • Directions - Link to Google Maps for navigation

Setting Up Google Maps​

1. Create a Google Cloud Project​

  1. Go to Google Cloud Console
  2. Create a new project or use an existing one

2. Enable Required APIs​

Enable the following APIs in your project:

  1. Go to APIs & Services → Library
  2. Search for and enable:
    • Maps JavaScript API - For displaying maps
    • Places API - For location search and autocomplete
    • Geocoding API - For converting addresses to coordinates

3. Create an API Key​

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → API Key
  3. Note your API key

For security, restrict your API key:

Application Restrictions:

  • Select HTTP referrers (web sites)
  • Add your frontend domain: https://your-domain.com/*

API Restrictions:

  • Select Restrict key
  • Choose: Maps JavaScript API, Places API, Geocoding API

5. Create a Map ID (Optional)​

For custom map styling:

  1. Go to Google Maps Platform → Map Styles
  2. Click Create Style
  3. Customize your map appearance
  4. Create a Map ID and note it

Environment Variables​

Add these to your frontend configuration:

VITE_GOOGLE_MAPS_API_KEY=your-api-key
VITE_GOOGLE_MAP_ID=your-map-id  # Optional, for custom styling

Optional: OpenCage Geocoding​

For additional geocoding capabilities (reverse geocoding, address parsing), you can add OpenCage:

  1. Create an account at OpenCage
  2. Get your API key
  3. Add to environment:
VITE_OPEN_CAGE_API_KEY=your-opencage-key

Event Location Features​

Creating Events with Locations​

When Google Maps is configured, users can:

  1. Search for a venue - Type a venue name or address
  2. Select from suggestions - Google Places provides autocomplete
  3. Add virtual event URLs - For online events
  4. Mark private residences - Hide exact address for privacy

Event Data Model​

Events store location information:

FieldDescription
locationNameVenue name (e.g., "Coffee Shop")
addressFull street address
placeIdGoogle Places ID for the venue
locationGeographic coordinates (Point type)
virtualEventUrlURL for online events
isInPrivateResidenceFlag to hide exact address

Recurring Events​

Event series can share location information:

  • Set location once on the series
  • All occurrences inherit the location
  • Individual events can override the series location

Map Display Features​

Event List Maps​

When viewing events in a channel or search results:

  • Map shows all event locations as markers
  • Clicking a marker shows event preview
  • Marker clustering groups nearby events

Single Event Maps​

When viewing a single event:

  • Map centers on the event location
  • Address is displayed
  • Link to open in Google Maps for directions

Map Clustering​

For pages with many events, markers are automatically clustered:

  • Clusters show event count
  • Clicking a cluster zooms in
  • Individual markers appear at higher zoom levels

Privacy Considerations​

Private Residence Events​

For events at private homes:

  1. Host marks event as "private residence"
  2. Exact address is hidden from non-attendees
  3. General area may still be shown on map
  4. Full address shared only with confirmed attendees

Location Accuracy​

  • Google Places provides standardized addresses
  • Coordinates are stored for map display
  • Users can optionally hide their location

Troubleshooting​

Maps Not Loading​

  1. Verify API key is correct
  2. Check API key restrictions allow your domain
  3. Ensure Maps JavaScript API is enabled
  4. Check browser console for error messages

Places Autocomplete Not Working​

  1. Verify Places API is enabled
  2. Check API key has access to Places API
  3. Ensure you're using HTTPS (required by Google)

Geocoding Failures​

  1. Verify Geocoding API is enabled
  2. Check you haven't exceeded API quotas
  3. Some addresses may not geocode accurately

API Quota Issues​

Google Maps has usage quotas:

  • Monitor usage in Cloud Console
  • Set budget alerts
  • Consider enabling billing for higher limits

Cost Considerations​

Google Maps APIs have usage-based pricing:

APIFree TierAfter Free Tier
Maps JavaScript28,000 loads/month$7 per 1,000
Places10,000 requests/month$17 per 1,000
Geocoding40,000 requests/month$5 per 1,000

Most small to medium Multiforum instances will stay within free tier limits.