Skip to content

Mapping and Geocoding

You can configure mapping and geocoding providers by visiting Administer > System Settings > Mapping and Geocoding.

Mapping Provider
Select the service used to build and display the maps shown in the CiviCRM UI.

Mapping Provider Key
Enter your API Key or Application ID for the selected mapping provider. For Google Maps, refer to developers.google.com for the latest information. For OpenStreetMaps, you now require an API key from CARTO.

API Key for OpenStreetMaps usage

Maps under OpenStreetMaps rely on images from CARTO, which requires an API key. Without a valid API key, your maps may be repeatedly overlaid with an "API KEY REQUIRED" watermark. See CARTO's documentation for information on API keys for CARTO.

Geocoding Provider
Select the service used to lookup latitude and longditude for contact addresses, so they can be shown on maps.

Geo Provider Key
Enter the API key as required by your GeoCoding provider.

Click Save to save your action or Cancel to cancel it.

If successful you will see the message "Your changes have been saved."

Internal Server and/or Firewall Issues

If CiviCRM is installed on a server which does not have access to the public internet or there is a firewall which prevents CiviCRM from communicating with your chosen web services - you will see one or more fatal errors when attempting to add or edit contact records. You will need to either disable Mapping and Geocoding - or resolve the connectivity issue to resolve this.

After enabling the mapping provider, you should configure the job.geocode scheduled job which will geocode addresses without a latitude and longditude according to the configured options.

Usage Limits

Some providers have usage limits on their Mapping and Geocoding APIs. If you go over the limits you may receive a overlimit error when trying to save an address.

Alternative Geocoding providers

If you need to use an alternative Gecoding Provider, you may wish to evaluate the following extension which includes many improvements: https://civicrm.org/extensions/geocoder