Valkey’s geo commands are a surprisingly potent tool for building location-based features, not just with simple proximity searches, but by enabling complex spatial indexing and querying that can rival dedicated GIS systems for many common use cases.
Let’s see it in action. Imagine we’re building a ride-sharing app and need to find available drivers near a user’s pickup location.
First, we add some drivers with their current locations to a Valkey sorted set named drivers:locations. The score is the Geohash, which Valkey uses internally for spatial indexing.
valkey-cli
127.0.0.1:6379> ZADD drivers:locations 48.8566 2.3522 'driver:123'
(integer) 1
127.0.0.1:6379> ZADD drivers:locations 34.0522 -118.2437 'driver:456'
(integer) 1
127.0.0.1:6379> ZADD drivers:locations 40.7128 -74.0060 'driver:789'
(integer) 1
Now, a user requests a ride at 40.7580, -73.9855 (Times Square, NYC). We want to find drivers within 5 kilometers.
127.0.0.1:6379> GEORADIUS drivers:locations -73.9855 40.7580 5 km WITHCOORD WITHDIST
1) 1) "driver:789"
2) (integer) 0
3) "0.9480"
This tells us driver:789 is approximately 0.948 kilometers away. We can also query by m (meters), km (kilometers), mi (miles), and ft (feet).
The fundamental problem Valkey’s geo commands solve is efficient spatial indexing. Storing locations as simple latitude/longitude pairs and then performing distance calculations on all points for every query would be computationally prohibitive at scale. Instead, Valkey uses the Geohash algorithm to convert lat/lon coordinates into a single string (or in Valkey’s case, a numeric score in a sorted set). This Geohash represents a bounding box, and Valkey can efficiently query for points within a specific radius by looking for Geohashes that overlap with the query area.
The core commands are:
GEOADD key longitude latitude member [longitude latitude member ...]: Adds members with their location coordinates.GEODIST key member1 member2 [unit]: Returns the distance between two members.GEORADIUS key longitude latitude radius [unit] [WITHCOORD] [WITHDIST] [ASC|DESC] [COUNT count]: Finds members within a radius. This is your workhorse for proximity queries.GEORADIUSBYMEMBER key member radius [unit] [WITHCOORD] [WITHDIST] [ASC|DESC] [COUNT count]: Similar toGEORADIUS, but uses a member’s location as the center point.GEOHASH key member [member ...]: Returns the Geohash representation of members.GEOPOS key member [member ...]: Returns the longitude and latitude of members.
The GEORADIUS command is particularly powerful. When you use WITHCOORD, it returns the longitude and latitude of the found members. WITHDIST provides the distance from the query center. ASC and DESC sort the results by distance, and COUNT limits the number of results returned. This allows for efficient "find the nearest N" queries.
Internally, Valkey stores these locations in a sorted set where the score is derived from the Geohash of the coordinates. The Geohash is a hierarchical system that divides the world into progressively smaller grid cells. By using the Geohash as the score, Valkey can leverage its sorted set data structure to perform range queries that correspond to spatial areas. When you request locations within a radius, Valkey translates that radius into a set of Geohash prefixes that cover the area and then queries the sorted set for members whose scores fall within those prefixes. This is significantly faster than a brute-force calculation.
What many users don’t realize is that you can use GEORADIUS with a STORE or STOREDIST option to populate another Valkey data structure with the results. This is incredibly useful for scenarios where you want to perform subsequent operations on the spatially filtered data without re-querying the original geo index. For instance, you could find all drivers within 10km of a user and then STORE those driver IDs into a list or set for further processing, like sending them a notification.
The next step in building sophisticated location-based features involves understanding how to combine Valkey’s geo commands with other data structures to create more complex spatial queries, such as finding all points within a bounding box or performing multi-criteria filtering on geographically relevant data.