Setting up Google Maps Integration

Setting up Google Maps Integration

ChurchCRM uses Google Maps for two purposes:

1. Geocoding - Converting addresses to latitude/longitude coordinates
2. Map Rendering - Displaying interactive maps in the browser

Prerequisites

• A Google Cloud Platform account
• A project in Google Cloud Console
• Billing enabled on the project (Google provides $200/month free credit)

Step 1: Enable Required APIs

You must enable both APIs in Google Cloud Console:

1. Go to Google Cloud Console - API Library
2. Search for and enable Geocoding API
   • This is used server-side to look up coordinates from addresses
3. Search for and enable Maps JavaScript API
   • This is used client-side to render maps in the browser

Important: Both APIs must be enabled. If you only enable Geocoding API, address lookups will work but maps won't display. If you only enable Maps JavaScript API, maps will load but address geocoding will fail.

Step 2: Create an API Key

1. Go to Google Cloud Console - Credentials
2. Click Create Credentials → API Key
3. Copy the generated API key
4. (Recommended) Click Edit API key to add restrictions:
   • Application restrictions: HTTP referrers (your ChurchCRM domain)
   • API restrictions: Restrict to Geocoding API and Maps JavaScript API

Step 3: Configure ChurchCRM

1. Log in to ChurchCRM as an administrator
2. Go to Admin → System Settings
3. Find the Map Settings section
4. Enter your API key in both fields:
   • sGoogleMapsGeocodeKey - For address geocoding
   • sGoogleMapsRenderKey - For map rendering
5. Click Save Settings

Tip: You can use the same API key for both settings if both services are enabled on that key.

Step 4: Set Church Location

For maps to center correctly:

1. Go to Admin → System Settings
2. Find Church Information section
3. Enter your church's address
4. Set iChurchLatitude and iChurchLongitude (or use "Update All Family Coordinates" to auto-populate)

Step 5: Update Family Coordinates

To geocode all family addresses:

1. Go to People → Family Geographic Utilities (GeoPage.php)
2. Click Update All Family Coordinates
3. Families with valid addresses will have their lat/lng populated

Troubleshooting

"InvalidKeyMapError" in browser console

• Cause: Maps JavaScript API is not enabled
• Solution: Enable "Maps JavaScript API" in Google Cloud Console

Maps load but addresses don't geocode

• Cause: Geocoding API is not enabled
• Solution: Enable "Geocoding API" in Google Cloud Console

"0 families with no Geodata" but coordinates are still blank

• Cause: Geocoding API key is missing or invalid
• Solution: Check sGoogleMapsGeocodeKey in System Settings

API key works locally but not in production

• Cause: API key restrictions don't include your domain
• Solution: Edit the API key in Google Cloud Console and add your production domain to HTTP referrer restrictions

"This API key is not authorized" error

• Cause: API restrictions are too narrow
• Solution: Ensure both Geocoding API and Maps JavaScript API are in the allowed APIs list

Alternative: Bing Maps

ChurchCRM also supports Bing Maps as an alternative geocoder:

1. Get a Bing Maps API key from Bing Maps Portal
2. In System Settings → Map Settings:
   • Set sGeoCoderProvider to "BingMaps"
   • Enter your key in sBingMapKey

Note: Bing Maps is only supported for geocoding, not for map rendering. Map display still requires Google Maps JavaScript API.

Cost Considerations

Google Maps pricing (as of 2024):

• Geocoding API: $5.00 per 1,000 requests (first $200/month free)
• Maps JavaScript API: $7.00 per 1,000 loads (first $200/month free)

For a typical church:

• Family geocoding is one-time per family
• Map loads occur when users view map pages
• Most churches stay well within the free tier

Set up budget alerts to monitor usage.

Related Settings

Setting	Description
sGeoCoderProvider	Choose GoogleMaps or BingMaps for geocoding
sGoogleMapsGeocodeKey	API key for address geocoding
sGoogleMapsRenderKey	API key for map rendering
sBingMapKey	Bing Maps API key (alternative geocoder)
iChurchLatitude	Church latitude for map centering
iChurchLongitude	Church longitude for map centering
iMapZoom	Default zoom level for maps
sGMapIcons	Marker icon names by classification

See Also

• Google Maps Platform Documentation
• Google Cloud Console
• Bing Maps Portal