This extension exposes multiple geocoder providers to CiviCRM for the purpose of retrieving additional information about addresses when entered into CiviCRM. It does this using a generic geocoder library (which itself supports multiple providers) .
Note that the terms of data use by geocoding providers varies and it is your responsibility to understand and adhere to them.
Currently enabled geocoders are
- OpenStreetMap - this is zero-config & is enabled as the default (lowest weight)on install if you have no existing mapping provider
- USZipGeocoder - this is enabled on install & has no config. It will work as a fallback for US addresses only.
- MapQuest - requires an API key to be used
- GoogleMaps - requires an API key to be used - this is enabled on install as the default if you already have google configured as your provider. However the Terms of service suggest it may not be a good choose https://support.google.com/code/answer/55180?hl=en
- GeoName DB geocoder - this requires that you get a sample dataset from geonames. I will require a developer or similar to tweak the download into an sql table. There is a sample dataset for New Zealand in the install directory & if loaded it will work for New Zealand.
- Here (not enabled by default)
- Addok (not enabled by default)
- German Postalcode - see Readme
Features
- Multiple providers can be configured for a site with different ones being used for different countries.
- Provider fall over. If a provider is not valid (e.g because the quota was hit or it only does a particular country or it's required fields are not present) then the next geocoder (by weight) will be used.
- Threshold standdown period. If the geocoding quota is hit for a provider it is not used again until the standdown has expired. By default the standdown is 1 minute but it is configurable per geocoder instance.
- Database table based geocoding. If you do not wish to interact with an external site then a US zip table lookup is available (from CiviSpace). It is possible to download other datasets (e.g from geonames) & upload & use them but that requires some more config.
- Datafill fields. Each geocoder is configured with 2 sets of fields to retain
- 'retained_response_fields' - these overwrite the existing fields for the address - usually latitude & longitude
- 'data fill fields' - these are added to the existing fields if the existing field is not set (usually things like city, postal_code, state or county - you should check your provider's terms of services for what you can store)
- other providers from https://github.com/geocoder-php/Geocoder#providers can be added easily
Limitations
Configuration beyond the default config needs to be done via the api
Default Config
On installation the following will be configured
1) OpenStreetMap (Nominatim) provider will be enabled, as will a db-based postal code based look up for US postal codes.
2) OpenStreetMap will be configured as the top priority provider and the db-based postal code look up will be a fall back for US addresses
3) If you already have Google as your geocoder it will be enabled (copying over your existing api key) and put at the front of the fall back chain (ie. the other 2 will only be used if the google look up does not find something)
4) The DB-based postal code lookup provider is configured to update the timezone field on the address (in addition to latitude and longitude). I will also 'fill' data about the city & state if not present from that table.
