Uma lista de quarenta endereços de agências ordenada pelo nome da cidade não é útil para um cliente que quer saber qual fica mais perto do seu escritório. Um banco regional teve exatamente essa lista no site durante anos, e a equipe de suporte recebia um fluxo constante de ligações pedindo, na prática, que a ordenação fosse feita manualmente por telefone.
Resolver isso exigia dois dados de localização que o banco ainda não tinha em uma forma utilizável: coordenadas para cada agência e uma forma de encontrar o ponto de partida do próprio cliente. Os endereços das agências foram geocodificados uma vez, em um único lote enviado ao /v1/forward, já que uma requisição em lote conta cada endereço como um item cobrado. Isso deu a cada agência uma latitude e uma longitude fixas para trabalhar, algo que a lista anterior, montada apenas com endereços em texto, nunca conseguiria oferecer.
Para o lado do cliente no cálculo, o banco ofereceu dois caminhos. Um cliente que permitia que a página detectasse sua localização aproximada a obtinha do /v1/ip, que resolve o endereço IP do visitante em coordenadas, junto com cidade e região, fornecendo um ponto de partida razoável sem pedir nada. Um cliente que preferia digitar um endereço, algo comum para quem planeja uma visita perto do trabalho e não da sua localização atual, tinha esse endereço geocodificado pela mesma chamada ao /v1/forward usada para a lista de agências, e depois classificado em relação a ela da mesma forma.
A classificação, depois que os dois lados tinham coordenadas, era uma conta de distância simples que o próprio site do banco fazia sem precisar de nenhum serviço adicional. O resultado visível foi um localizador de agências que mostrava primeiro os cinco locais mais próximos, cada um com um valor de distância simples, em vez de uma rolagem por quarenta endereços agrupados por cidade.
Por se tratar de um banco, a equipe tomou cuidado com o grau de certeza com que a ferramenta se expressava. A localização baseada em IP é uma aproximação, útil como ponto de partida, mas não exata, principalmente para um cliente em uma rede móvel ou em uma VPN corporativa, e o localizador do banco sempre indicava a localização detectada como uma estimativa inicial, com uma forma fácil de ajustá-la, em vez de apresentá-la como certeza. Isso importava mais aqui do que em um localizador de lojas casual, já que um cliente direcionado para a agência errada para algo como um reconhecimento de firma agendado sofre um transtorno maior do que ser direcionado para a cafeteria errada.
O tráfego da ferramenta era modesto e previsível, uma ou duas consultas por sessão de visitante, bem dentro da cota diária gratuita incluída na chave do banco, mesmo durante uma campanha de marketing que gerou tráfego extra no localizador de agências. O projeto também deu ao banco coordenadas de agências limpas e reutilizáveis, que ele usou depois para outras coisas, como desenhar mapas de raio simples para o anúncio da inauguração de uma nova agência, sem nenhum trabalho adicional de geocodificação.
Um localizador de agências ou de lojas é um dos usos mais comuns da geocodificação justamente porque o retorno é muito visível: um localizador que funciona e classifica por distância é algo que os clientes percebem segundos depois de usar, ao lado de algo que claramente não funciona. A documentação dos endpoints relevantes está em /docs/forward-geocoding/ e /docs/ipv4-lookup/.