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
インストール
composer require 'drupal/geocoder:8.x-4.30'
概要
Geocoderモジュールは、Drupalでジオコーディング（住所を地理座標に変換）および逆ジオコーディング（座標を住所に変換）操作を実行するための堅牢なAPIを提供します。Geocoder PHPライブラリバージョン4.xの上に構築されており、30以上の異なるジオコーディングサービスプロバイダーをサポートする柔軟なプラグインベースのアーキテクチャを提供します。
このモジュールには、ジオコーディングプロバイダーの設定、APIキーの管理、キャッシュオプションの設定のための包括的な管理インターフェースが含まれています。結果は、Dumperプラグインシステムを通じてWKT、GeoJSON、KML、GPXなど、さまざまな地理データ形式にエクスポートできます。
サブモジュール（Geocoder Field、Geocoder Geofield、Geocoder Address）により、DrupalのField APIとシームレスに統合され、Entity保存時にテキストフィールドの自動ジオコーディングや地理フィールドの逆ジオコーディングが可能になります。また、プログラムによるジオコーディング操作のためのREST APIエンドポイントも公開しています。
Features
- 順方向ジオコーディング：住所、地名、場所を地理座標（緯度/経度）に変換
- 逆ジオコーディング：地理座標を人間が読める住所に変換
- Google Maps、Nominatim、OpenStreetMap、Bing Maps、MapQuest、Mapboxなど、30以上のジオコーディングサービスプロバイダーをサポート
- Provider、Dumper、Formatterプラグインの拡張可能なプラグインアーキテクチャ
- 複数の出力形式：WKT、GeoJSON、KML、GPX、WKB、プレーンアドレステキスト
- API呼び出しを削減しパフォーマンスを向上させる組み込みキャッシュシステム
- プロバイダーのレート制限を尊重するリクエストスロットリング
- ジオコーディング操作用のREST APIエンドポイント
- 大量のジオコーディング操作のためのQueueベースの処理
- Geocoder Fieldサブモジュールによるentity保存時の自動フィールドジオコーディング
- 地理データの保存のためのGeofieldモジュールとの統合
- 構造化された住所処理のためのAddressモジュールとの統合
- 画像のEXIFデータ、GPX、KML、GeoJSONファイルからのファイルベースのジオコーディング
- ジオコーディング候補による住所入力のオートコンプリート機能
- 近接検索のためのGeofield Proximityソースプラグイン
- プロバイダー固有の設定オプション（APIキー、地域、ロケールなど）のサポート
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.
権限 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.