Codificador geohash

Um geohash transforma um par de coordenadas geográficas em uma curta string base32 que identifica uma célula retangular na Terra. Pontos próximos compartilham longos prefixos em comum, o que torna a codificação útil para busca por proximidade, chaves de tile, partições de cache e tokens de localização legíveis por pessoas. O algoritmo é pura aritmética: sem chamadas de rede, sem amostragem aleatória e sem relógio. Precisão inválida ou coordenadas fora de faixa são rejeitadas com um erro de entrada claro, em vez de uma célula errada silenciosa.

O que um geohash realmente representa

Cada caractere que você acrescenta reduz a célula pela metade, primeiro em uma dimensão e depois na outra, de modo que strings mais longas descrevem retângulos menores. Um hash de um caractere cobre uma faixa enorme do planeta; nove ou dez caracteres costumam ser finos o bastante para um quarteirão ou a pegada de um edifício, dependendo da latitude.

Como os prefixos se aninham, dois locais que compartilham os sete primeiros caracteres caem dentro da mesma célula grosseira, e é exatamente isso que torna práticas as consultas por prefixo e o agrupamento em mapas. A string não é um hash criptográfico: pontos diferentes podem compartilhar um prefixo de propósito, e a mesma precisão sempre produz a mesma string para as mesmas coordenadas.

Use-a quando precisar de uma chave compacta e segura para URL de um lugar, em vez de um par completo de ponto flutuante em cada linha de log ou linha de banco de dados.

Como escolher a precisão e enviar as coordenadas

A precisão é o número de caracteres base32 que você quer de volta, de um até doze. Valores baixos servem para baldes de país ou região; valores médios servem para cidades e bairros; valores altos servem para células em escala de interior ou de rastreamento de veículos. Campos ausentes e valores não numéricos falham da mesma forma.

Prefira números decimais estáveis a strings com unidades ou letras cardeais; converta referências DMS ou de grade antes de chamar.

Onde as células codificadas se encaixam em pipelines reais

As equipes usam geohashes como chaves de partição em bases de séries temporais, como identificadores de tile de mapa para caches de cliente, como prefixos compartilhados para filtros de pontos próximos e como tokens curtos em URLs ou cargas de QR quando um par completo de lat/lon é incômodo. Como a transformação é determinística e sem efeitos colaterais, você pode regenerar a mesma chave no navegador, em um worker ou em um job em lote e esperar resultados idênticos byte a byte para as mesmas entradas.

Isso importa para testes de referência, réplicas multirregião e ferramentas offline que não podem divergir. Lembre-se de que as células geohash são retângulos no espaço de graus, não círculos perfeitos de área igual: perto dos polos, uma célula longa é muito mais estreita em metros no sentido leste-oeste do que o mesmo comprimento perto do equador. Para busca estrita por raio, você ainda calcula a distância sobre os pontos originais; use o hash para agrupar e recuperar candidatos e, depois, refine.