Geocoder
Un módulo de API de geocodificación completo basado en la biblioteca Geocoder PHP que permite operaciones de geocodificación directa e inversa con soporte para múltiples proveedores de servicios de geocodificación.
geocoder
Install
composer require 'drupal/geocoder:8.x-4.30'
Overview
El módulo Geocoder proporciona una API robusta para realizar operaciones de geocodificación (conversión de direcciones a coordenadas geográficas) y geocodificación inversa (conversión de coordenadas a direcciones) en Drupal. Construido sobre la biblioteca Geocoder PHP versión 4.x, ofrece una arquitectura flexible basada en plugins que soporta más de 30 proveedores de servicios de geocodificación diferentes.
El módulo incluye una interfaz administrativa completa para configurar proveedores de geocodificación, gestionar claves API y establecer opciones de caché. Los resultados pueden exportarse a varios formatos de datos geográficos incluyendo WKT, GeoJSON, KML, GPX y más a través de su sistema de plugins Dumper.
Con sus submódulos (Geocoder Field, Geocoder Geofield y Geocoder Address), proporciona integración perfecta con la Field API de Drupal, permitiendo geocodificación automática de campos de texto y geocodificación inversa de campos geográficos durante las operaciones de guardado de entidades. El módulo también expone endpoints de REST API para operaciones de geocodificación programáticas.
Features
- Geocodificación directa: Convierte direcciones, nombres de lugares y ubicaciones a coordenadas geográficas (latitud/longitud)
- Geocodificación inversa: Convierte coordenadas geográficas a direcciones legibles
- Soporte para más de 30 proveedores de servicios de geocodificación incluyendo Google Maps, Nominatim, OpenStreetMap, Bing Maps, MapQuest, Mapbox y muchos más
- Arquitectura de plugins extensible para plugins de Provider, Dumper y Formatter
- Múltiples formatos de salida: WKT, GeoJSON, KML, GPX, WKB y texto de dirección simple
- Sistema de caché integrado para reducir llamadas a la API y mejorar el rendimiento
- Limitación de solicitudes para respetar los límites de tasa de los proveedores
- Endpoints de REST API para operaciones de geocodificación
- Procesamiento basado en colas para operaciones de geocodificación de alto volumen
- Geocodificación automática de campos al guardar entidades a través del submódulo Geocoder Field
- Integración con el módulo Geofield para almacenamiento de datos geográficos
- Integración con el módulo Address para manejo de direcciones estructuradas
- Geocodificación basada en archivos desde datos EXIF en imágenes, archivos GPX, KML y GeoJSON
- Funcionalidad de autocompletado para entrada de direcciones con sugerencias de geocodificación
- Plugin de origen Geofield Proximity para búsquedas por proximidad
- Soporte para opciones de configuración específicas del proveedor (claves API, regiones, idiomas, etc.)
Use Cases
Almacenar coordenadas de ubicación a partir de una dirección
Configure un Geofield en su tipo de contenido para geocodificar automáticamente desde un campo de texto de dirección. Cuando los usuarios ingresan una dirección, las coordenadas se almacenan automáticamente en el Geofield. Habilite los submódulos geocoder_field y geocoder_geofield, agregue un campo de texto para la entrada de dirección y un Geofield para las coordenadas, luego configure los ajustes de Geocode del Geofield para geocodificar desde el campo de dirección usando su proveedor preferido.
Mostrar direcciones legibles desde ubicaciones del mapa
Use la geocodificación inversa para mostrar direcciones formateadas a partir de coordenadas almacenadas. Configure un campo de texto para geocodificar inversamente desde un Geofield. Cuando se guardan las coordenadas (por ejemplo, desde un widget de mapa), la dirección se completa automáticamente.
Extraer coordenadas GPS de fotos subidas
Extraiga automáticamente datos de ubicación de fotos con información GPS incrustada. Suba imágenes con datos GPS EXIF, y el proveedor File geocoder extraerá las coordenadas y las almacenará en un Geofield.
Crear una búsqueda por proximidad con autocompletado de direcciones
Cree un filtro expuesto de Views usando la fuente de proximidad 'Geocode Origin'. Los usuarios pueden escribir una dirección con sugerencias de autocompletado, y los resultados se ordenan por distancia desde esa ubicación.
Geocodificar direcciones mediante REST API
Use el endpoint /geocoder/api/geocode para geocodificar direcciones programáticamente. Pase la dirección y el/los proveedor(es) como parámetros de consulta, reciba resultados JSON con coordenadas y componentes de dirección. Útil para aplicaciones JavaScript o integraciones externas.
Geocodificar contenido existente en lotes
Habilite el procesamiento de cola en la configuración de Geocoder, luego active los guardados en el contenido existente. La geocodificación se procesará mediante cron, evitando tiempos de espera agotados para grandes conjuntos de datos. Monitoree la cola 'geocoder_field' para ver el progreso.
Importar datos de rutas GPX/KML
Suba archivos GPX o KML que contengan datos de rutas y extraiga automáticamente la información geográfica en valores Geofield. Útil para importar senderos, rutas de entrega o datos de límites.
Tips
- Para sitios en producción, siempre configure el almacenamiento en caché para reducir costos de API y mejorar el rendimiento. Considere usar el módulo Permanent Cache Bin para persistir los resultados en caché.
- Al usar proveedores gratuitos como Nominatim, respete los límites de tasa configurando la limitación (por ejemplo, 1 solicitud cada 2 segundos). Nominatim tiene limitación predeterminada incorporada.
- Pruebe la geocodificación con los endpoints de API antes de configurar la integración de campos: /geocoder/api/geocode?address=SU_DIRECCION&geocoder=SU_PROVEEDOR
- Configure múltiples proveedores como respaldo - se usará el primer proveedor que devuelva resultados, los demás se intentan si falla.
- Para migraciones de contenido, habilite temporalmente 'Geocoder Presave Disabled' para evitar la geocodificación durante la importación, luego procese la geocodificación por separado.
- Use la opción 'Skip Geocode if target value is not empty' para preservar coordenadas ingresadas manualmente mientras sigue geocodificando automáticamente el contenido nuevo.
- El formato de salida del dumper WKT generalmente se requiere al almacenar resultados en Geofield, mientras que GeoJSON se necesita para campos Address.
- Para Google Maps, use una clave API sin restricciones de referente ya que la geocodificación del lado del servidor no expondrá la clave en el navegador.
- Habilite el procesamiento de cola para sitios de alto tráfico para evitar que las operaciones de guardado se retrasen por llamadas API externas.
Technical Details
Admin Pages 3
/admin/config/system/geocoder
Configura los ajustes globales del módulo Geocoder, incluyendo el comportamiento de caché, el procesamiento de colas y la capacidad de deshabilitar globalmente las operaciones de geocodificación.
/admin/config/system/geocoder/geocoder-provider
Gestiona los proveedores de geocodificación. Añade nuevos proveedores seleccionando un tipo de proveedor del menú desplegable y configurando sus ajustes. Visualiza, edita y elimina proveedores existentes. Los proveedores deben crearse aquí antes de poder utilizarse para operaciones de geocodificación.
/admin/config/system/geocoder/geocoder-provider/add/{geocoder_provider_id}
Configura un nuevo proveedor de Geocoder. Los ajustes varían según el tipo de proveedor, pero típicamente incluyen claves API, regiones, agentes de usuario y otras opciones específicas del proveedor.
Permissions 2
Hooks 10
hook_geocode_address_string_alter
Permite a los módulos modificar la cadena de dirección antes de que sea geocodificada.
hook_geocode_address_geocode_query
Permite a los módulos modificar el objeto GeocodeQuery antes de la geocodificación.
hook_reverse_geocode_coordinates_alter
Permite a los módulos modificar las coordenadas de latitud y longitud antes de la geocodificación inversa.
hook_geocode_country_code_alter
Permite a los módulos modificar el código de país extraído de los resultados de geocodificación. Útil cuando los proveedores no devuelven códigos de país estándar.
hook_geocoder_provider_info_alter
Permite a los módulos modificar la lista de plugins de proveedores de geocodificación disponibles. La implementación predeterminada elimina los plugins cuyas clases de controlador no están instaladas.
hook_geocode_source_fields_alter
Modifica la lista de tipos de Field que pueden usarse como fuentes para operaciones de geocodificación. Proporcionado por el submódulo geocoder_field.
hook_reverse_geocode_source_fields_alter
Modifica la lista de tipos de Field que pueden usarse como fuentes para operaciones de geocodificación inversa. Proporcionado por el submódulo geocoder_field.
hook_geocode_entity_field_address_string_alter
Modifica la cadena de dirección a geocodificar en el presave de Entity. Proporcionado por el submódulo geocoder_field.
hook_reverse_geocode_entity_field_coordinates_alter
Modifica las coordenadas antes de la geocodificación inversa en el presave de Entity. Proporcionado por el submódulo geocoder_field.
hook_geocoder_address_values_alter
Modifica los valores de dirección antes de la geocodificación. Proporcionado por el submódulo geocoder_address.
Troubleshooting 7
Asegúrese de que el paquete Composer del proveedor esté instalado. Por ejemplo, para Google Maps: composer require geocoder-php/google-maps-provider. Verifique la carpeta src/Plugin/Geocoder/Provider del módulo - solo los proveedores con plugins allí son compatibles.
Revise los registros de Drupal para mensajes de error detallados. Verifique que las claves API sean correctas y no estén limitadas por tasa. Para Nominatim/OpenStreetMap, asegúrese de que los encabezados User-Agent y Referer estén configurados. Pruebe primero con una dirección más simple y conocida.
Habilite el almacenamiento en caché en la configuración de Geocoder para evitar llamadas API repetidas. Para operaciones masivas, habilite el procesamiento de cola. Considere usar el módulo Permanent Cache Bin para persistir el caché entre limpiezas de caché.
Algunos proveedores devuelven datos incompletos (códigos de país faltantes, códigos postales, etc.). Use el hook hook_geocode_country_code_alter para corregir problemas de códigos de país. Verifique que el dumper seleccionado (GeoJSON para campos Address) sea compatible con el campo de destino.
Verifique que 'Geocoder Presave Disabled' no esté marcado en la configuración. Confirme que los ajustes de Geocode del campo estén configurados con al menos un proveedor seleccionado. Compruebe que el campo de origen tenga un valor y no haya permanecido sin cambios desde el último guardado.
Configure la limitación en los ajustes del proveedor (período y límite). Use el almacenamiento en caché para reducir las llamadas API. Considere habilitar el procesamiento de cola para distribuir las solicitudes en el tiempo mediante cron.
Configure los ajustes de proxy en settings.php: $settings['http_client_config']['proxy']. El servicio geocoder.http_adapter usa Guzzle que respeta estos ajustes.
Security Notes 5
- Las claves API para proveedores de geocodificación se almacenan en la configuración. Use anulaciones de settings.php específicas del entorno para mantener las claves de producción fuera del control de versiones.
- El permiso 'access geocoder api endpoints' controla el acceso a la REST API. Solo otórguelo a roles de confianza ya que consume cuota de API.
- Considere usar el módulo COI (Config Override Inspector) para ocultar las claves API en la interfaz de administración cuando están anuladas en settings.php.
- Al exponer la funcionalidad de autocompletado a usuarios anónimos, tenga en cuenta el potencial abuso de cuota de API. Configure la limitación y considere implementar limitación de tasa adicional.
- Los resultados de geocodificación pueden contener datos de ubicación personal. Asegure controles de acceso adecuados en los campos que almacenan datos geocodificados y considere las implicaciones del RGPD.