Géocodage

La plupart de vos membres n'auront jamais de pin placé à la main. Ils auront une adresse — Calle 23 #45-12, Cartagena, Bolívar, Colombia — et l'attente que la carte fonctionne simplement. Le géocodage est le processus en arrière-plan qui prend ces adresses, les envoie à un fournisseur et stocke le résultat pour qu'elles apparaissent sur la carte.

Les deux colonnes de coordonnées

Chaque ligne de members et chaque ligne de org_units porte deux colonnes de localisation indépendantes :

• map_location — le pin exact. Placé à la main par un membre du personnel qui a cliqué sur Utiliser ma position ou tapé lat,lng dans le champ de localisation. C'est la vérité de terrain et le géocodeur n'y touche jamais.
• estimated_map_location — la coordonnée approximative. Écrite par le géocodeur lorsqu'un champ d'adresse change. Peu coûteuse, scalable à des milliers d'enregistrements, mais seulement aussi précise que l'adresse elle-même.

Les deux peuvent être présentes en même temps. Le sélecteur de source décide laquelle la carte dessine.

Quand le géocodeur s'exécute

Le géocodeur est déclenché par tout changement à un champ de forme adresse sur un membre ou une unité organisationnelle :

• address (la ligne de rue)
• city_id (la ville à laquelle appartient l'enregistrement)
• state_id / country_id (les zones administratives plus larges)

Lorsqu'un de ces champs change, l'enregistrement est marqué estimated_geocode_status = 'pending' et ajouté à une file d'attente. La sauvegarde elle-même retourne immédiatement — vous n'attendez pas le géocodeur. Un worker en arrière-plan prend le travail dans la minute environ et écrit le résultat.

Si seul le nom ou le numéro de téléphone change, le géocodeur ne se relance pas. Il ne s'intéresse qu'aux entrées de forme adresse.

Le champ estimated_geocode_status

Cette colonne vous indique exactement où en est chaque enregistrement dans le pipeline. Quatre valeurs :

Statut	Signification
pending	L'enregistrement est en file. Un worker le prendra sous peu. Les nouveaux enregistrements ayant une adresse commencent toujours ici.
ok	Le géocodeur a réussi. estimated_map_location est rempli et l'enregistrement apparaîtra sur la carte.
failed	Un échec temporaire (panne réseau, limitation de débit du fournisseur). Le worker réessaiera avec backoff.
terminal	Le géocodeur a renoncé. L'adresse n'a pas pu être résolue après plusieurs tentatives. Signifie généralement que l'adresse est malformée, une ville en texte libre que le fournisseur ne reconnaît pas, ou une combinaison de pays sans lieu correspondant.

Vous pouvez voir le badge sur le profil d'un membre sous la section emplacement — pending s'affiche en gris, failed / terminal en rouge. La requête de membres de la carte filtre automatiquement les lignes terminal et failed, vous ne voyez donc que les enregistrements qui ont réellement des coordonnées.

Fournisseurs

GCM est livré avec trois fournisseurs de géocodage ; l'admin de l'org en choisit un à Paramètres → Carte → Fournisseur de géocodage :

• Nominatim (défaut) — le service gratuit d'OpenStreetMap. Aucune clé API requise, à débit limité par usage poli, bonne couverture mondiale mais plus faible sur les adresses de rue d'Amérique latine.
• Mapbox — payant, rapide, structuré. Nécessite un jeton d'accès Mapbox dans Paramètres → Carte. Excellent sur les adresses US/UE, très bon ailleurs.
• Google Maps — payant, qualité premium. Nécessite une clé API Google Maps Geocoding. Le fournisseur le plus précis pour la majeure partie du monde mais le plus cher.

Le worker appelle le fournisseur que l'org a configuré et écrit le lat,lng résultant dans estimated_map_location. La réponse verbatim du fournisseur n'est pas stockée — uniquement la coordonnée.

TIP

Pour la plupart des églises d'Amérique latine, nous recommandons Mapbox ou Google. La couverture gratuite de Nominatim convient pour les adresses en anglais mais perd en précision sur les numéros d'appartement, étiquettes d'unité et nomenclature de rue informelle.

La file d'attente

La file vit dans geocode_jobs. Chaque travail porte le type d'enregistrement (member ou org_unit), l'ID de l'enregistrement, un statut pending et un bail claim pour que deux workers ne prennent pas le même travail. La fonction edge geocode-worker s'exécute sur cron (toutes les minutes par défaut). À chaque tic, elle :

1. Réclame un lot de travaux en attente atomiquement en utilisant claim_geocode_jobs (avec SKIP LOCKED pour ne jamais bloquer).
2. Appelle le fournisseur configuré pour chaque adresse.
3. En cas de succès, écrit estimated_map_location et définit estimated_geocode_status = 'ok'.
4. En cas d'échec transitoire, laisse le statut comme failed et laisse le prochain tic réessayer.
5. Après plusieurs tentatives, passe à terminal et arrête d'essayer.

Un platform admin peut aussi invoquer le worker à la demande pour vider la file immédiatement — utile juste après l'importation d'une grande liste de membres.

Re-géocoder un seul enregistrement

Parfois le géocodeur a placé un pin dans le mauvais quartier — un centroïde de route pour un bloc d'appartements, un centre-ville pour une adresse sans numéro de rue — et vous avez depuis corrigé l'adresse. Pour forcer un nouveau géocodage :

1. Ouvrez le profil du membre (ou l'éditeur d'unité organisationnelle).
2. Trouvez la carte d'emplacement.
3. Cliquez sur le bouton Re-géocoder (il apparaît à côté du champ d'emplacement ; dit Géocoder si l'enregistrement n'a jamais été géocodé, Re-géocoder s'il l'a été).
4. Le statut repasse à pending et le worker le prend au prochain tic.

Un petit flash vert confirme que la requête a été mise en file. La nouvelle coordonnée apparaît généralement dans la minute. Si elle n'apparaît pas, l'adresse a probablement échoué — ouvrez la liste des membres, filtrez par estimated_geocode_status = terminal, et vérifiez les adresses.

Re-géocodage en masse

Après le déploiement d'une nouvelle table de référence ville/état/pays ou un changement de fournisseur, vous voudrez peut-être que chaque enregistrement soit re-géocodé. Le re-géocodage en masse est une action de platform admin : un UPDATE SQL repasse chaque ligne de l'organisation à pending, le prochain tic du worker commence à traiter, et Platform admin → Geocode jobs affiche la progression (décomptes pending / ok / failed). Comme le worker est à débit limité et par lots, un re-géocodage de 5 000 membres prend quelques heures.

Unités organisationnelles

Les unités organisationnelles utilisent exactement le même pipeline. Modifiez l'adresse d'un campus et le worker la géocode comme un membre. La table org_units porte les mêmes colonnes map_location / estimated_map_location / estimated_geocode_status et les mêmes statuts. Voir Unités organisationnelles sur la carte pour savoir comment les coordonnées résultantes s'affichent.

Ce que la carte affiche

Les enregistrements avec estimated_geocode_status = 'pending', 'failed' ou 'terminal' et sans pin manuel n'apparaissent pas sur la carte — ils n'ont pas de coordonnée. Ils restent silencieusement dans l'annuaire jusqu'à ce qu'une coordonnée soit écrite. Le badge de décompte de pins en haut de la carte ne reflète que les enregistrements avec au moins une coordonnée valide.

Si un membre a un pin exact mais que son résultat géocodeur d'adresse est également stocké, le mode Tous les emplacements de la carte dessine le pin exact et ignore l'estimation. Cette préséance est délibérée — la vérité de terrain bat une supposition, à chaque fois.

Confidentialité

Le géocodeur ne voit que l'adresse, jamais le nom du membre. Les chaînes d'adresse sont envoyées au fournisseur configuré sur HTTPS. Si la posture de confidentialité de votre organisation interdit d'envoyer des adresses de membres à une API tierce, basculez le fournisseur sur Aucun dans Paramètres → Carte et la file arrêtera le traitement. Les membres sans pin manuel n'apparaîtront simplement pas sur la carte.

Liens connexes

• Vue d'ensemble de la carte — la page qui consomme ces coordonnées.
• Voir les membres sur la carte — comment le badge exact vs approximatif est affiché.
• Filtres et couches — basculer entre exact, approximatif et mixte.
• Unités organisationnelles sur la carte — le géocodage s'applique aussi aux campus.
• Module Membres — où vous éditez les adresses et déclenchez les re-géocodages.
• Créer des unités organisationnelles — les adresses entrées ici passent aussi par le géocodeur.