Pontos k vizinhos mais próximos por distância geodésica

Informe latitude e longitude, uma lista de coordenadas candidatas e a quantidade de resultados desejada. A capacidade calcula a distância de grande círculo até cada candidato, classifica do mais próximo ao mais distante e retorna os primeiros k com índices de origem e rótulos opcionais. A ordenação determinística é apropriada para busca de locais, preparação de rotas, verificações de proximidade e pipelines de dados reproduzíveis.

Prepare a consulta e a lista de candidatos

Comece com uma coordenada de consulta em graus decimais e uma lista de um a dez mil pontos candidatos. A latitude deve ficar entre -90 e 90, e a longitude entre -180 e 180. Cada candidato segue as mesmas regras e pode ter um rótulo, como nome de loja, código de depósito, identificador de sensor ou cidade. O rótulo é copiado para o resultado, mas nunca altera a classificação. Escolha k como inteiro positivo que não ultrapasse a quantidade de candidatos. Esse contrato explícito evita buscas parciais ambíguas e faz registros inválidos falharem cedo com uma mensagem útil. Use coordenadas no padrão de graus decimais comum em mapas web e exportações GPS. Caso a origem use graus, minutos e segundos ou uma projeção cartográfica, converta-a antes da chamada. Se duas distâncias forem iguais, a ordem original da lista será mantida, garantindo uma saída repetível em diferentes execuções.

Entenda o ranking por grande círculo

O cálculo representa a Terra como uma esfera com raio médio de 6,371.0088 quilômetros. Para cada candidato, aplica a relação de haversine e um cálculo de ângulo central com atan2, estável tanto para trajetos muito curtos quanto para pontos quase opostos. O valor distance_km é arredondado para seis casas decimais e os candidatos são ordenados de forma crescente. Essa é a distância pela superfície do globo, e não uma linha reta através da Terra, uma rota rodoviária ou uma medida em projeção local. O método trata naturalmente a mudança de longitude perto da linha internacional de data e funciona nos polos. O modelo esférico atende bem a consultas globais, descoberta, despacho aproximado e formação de listas curtas. Para topografia, distância elipsoidal, estradas, altitude, fronteiras ou obstáculos, use o resultado como pré-seleção e aplique depois um cálculo especializado. O índice permite relacionar cada vizinho ao registro original mesmo sem rótulo exclusivo.

Use a lista ordenada em um fluxo maior

Um resultado de vizinhos próximos normalmente inicia uma decisão. Um localizador pode solicitar as cinco filiais mais próximas e depois filtrar por horário ou estoque. Um serviço logístico pode selecionar depósitos próximos antes de enviar poucos candidatos a um mecanismo de rotas. Um painel ambiental pode associar uma observação aos sensores mais próximos e preservar as distâncias para controle de qualidade. Como a função não usa rede, aleatoriedade, estado armazenado nem horário atual, entradas idênticas produzem saídas idênticas. Isso facilita cache, testes com exemplos fixos e reprodução de um ranking em auditorias. O limite declarado mantém o processamento previsível: cada candidato é medido uma vez e o conjunto limitado é ordenado. Para coleções muito grandes ou alteradas com frequência, um índice espacial ou banco de dados é mais eficiente. Para listas compactas enviadas por solicitação, esta capacidade dispensa configuração de índice e retorna uma estrutura JSON transparente, pronta para outra tarefa.