Geocodificación

La mayoría de tus miembros nunca tendrá un pin colocado a mano. Tendrán una dirección — Calle 23 #45-12, Cartagena, Bolívar, Colombia — y la expectativa de que el mapa simplemente funcione. La geocodificación es el proceso de fondo que toma esas direcciones, las envía a un proveedor y guarda el resultado para que aparezcan en el mapa.

Las dos columnas de coordenadas

Cada fila de members y cada fila de org_units lleva dos columnas de ubicación independientes:

• map_location — el pin exacto. Colocado a mano por un miembro del personal que hizo clic en Usar mi ubicación o escribió lat,lng en el campo de ubicación. Es verdad de campo y el geocodificador nunca lo toca.
• estimated_map_location — la coordenada aproximada. Escrita por el geocodificador cuando cambia un campo de dirección. Económica, escala a miles de registros, pero solo es tan precisa como la dirección.

Ambas pueden coexistir. El selector de fuente decide cuál dibuja el mapa.

Cuándo corre el geocodificador

El geocodificador se dispara con cualquier cambio en un campo con forma de dirección en un miembro o unidad organizacional:

• address (la línea de calle)
• city_id (a qué ciudad pertenece el registro)
• state_id / country_id (las áreas administrativas mayores)

Cuando uno de esos campos cambia, el registro se marca como estimated_geocode_status = 'pending' y se añade a una cola. El guardado en sí devuelve de inmediato — no esperas al geocodificador. Un worker en segundo plano recoge el trabajo en alrededor de un minuto y escribe el resultado.

Si solo cambian el nombre o el teléfono, el geocodificador no vuelve a correr. Solo le importan las entradas con forma de dirección.

El campo estimated_geocode_status

Esta columna te dice exactamente dónde está cada registro dentro de la canalización. Cuatro valores:

Estado	Significado
pending	El registro está en cola. Un worker lo recogerá en breve. Los registros nuevos con dirección siempre empiezan aquí.
ok	El geocodificador tuvo éxito. estimated_map_location está poblada y el registro aparecerá en el mapa.
failed	Falla temporal (corte de red, límite de tasa del proveedor). El worker reintentará con backoff.
terminal	El geocodificador se rindió. La dirección no pudo resolverse tras varios intentos. Suele significar que la dirección está mal formada, que la ciudad es texto libre que el proveedor no reconoce, o que es una combinación de país sin lugar coincidente.

Puedes ver la insignia en el perfil del miembro bajo la sección de ubicación — pending aparece en gris, failed / terminal en rojo. La consulta de miembros del mapa filtra automáticamente las filas terminal y failed, de modo que solo ves registros que realmente tienen coordenadas.

Proveedores

GCM trae tres proveedores de geocodificación; el administrador de la organización elige uno en Configuración → Mapa → Proveedor de geocodificación:

• Nominatim (por defecto) — el servicio gratuito de OpenStreetMap. Sin clave de API requerida, límites de uso cortés, buena cobertura global pero más débil en direcciones de calles latinoamericanas.
• Mapbox — de pago, rápido, estructurado. Requiere un token de acceso de Mapbox en Configuración → Mapa. Excelente en direcciones de EE. UU. y la UE, muy bueno en otros lugares.
• Google Maps — de pago, calidad premium. Requiere una clave de Google Maps Geocoding API. El proveedor más preciso para la mayor parte del mundo pero el más caro.

El worker llama a cualquier proveedor que la organización tenga configurado y escribe el lat,lng resultante en estimated_map_location. La respuesta literal del proveedor no se guarda — solo la coordenada.

TIP

Para la mayoría de las iglesias latinoamericanas recomendamos Mapbox o Google. La cobertura gratuita de Nominatim está bien para direcciones en inglés pero pierde precisión en números de apartamento, etiquetas de unidad y nombres de calle informales.

La cola

La cola vive en geocode_jobs. Cada trabajo lleva el tipo de registro (member o org_unit), el ID del registro, un estado pending, y un lease de claim para que dos workers no recojan el mismo trabajo. La edge function geocode-worker corre por cron (cada minuto por defecto). En cada tick:

1. Reclama un lote de trabajos pendientes atómicamente usando claim_geocode_jobs (con SKIP LOCKED para que nunca se bloquee).
2. Llama al proveedor configurado para cada dirección.
3. En éxito, escribe estimated_map_location y fija estimated_geocode_status = 'ok'.
4. En una falla transitoria, deja el estado como failed y permite que el siguiente tick reintente.
5. Tras varios reintentos, pasa a terminal y deja de intentar.

Un administrador de plataforma también puede invocar el worker a demanda para vaciar la cola de inmediato — útil justo después de importar una gran lista de miembros.

Re-geocodificar un solo registro

A veces el geocodificador puso un pin en el barrio equivocado — un centroide de carretera para un edificio de apartamentos, un centro de ciudad para una dirección sin número — y luego corregiste la dirección. Para forzar una geocodificación fresca:

1. Abre el perfil del miembro (o el editor de la unidad organizacional).
2. Encuentra la tarjeta de ubicación.
3. Haz clic en el botón Re-geocodificar (aparece junto al campo de ubicación; dice Geocodificar si el registro nunca se ha geocodificado, Re-geocodificar si ya lo hizo).
4. El estado vuelve a pending y el worker lo recoge en el siguiente tick.

Un pequeño destello verde confirma que la solicitud fue encolada. La nueva coordenada suele aparecer en un minuto. Si no aparece, la dirección probablemente falló — abre la lista de miembros, filtra por estimated_geocode_status = terminal, y revisa las direcciones.

Re-geocodificación masiva

Tras desplegar una nueva tabla de referencia de ciudad/estado/país o cambiar de proveedor, quizá quieras que cada registro vuelva a geocodificarse. La re-geocodificación masiva es una acción de administrador de plataforma: un UPDATE SQL pone cada fila de la organización en pending, el siguiente tick del worker empieza a procesar, y Administración de plataforma → Trabajos de geocodificación muestra el progreso (conteos de pending / ok / failed). Como el worker está limitado por tasa y por lotes, una re-geocodificación de 5.000 miembros toma unas cuantas horas.

Unidades organizacionales

Las unidades organizacionales usan exactamente la misma canalización. Edita la dirección de una sede y el worker la geocodifica igual que a un miembro. La tabla org_units lleva las mismas columnas map_location / estimated_map_location / estimated_geocode_status y los mismos estados. Consulta Unidades organizacionales en el mapa para ver cómo se renderizan las coordenadas resultantes.

Qué muestra el mapa

Los registros con estimated_geocode_status = 'pending', 'failed', o 'terminal' y sin pin manual no aparecen en el mapa — no tienen coordenada. Permanecen silenciosamente en el directorio hasta que se escriba una coordenada. La insignia del contador de pins en la parte superior del mapa refleja solo registros con al menos una coordenada válida.

Si un miembro tiene un pin exacto pero su resultado de geocodificación de dirección también está guardado, el modo Todas las ubicaciones del mapa dibuja el pin exacto e ignora la estimación. Esa precedencia es deliberada — la verdad de campo le gana a una suposición, siempre.

Privacidad

El geocodificador solo ve la dirección, nunca el nombre del miembro. Las cadenas de dirección se envían al proveedor configurado por HTTPS. Si la postura de privacidad de tu organización prohíbe enviar direcciones de miembros a una API de terceros, cambia el proveedor a None en Configuración → Mapa y la cola dejará de procesar. Los miembros sin pin manual simplemente no aparecerán en el mapa.

Relacionado

• Vista general del mapa — la página que consume estas coordenadas.
• Ver miembros en el mapa — cómo se muestra la insignia exacta vs aproximada.
• Filtros y capas — alterna entre exacta, aproximada y mixta.
• Unidades organizacionales en el mapa — la geocodificación también aplica a sedes.
• Módulo Miembros — donde editas direcciones y disparas re-geocodificaciones.
• Crear unidades organizacionales — las direcciones introducidas aquí también pasan por el geocodificador.