Geocodificação

A maioria dos seus membros nunca terá um pin colocado à mão. Eles terão um endereço — Calle 23 #45-12, Cartagena, Bolívar, Colombia — e uma expectativa de que o mapa simplesmente funcione. Geocodificação é o processo em segundo plano que pega esses endereços, envia para um provedor e armazena o resultado para que eles apareçam no mapa.

As duas colunas de coordenadas

Cada linha de members e cada linha de org_units carrega duas colunas independentes de localização:

• map_location — o pin exato. Colocado à mão por um membro da equipe que clicou em Usar minha localização ou digitou lat,lng no campo de localização. Esta é a verdade do campo e o geocoder nunca toca.
• estimated_map_location — a coordenada aproximada. Escrita pelo geocoder quando um campo de endereço muda. Barata, escala para milhares de registros, mas apenas tão precisa quanto o endereço em si.

Ambas podem estar presentes ao mesmo tempo. O seletor de fonte decide qual o mapa desenha.

Quando o geocoder roda

O geocoder é disparado por qualquer mudança em um campo no formato de endereço em um membro ou unidade organizacional:

• address (a linha da rua)
• city_id (qual cidade o registro pertence)
• state_id / country_id (as áreas administrativas maiores)

Quando um desses campos muda, o registro é marcado como estimated_geocode_status = 'pending' e adicionado a uma fila. O próprio salvamento retorna imediatamente — você não espera o geocoder. Um worker em segundo plano pega o trabalho em um minuto ou pouco mais e escreve o resultado.

Se só o nome ou número de telefone muda, o geocoder não roda de novo. Ele só se importa com inputs no formato de endereço.

O campo estimated_geocode_status

Esta coluna diz exatamente onde cada registro está no pipeline. Quatro valores:

Status	Significado
pending	O registro está na fila. Um worker vai pegar em breve. Novos registros que têm um endereço sempre começam aqui.
ok	O geocoder teve sucesso. estimated_map_location está preenchido e o registro vai aparecer no mapa.
failed	Uma falha temporária (queda de rede, limite de taxa do provedor). O worker vai tentar de novo com backoff.
terminal	O geocoder desistiu. O endereço não pôde ser resolvido depois de múltiplas tentativas. Geralmente significa que o endereço está mal formado, uma cidade em texto livre que o provedor não reconhece, ou uma combinação de país sem lugar correspondente.

Você pode ver o selo no perfil de um membro sob a seção de localização — pending aparece como cinza, failed / terminal como vermelho. A consulta de membros do mapa filtra linhas terminal e failed automaticamente, então você só vê registros que realmente têm coordenadas.

Provedores

O GCM vem com três provedores de geocodificação; o admin da org escolhe um em Configurações → Mapa → Provedor de geocodificação:

• Nominatim (padrão) — o serviço gratuito do OpenStreetMap. Não requer chave de API, com limite de taxa de uso educado, boa cobertura global mas mais fraco em endereços de rua latino-americanos.
• Mapbox — pago, rápido, estruturado. Requer um token de acesso Mapbox em Configurações → Mapa. Excelente em endereços US/UE, muito bom em outros lugares.
• Google Maps — pago, qualidade premium. Requer uma chave de API Google Maps Geocoding. O provedor mais preciso para a maior parte do mundo mas o mais caro.

O worker chama o provedor que a org configurou e escreve o lat,lng resultante em estimated_map_location. A resposta verbatim do provedor não é armazenada — apenas a coordenada.

TIP

Para a maioria das igrejas latino-americanas recomendamos Mapbox ou Google. A cobertura gratuita do Nominatim está OK para endereços em inglês mas perde precisão em números de apartamento, rótulos de unidade e nomenclatura de rua informal.

A fila

A fila vive em geocode_jobs. Cada trabalho carrega o tipo de registro (member ou org_unit), o ID do registro, um status pending e um arrendamento claim para que dois workers não peguem o mesmo trabalho. A edge function geocode-worker roda em cron (a cada minuto por padrão). Em cada tick, ela:

1. Reivindica um lote de trabalhos pendentes atomicamente usando claim_geocode_jobs (com SKIP LOCKED para nunca bloquear).
2. Chama o provedor configurado para cada endereço.
3. Em sucesso, escreve estimated_map_location e define estimated_geocode_status = 'ok'.
4. Em falha transitória, deixa o status como failed e deixa o próximo tick tentar de novo.
5. Depois de várias tentativas, transita para terminal e para de tentar.

Um platform admin também pode invocar o worker sob demanda para esvaziar a fila imediatamente — útil logo após importar uma lista grande de membros.

Regeocodificando um único registro

Às vezes o geocoder colocou um pin no bairro errado — um centroide de via para um bloco de apartamentos, um centro de cidade para um endereço sem número de rua — e desde então você corrigiu o endereço. Para forçar uma geocodificação fresca:

1. Abra o perfil do membro (ou o editor de unidade organizacional).
2. Encontre o cartão de localização.
3. Clique no botão Re-geocodificar (aparece ao lado do campo de localização; diz Geocodificar se o registro nunca foi geocodificado, Re-geocodificar se já foi).
4. O status volta para pending e o worker pega no próximo tick.

Um pequeno flash verde confirma que a solicitação foi enfileirada. A nova coordenada geralmente aparece em um minuto. Se não, o endereço provavelmente falhou — abra a lista de membros, filtre por estimated_geocode_status = terminal e cheque os endereços.

Regeocodificação em massa

Depois de lançar uma nova tabela de referência de cidade/estado/país ou trocar provedores, você pode querer cada registro regeocodificado. Regeocodificação em massa é uma ação de platform admin: um UPDATE SQL vira cada linha na org de volta para pending, o próximo tick do worker começa a processar, e Platform admin → Geocode jobs mostra o progresso (contagens pending / ok / failed). Como o worker tem limite de taxa e processa em lotes, uma regeocodificação de 5.000 membros leva algumas horas.

Unidades organizacionais

Unidades organizacionais usam exatamente o mesmo pipeline. Edite o endereço de uma sede e o worker a geocodifica como um membro. A tabela org_units carrega as mesmas colunas map_location / estimated_map_location / estimated_geocode_status e os mesmos status. Veja Unidades organizacionais no mapa para como as coordenadas resultantes renderizam.

O que o mapa mostra

Registros com estimated_geocode_status = 'pending', 'failed' ou 'terminal' e sem pin manual não aparecem no mapa — eles não têm coordenada. Ficam silenciosamente no diretório até que uma coordenada seja escrita. O selo de contagem de pins no topo do mapa reflete apenas registros com pelo menos uma coordenada válida.

Se um membro tem um pin exato mas seu resultado de geocoder de endereço também é armazenado, o modo Todos os locais do mapa desenha o pin exato e ignora a estimativa. Essa precedência é deliberada — verdade-do-campo vence palpite, todo dia.

Privacidade

O geocoder vê só o endereço, nunca o nome do membro. Strings de endereço são enviadas para o provedor configurado via HTTPS. Se a postura de privacidade da sua org proíbe enviar endereços de membros para uma API de terceiros, troque o provedor para Nenhum em Configurações → Mapa e a fila para de processar. Membros sem pins manuais simplesmente não aparecerão no mapa.

Relacionado

• Visão geral do mapa — a página que consome essas coordenadas.
• Visualizando membros no mapa — como o selo exato vs aproximado é mostrado.
• Filtros e camadas — alternar entre exato, aproximado e misto.
• Unidades organizacionais no mapa — geocodificação também se aplica a sedes.
• Módulo Membros — onde você edita endereços e dispara regeocodificações.
• Criando unidades organizacionais — endereços inseridos aqui também passam pelo geocoder.