Geocoder
A comprehensive geocoding API module based on the Geocoder PHP library that enables forward and reverse geocoding operations with support for multiple geocoding service providers.
geocoder
Install
composer require 'drupal/geocoder:8.x-4.30'
Overview
The Geocoder module provides a robust API for performing geocoding (converting addresses to geographic coordinates) and reverse geocoding (converting coordinates to addresses) operations in Drupal. Built on top of the Geocoder PHP library version 4.x, it offers a flexible plugin-based architecture that supports over 30 different geocoding service providers.
The module includes a comprehensive administrative interface for configuring geocoding providers, managing API keys, and setting up caching options. Results can be exported to various geographic data formats including WKT, GeoJSON, KML, GPX, and more through its Dumper plugin system.
With its submodules (Geocoder Field, Geocoder Geofield, and Geocoder Address), it provides seamless integration with Drupal's Field API, allowing automatic geocoding of text fields and reverse geocoding of geographic fields during entity save operations. The module also exposes REST API endpoints for programmatic geocoding operations.
Features
- Forward geocoding: Convert addresses, place names, and locations to geographic coordinates (latitude/longitude)
- Reverse geocoding: Convert geographic coordinates to human-readable addresses
- Support for 30+ geocoding service providers including Google Maps, Nominatim, OpenStreetMap, Bing Maps, MapQuest, Mapbox, and many more
- Extensible plugin architecture for Provider, Dumper, and Formatter plugins
- Multiple output formats: WKT, GeoJSON, KML, GPX, WKB, and plain address text
- Built-in caching system to reduce API calls and improve performance
- Request throttling to respect provider rate limits
- REST API endpoints for geocoding operations
- Queue-based processing for high-volume geocoding operations
- Automatic field geocoding on entity save through the Geocoder Field submodule
- Integration with Geofield module for storing geographic data
- Integration with Address module for structured address handling
- File-based geocoding from EXIF data in images, GPX, KML, and GeoJSON files
- Autocomplete functionality for address input with geocoding suggestions
- Geofield Proximity source plugin for proximity searches
- Support for provider-specific configuration options (API keys, regions, locales, etc.)
Use Cases
Store location coordinates from address input
Configure a Geofield on your content type to automatically geocode from a text address field. When users enter an address, the coordinates are automatically stored in the Geofield. Enable geocoder_field and geocoder_geofield submodules, add a text field for address input and a Geofield for coordinates, then configure the Geofield's Geocode settings to geocode from the address field using your preferred provider.
Display human-readable addresses from map locations
Use reverse geocoding to display formatted addresses from stored coordinates. Configure a text field to reverse geocode from a Geofield. When coordinates are saved (e.g., from a map widget), the address is automatically populated.
Extract GPS coordinates from uploaded photos
Automatically extract location data from photos with embedded GPS information. Upload images with EXIF GPS data, and the File geocoder provider will extract coordinates and store them in a Geofield.
Build a proximity search with address autocomplete
Create a Views exposed filter using the 'Geocode Origin' proximity source. Users can type an address with autocomplete suggestions, and results are sorted by distance from that location.
Geocode addresses via REST API
Use the /geocoder/api/geocode endpoint to geocode addresses programmatically. Pass the address and provider(s) as query parameters, receive JSON results with coordinates and address components. Useful for JavaScript applications or external integrations.
Batch geocode existing content
Enable queue processing in Geocoder settings, then trigger saves on existing content. Geocoding will be processed via cron, avoiding timeouts for large datasets. Monitor the 'geocoder_field' queue for progress.
Import GPX/KML track data
Upload GPX or KML files containing route data and automatically extract the geographic information into Geofield values. Useful for importing hiking trails, delivery routes, or boundary data.
Tips
- For production sites, always configure caching to reduce API costs and improve performance. Consider using the Permanent Cache Bin module to persist cached results.
- When using free providers like Nominatim, respect rate limits by configuring throttling (e.g., 1 request per 2 seconds). Nominatim has built-in default throttling.
- Test geocoding with the API endpoints before configuring field integration: /geocoder/api/geocode?address=YOUR_ADDRESS&geocoder=YOUR_PROVIDER
- Configure multiple providers as fallbacks - the first provider returning results will be used, others are tried if it fails.
- For content migrations, temporarily enable 'Geocoder Presave Disabled' to prevent geocoding during import, then process geocoding separately.
- Use the 'Skip Geocode if target value is not empty' option to preserve manually-entered coordinates while still auto-geocoding new content.
- The WKT dumper output format is typically required when storing results in Geofield, while GeoJSON is needed for Address fields.
- For Google Maps, use an API key without referrer restrictions since server-side geocoding won't expose the key in the browser.
- Enable queue processing for high-traffic sites to prevent save operations from being delayed by external API calls.
Technical Details
Admin Pages 3
/admin/config/system/geocoder
Configure global settings for the Geocoder module including caching behavior, queue processing, and the ability to globally disable geocoding operations.
/admin/config/system/geocoder/geocoder-provider
Manage geocoding providers. Add new providers by selecting a provider type from the dropdown and configuring its settings. View, edit, and delete existing providers. Providers must be created here before they can be used for geocoding operations.
/admin/config/system/geocoder/geocoder-provider/add/{geocoder_provider_id}
Configure a new geocoder provider. Settings vary by provider type but typically include API keys, regions, user agents, and other provider-specific options.
Permissions 2
Hooks 10
hook_geocode_address_string_alter
Allows modules to alter the address string before it is geocoded.
hook_geocode_address_geocode_query
Allows modules to alter the GeocodeQuery object before geocoding.
hook_reverse_geocode_coordinates_alter
Allows modules to alter latitude and longitude coordinates before reverse geocoding.
hook_geocode_country_code_alter
Allows modules to alter the country code extracted from geocoding results. Useful when providers don't return standard country codes.
hook_geocoder_provider_info_alter
Allows modules to alter the list of available geocoder provider plugins. The default implementation removes plugins whose handler classes are not installed.
hook_geocode_source_fields_alter
Alters the list of field types that can be used as sources for geocoding operations. Provided by geocoder_field submodule.
hook_reverse_geocode_source_fields_alter
Alters the list of field types that can be used as sources for reverse geocoding operations. Provided by geocoder_field submodule.
hook_geocode_entity_field_address_string_alter
Alters the address string to geocode on entity presave. Provided by geocoder_field submodule.
hook_reverse_geocode_entity_field_coordinates_alter
Alters coordinates before reverse geocoding on entity presave. Provided by geocoder_field submodule.
hook_geocoder_address_values_alter
Alters address values before geocoding. Provided by geocoder_address submodule.
Troubleshooting 7
Ensure the provider's Composer package is installed. For example, for Google Maps: composer require geocoder-php/google-maps-provider. Check the module's src/Plugin/Geocoder/Provider folder - only providers with plugins there are supported.
Check the Drupal logs for detailed error messages. Verify API keys are correct and not rate-limited. For Nominatim/OpenStreetMap, ensure User-Agent and Referer headers are configured. Test with a simpler, well-known address first.
Enable caching in Geocoder settings to avoid repeated API calls. For bulk operations, enable queue processing. Consider using the Permanent Cache Bin module to persist cache across cache clears.
Some providers return incomplete data (missing country codes, postal codes, etc.). Use the hook_geocode_country_code_alter hook to fix country code issues. Check that your selected dumper (GeoJSON for Address fields) is compatible with the target field.
Check that 'Geocoder Presave Disabled' is not checked in settings. Verify the field's Geocode settings are configured with at least one provider selected. Check the source field has a value and hasn't been unchanged since last save.
Configure throttling in the provider settings (period and limit). Use caching to reduce API calls. Consider enabling queue processing to spread requests over time via cron.
Configure proxy settings in settings.php: $settings['http_client_config']['proxy']. The geocoder.http_adapter service uses Guzzle which respects these settings.
Security Notes 5
- API keys for geocoding providers are stored in configuration. Use environment-specific settings.php overrides to keep production keys out of version control.
- The 'access geocoder api endpoints' permission controls access to the REST API. Only grant to trusted roles as it consumes API quota.
- Consider using the COI (Config Override Inspector) module to hide API keys in the admin interface when they are overridden in settings.php.
- When exposing autocomplete functionality to anonymous users, be aware of potential API quota abuse. Configure throttling and consider implementing additional rate limiting.
- Geocoding results may contain personal location data. Ensure proper access controls on fields storing geocoded data and consider GDPR implications.