K nearest neighbor points

Provide a latitude and longitude, a list of candidate coordinates, and the number of matches you need. The capability calculates spherical great-circle distance to every candidate, sorts the results from nearest to farthest, and returns the requested top k with source indexes and optional labels. Its deterministic ordering makes the result suitable for location search, routing preparation, proximity checks, and repeatable data-processing pipelines.

Prepare a clear query and candidate set

Start with one query coordinate in decimal degrees and a candidate list containing between one and ten thousand points. Latitude must fall between -90 and 90, while longitude must fall between -180 and 180. Each candidate uses the same coordinate rules and may include a label, such as a store name, depot code, sensor identifier, or city. Labels are copied into results but never influence ranking. Choose k as a positive integer no larger than the candidate count. This explicit contract prevents ambiguous partial searches and makes malformed records fail early with a useful input error. Keep all coordinates in the WGS84-style decimal-degree convention normally used by web maps and GPS exports. If your source uses degrees, minutes, and seconds or a projected coordinate system, convert it before calling the capability. Candidate order matters only when distances tie: equally distant points retain their original list order, giving repeatable output across calls and runtimes.

Understand the great-circle ranking

The calculation treats Earth as a sphere with a mean radius of 6,371.0088 kilometers. For each candidate, it applies the haversine relationship and an atan2 central-angle calculation, which remains stable for both very short paths and nearly opposite points. The returned distance_km value is rounded to six decimal places, then candidates are sorted in ascending order. This is surface distance along the globe, not a straight line through Earth, a driving route, or distance measured in a local map projection. It naturally handles longitude wraparound near the international date line and works at either pole without special cases. The spherical model is appropriate for global lookup, discovery, rough dispatch, and shortlist generation. If a workflow requires survey-grade ellipsoidal measurements, road travel time, elevation, borders, or obstacles, use this result as a first-stage shortlist and apply a specialized calculation afterward. The source index lets you join every returned neighbor back to its original record without relying on a label being present or unique.

Use the ranked shortlist in a larger workflow

A nearest-neighbor result is often the beginning of a decision rather than its end. A store locator can request the five closest branches, then filter them by opening hours or inventory. A logistics service can shortlist nearby depots before sending those few candidates to a road-routing engine. An environmental dashboard can associate an observation with its closest sensors while preserving the computed distance for quality checks. Because the function has no network calls, randomness, stored state, or current-time dependency, identical input produces identical output. That makes it straightforward to cache results, test integrations with golden fixtures, or reproduce an earlier ranking during an audit. The declared upper bound also keeps execution predictable: the implementation measures every candidate once and sorts the bounded result set. For frequently changing or very large collections, a spatial index or database will be more efficient. For compact lists supplied with each request, this capability avoids index setup and returns a transparent JSON structure that can be passed directly to another task.