Improved geocoding in CiviCRM

Photo by W.carter, CC0.

new geocoder extension released by the Wikimedia Foundation addresses some of the geocoding issues experienced by CiviCRM users. This is timely for CiviCRM users using Google as their geocoding provider who are considering how Google changes to its service affect them and whether they are operating within Google’s terms of service.

Geocoding is the process of getting latitude and longitude data (and sometimes other data) for addresses stored in the CiviCRM database. Usually this is done by using an outside service provider,with Google being the most common. However, we strive to use open source service providers that align with our commitment to privacy where possible. In this case we opted to use a locally stored open source data set. We initially set up a custom mechanism for updating from this data but found that it was then not available in various search functions. So we decided to tackle our need in a generic way and make it available to the community at large.

Our geocoding extension uses a generic library which potentially offers many providers, but the ones currently available are OpenStreetMap, MapQuest, and Google Maps and a local look up table.


  • No more fatal errors if you exceed your geocoding quota!
  • You can now configure multiple geocoder providers – if one does not provide coordinates then it will try the next one
  • You can look up a local database for coordinates by postal code for configured countries
  • You now have control over what other data from the provider is retained (e.g timezone, city might be known for an address by them but not by your site).

In general the configuration is available via the API rather than a form. But for most sites the default config will be fine – it is:

Default provider:  OpenStreetMap unless you were already using Google, in which case it will continue to use Google. OpenStreetMap  is an open data provider and does not require any API keys.

Fallback provider: If you are already using Google then OpenStreetMap will be configured as a fallback provider, and used if you exceed your limit with Google or it cannot be found by Google. In both cases a further fall back for US sites is a postal code lookup.

Data retention:  By default any lookups using the DB table will store timezone in addition to latitude and longitude. They will also ‘fill’ State & City if they are not already known.


We needed to clean up the core CiviCRM code to remove some blockers to this extension. Ginkgo Street Labs collaborated with us on that.

Other Wikimedia Foundation extensions

Some other CiviCRM extensions that we have not promoted to date:

Unsubscribe email: creates a screen for doing data-entry on unsubscribe requests

Contact editor provides a menu action on the contact summary screen to change contact type (e.g when an Organization was mis-entered as an individual)

RIP: add opt out flag on deceased contacts

Eileen McNaughton, Software Engineer, Fundraising Tech
Wikimedia Foundation


Read further in the pursuit of knowledge

New interaction timeline improves investigation of harassment cases

The new interaction timeline tool is a way to look at two contributors’ editing history—where they have interacted, when, and how often. This can help add clarity when reviewing reports of harassment and abuse, and takes some of the burden off both the people reviewing problems, and the people reporting them.

Read more

What should journalists know about Wikipedia? A Poynter Institute NewsU webinar

Join us for a Poynter Institute NewsU webinar to help journalists around the world better understand Wikipedia. Here's some additional details on what we're going to talk about on July 12.

Read more

California Supreme Court upholds critical intermediary liability provision

In a well-reasoned opinion, the California Supreme Court recognized that CDA 230 offers broad protection to sites like Yelp from liability for user-created content.

Read more

Help us unlock the world’s knowledge.

As a nonprofit, Wikipedia and our related free knowledge projects are powered primarily through donations.

Donate now

Contact us

Questions about the Wikimedia Foundation or our projects? Get in touch with our team.

Photo credits