Sugerencias de dirección con Google Places en campos de entrada personalizados

PLUS

El autocompletado de direcciones que WP-ImmoMakler utiliza en la búsqueda por radio está disponible a partir de la versión 5.60.0 como biblioteca reutilizable en cualquier campo de entrada de su sitio web. Puede utilizarlo, por ejemplo, para equipar un formulario de contacto, un buscador de agentes inmobiliarios o un filtro personalizado con las mismas sugerencias — incluida la navegación por teclado, caché y protección de su clave de API de Google.

Requisitos previos

Para que la biblioteca se active en una página, deben cumplirse los siguientes requisitos:

Usted utiliza la edición Plus de WP-ImmoMakler.
Los servicios de Google están activados en el backend de WordPress (wp-admin) bajo WP-ImmoMakler → Integraciones → Servicios de geolocalización y se ha introducido una clave de API de Google Maps Geocoding válida.

Si se cumplen ambas condiciones, WP-ImmoMakler carga automáticamente el script assets-plus/js/places-autocomplete.js en cada página del frontend (diferido). Si el script no encuentra ningún campo de entrada coincidente en la página, no tiene ningún efecto adicional — no se generan solicitudes a Google.

Variante 1: mediante atributo HTML (recomendado)

Añada el atributo data-immomakler-autocomplete a un elemento <input>. La biblioteca detecta el campo automáticamente y se vincula a él:

<input
  type="text"
  name="direccion"
  placeholder="Código postal, ciudad o calle"
  data-immomakler-autocomplete
  autocomplete="off"
>

Cuando el usuario selecciona una sugerencia, WP-ImmoMakler inserta el texto de dirección formateado en el campo y dispara un CustomEvent con el nombre immomakler:place-selected en el mismo elemento. El evento contiene el texto de dirección (label) y el ID de lugar de Google (placeId) en el objeto detail:

const input = document.querySelector('input[name="direccion"]');
input.addEventListener('immomakler:place-selected', (event) => {
  console.log(event.detail.label);   // "Calle Principal 1, 20095 Hamburgo, Alemania"
  console.log(event.detail.placeId); // "ChIJ..."
});

Variante 2: mediante API de JavaScript

Si el campo de entrada se inserta dinámicamente en la página (por ejemplo, en un formulario abierto en un modal), vincule la biblioteca de forma explícita:

const input = document.getElementById('mi-campo-direccion');
window.ImmoMaklerPlacesAutocomplete.attach(input, {
  minLength: 4,        // Número mínimo de caracteres antes de la primera solicitud (por defecto: 3)
  maxResults: 5,       // Número máximo de sugerencias (por defecto: 8)
  debounceMs: 200      // Retraso de escritura en milisegundos (por defecto: 140)
});

Para eliminar el vínculo — por ejemplo, al cerrar un modal — utilice detach:

window.ImmoMaklerPlacesAutocomplete.detach(input);

attach y detach aceptan tanto un elemento DOM como un selector CSS.

Opciones por campo de entrada como JSON

También puede especificar las opciones de la Variante 2 directamente en el atributo data-immomakler-autocomplete en formato JSON:

<input
  type="text"
  name="direccion"
  data-immomakler-autocomplete='{"minLength": 4, "maxResults": 5}'
>

Cómo se procesan las solicitudes

WP-ImmoMakler ofrece tres formas para que el script del navegador obtenga las sugerencias de dirección — una rápida y dos que pasan por toda la pila de WordPress:

Proxy Fast-API (por defecto, rápido). Un script PHP independiente en wp-content/cache/immomakler/fast-api/immomakler-autocomplete.php que no carga WordPress. Verifica un token HMAC firmado, realiza una comprobación same-origin y un límite de velocidad por IP, llama a Google Places mediante cURL y devuelve JSON. Una solicitud suele tardar 5–15 ms en lugar de 100–500 ms (arranque de WordPress con todos los plugins activos).
Endpoint REST (alternativa). POST /wp-json/immomakler/v1/places/autocomplete — se ejecuta a través de index.php, pasa por los hooks habituales y devuelve las mismas sugerencias.
Endpoint admin-ajax (segunda alternativa). POST /wp-admin/admin-ajax.php?action=immomakler_places_autocomplete — interviene cuando la API REST no está disponible en el sitio (por ejemplo, porque ha sido desactivada por un plugin o un filtro).

El script del navegador intenta primero la ruta 1, luego recurre automáticamente a la ruta 2 y finalmente a la ruta 3. El resultado funcional es idéntico para el usuario final; solo difiere la latencia.

Sesiones (token de sesión)

Con cada solicitud, el script del navegador envía un token de sesión. Este agrupa las solicitudes de una misma búsqueda. Mapbox factura las sugerencias de dirección por sesión. Google también recomienda el uso de sesiones, pero solo las factura como sesión si esta se completa con una solicitud de detalles de lugar (Place Details). WP-ImmoMakler no realiza dicha solicitud, por lo que Google factura cada solicitud de sugerencia de forma individual.

A partir de la versión 5.70.0, un token es válido para exactamente una búsqueda: finaliza en cuanto el visitante selecciona una sugerencia o envía el formulario, y también tras tres minutos sin ninguna solicitud. La siguiente entrada inicia entonces una nueva sesión. El token reside únicamente en la memoria de la página, por lo que cada carga de página comienza con uno nuevo. Hasta la versión 5.69, un único token era válido para todas las búsquedas dentro de una misma pestaña del navegador.

Desactivar el proxy Fast-API

Si sus políticas de cumplimiento o seguridad requieren que no haya archivos PHP ejecutables fuera del arranque habitual de WordPress, puede desactivar el proxy Fast-API en el backend de WordPress (wp-admin) bajo WP-ImmoMakler → Integraciones → Servicios de geolocalización con la casilla Usar proxy Fast-API. El autocompletado de direcciones funcionará entonces exclusivamente a través del endpoint REST (con admin-ajax como segunda alternativa), y el script del proxy se eliminará del sistema de archivos al guardar.

Alternativamente, puede bloquear la ruta wp-content/cache/immomakler/fast-api/*.php mediante una regla de servidor (.htaccess, Nginx) — el script lo detecta (HTTP 403) y cambia automáticamente a la alternativa REST sin necesidad de modificar nada en el plugin.

Limitación de solicitudes por visitante

Las tres vías son accesibles públicamente, y cada solicitud que no se responde desde la caché se factura a través de su clave de API del servicio de mapas. Para que un script automatizado no dispare su factura ni agote su cuota, WP-ImmoMakler responde como máximo 600 solicitudes facturadas por hora por dirección IP. Las sugerencias servidas desde la caché no cuentan para este límite y se siguen entregando incluso después de alcanzarlo.

Al escribir un nombre de lugar se generan, según su longitud, entre 10 y 15 solicitudes aproximadamente. El límite equivale, por tanto, a más de 40 búsquedas completas por hora desde la misma dirección IP, incluso si varios visitantes comparten una dirección, por ejemplo en una red de oficina.

Una vez alcanzado el límite, el servidor responde con HTTP 429. El script del navegador deja entonces de solicitar más sugerencias en esa página; el campo de búsqueda permanece como un campo de entrada normal, y la búsqueda por radio sigue funcionando con el texto ya introducido. WP-ImmoMakler registra las solicitudes rechazadas al endpoint REST y al endpoint admin-ajax en su registro de protección antispam; el proxy Fast-API no carga WordPress y no las registra.

Puede ajustar el valor con el filtro immomakler_places_autocomplete_rate_limit; 0 desactiva el límite. Se aplica a las tres vías, incluido el proxy Fast-API:

// Permitir 1200 solicitudes facturadas por dirección IP y hora:
add_filter( 'immomakler_places_autocomplete_rate_limit', fn () => 1200 );

Si su sitio web está detrás de un proxy inverso o una CDN que reenvía cada solicitud con su propia dirección IP, todos los visitantes comparten un único límite. En ese caso, pase la IP real del visitante mediante el filtro immomakler_rate_limit_client_fingerprint. El proxy Fast-API no carga WordPress y siempre lee REMOTE_ADDR; en ese caso, desactívelo o configure su servidor web para que REMOTE_ADDR contenga la IP del visitante.

Limitación al enviar la búsqueda por radio

Cuando un visitante envía la búsqueda por radio, WP-ImmoMakler convierte en el servidor el lugar introducido en coordenadas (geocodificación). Esta solicitud también la factura el servicio de geolocalización elegido a través de su clave de API, siempre que el lugar no esté ya en la caché. Dado que la página de resumen es accesible públicamente mediante el parámetro ?center=, aquí también se aplica una limitación propia: como máximo 100 geocodificaciones facturadas por hora por dirección IP.

Una búsqueda de un lugar nuevo cuesta una geocodificación; un nombre de lugar ambiguo fuera de su región cuesta como máximo tres solicitudes. Los lugares por los que ya se ha buscado, así como la paginación y la ordenación, no cuentan. El límite es, por tanto, suficiente para muchos visitantes que comparten una misma dirección IP.

Una vez alcanzado el límite, la página de resumen muestra todos los inmuebles que coinciden con los demás criterios de búsqueda, junto con un aviso encima de los resultados de que la búsqueda por radio no está disponible en ese momento. El lugar introducido permanece en el campo de búsqueda. Los lugares de la caché siguen funcionando. Las alertas de búsqueda que WP-ImmoMakler ejecuta mediante WP-Cron no están sujetas a esta limitación. WP-ImmoMakler nunca geocodifica entradas de más de 200 caracteres.

Puede ajustar el valor con el filtro immomakler_radius_search_geocode_rate_limit; 0 desactiva la limitación:

// Permitir 300 geocodificaciones facturadas por dirección IP y hora:
add_filter( 'immomakler_radius_search_geocode_rate_limit', fn () => 300 );

Esta limitación también identifica a los visitantes por su dirección IP; la nota sobre el filtro immomakler_rate_limit_client_fingerprint anterior se aplica igualmente aquí.

Compatibilidad con plugins de caché

La biblioteca está diseñada deliberadamente para funcionar con configuraciones de caché agresiva (WP Rocket, W3 Total Cache, LiteSpeed Cache, WP Super Cache, Cloudflare APO):

Sin token de seguridad en el HTML. Antes de la versión 5.60.0, WP-ImmoMakler escribía en el código fuente de la página un token válido durante 15 minutos. En las páginas en caché, este token ya había expirado para el primer visitante. A partir de la versión 5.60.0, el token se obtiene en el primer enfoque del campo de entrada a través del endpoint no cacheable /wp-json/immomakler/v1/places/token.
Alternativa de múltiples niveles. Si el proxy rápido falla (por ejemplo, porque un token ha caducado), la biblioteca obtiene automáticamente uno nuevo y lo reintenta. Si el proxy sigue sin responder, las solicitudes se redirigen de forma transparente a la API REST de WordPress y, finalmente, a admin-ajax. Solo si se alcanza el límite de solicitudes (HTTP 429) la cadena termina de inmediato (véase más arriba).

Si su plugin de caché gestiona las rutas REST de forma inusual, excluya la ruta /wp-json/immomakler/v1/places/* del procesamiento de caché.

Personalización mediante filtros

Tres filtros influyen en el comportamiento de la biblioteca:

// No insertar el script automáticamente en el pie de página, sino cargarlo
// manualmente con wp_enqueue_script( 'immomakler-places-autocomplete' ) en páginas concretas:
add_filter( 'immomakler_places_autocomplete_auto_enqueue', '__return_false' );

// Tiempo de vida del token (en segundos, por defecto 900 = 15 minutos):
add_filter( 'immomakler_places_token_ttl', fn () => 600 );

// Número mínimo de caracteres / máximo de sugerencias / retraso de escritura:
add_filter( 'immomakler_places_autocomplete_min_length', fn () => 4 );
add_filter( 'immomakler_places_autocomplete_max_results', fn () => 5 );
add_filter( 'immomakler_places_autocomplete_debounce_ms', fn () => 200 );