Mastering Redis GEO: Add Locations, Compute Distances, and Build Nearby User Features

Version Requirements

Redis 3.0 is the stable release, while the GEO feature is available only in the unstable 3.2 branch. To use it, clone the unstable branch from Redis GitHub and compile the source.

Adding Locations and Getting Positions

Geographic data is stored with the GEOADD command:

<code>GEOADD location-set longitude latitude name [longitude latitude name ...]</code>

Example adding several cities in Guangdong:

<code>redis> GEOADD Guangdong-cities 113.2099647 23.593675 Qingyuan 1 -- added one location redis> GEOADD Guangdong-cities 113.2278442 23.1255978 Guangzhou 113.106308 23.0088312 Foshan 113.7943267 22.9761989 Dongguan 114.0538788 22.5551603 Shenzhen 4 -- added four locations</code>

After storing locations, retrieve their coordinates with GEOPOS:

<code>GEOPOS location-set name [name ...]</code>

Example:

<code>redis> GEOPOS Guangdong-cities Qingyuan Guangzhou Foshan 1) 1) "113.20996731519699" 2) "23.593675019671288" 2) 1) "113.22784155607224" 2) "23.125598202060807" 3) 1) "113.10631066560745" 2) "23.008831202413539"</code>

Calculating Distance Between Two Locations

Use GEODIST to compute the distance between two members:

<code>GEODIST location-set location-x location-y [unit]</code>

The optional unit can be m, km, mi or ft. If omitted, meters are used.

Example (distance between Qingyuan and Guangzhou):

<code>redis> GEODIST Guangdong-cities Qingyuan Guangzhou "52094.433840356309" -- 52 094 meters redis> GEODIST Guangdong-cities Qingyuan Guangzhou km "52.094433840356309" -- 52.09 km</code>

Getting Elements Within a Specified Radius

Redis provides GEORADIUS and GEORADIUSBYMEMBER to find members inside a radius. The two commands differ only in how the center point is specified.

<code>GEORADIUS location-set longitude latitude radius m|km|ft|mi [WITHCOORD] [WITHDIST] [ASC|DESC] [COUNT count] GEORADIUSBYMEMBER location-set location radius m|km|ft|mi [WITHCOORD] [WITHDIST] [ASC|DESC] [COUNT count]</code>

Key options:

Unit ( m|km|ft|mi) WITHCOORD – return coordinates of each result WITHDIST – return distance from the center ASC / DESC – sort by distance COUNT – limit number of results

Example: find cities within 50 km, 100 km and 150 km of Guangzhou:

<code>redis> GEORADIUSBYMEMBER Guangdong-cities Guangzhou 50 km 1) "Foshan" 2) "Guangzhou" redis> GEORADIUSBYMEMBER Guangdong-cities Guangzhou 100 km 1) "Foshan" 2) "Guangzhou" 3) "Dongguan" 4) "Qingyuan" redis> GEORADIUSBYMEMBER Guangdong-cities Guangzhou 150 km 1) "Foshan" 2) "Guangzhou" 3) "Dongguan" 4) "Qingyuan" 5) "Shenzhen"</code>

Example: Find Nearby Users

Using the GEO commands, a simple "find nearby users" feature can be built:

<code>def pin(user, longitude, latitude): """Record the user's location.""" GEOADD('user-location-set', longitude, latitude, user) def find_nearby(user, n): """Return all other users within n kilometers of the given user.""" return GEORADIUSBYMEMBER('user-location-set', user, n, unit='km')</code>

Example: "Shake" Random Nearby User

To add a random‑selection twist, modify the function to pick a random member from the nearby set:

<code>RANDOM_RADIUS = 1 # 1 km radius def find_random(user): # Get all nearby users all_near = find_nearby(user, RANDOM_RADIUS) # Convert list to a set for random pop user_set = set(all_near) return user_set.pop()</code>

Efficiency Optimization

The naive find_random calls find_nearby on every request, which is costly because GEORADIUSBYMEMBER is not cheap and most users' locations change rarely. A cache can store the result of find_nearby in a Redis set with a short TTL (e.g., 5 minutes) and then use SRANDMEMBER to pick a random user, dramatically reducing the number of radius queries.

When many users are clustered, using the COUNT option of GEORADIUSBYMEMBER limits the number of candidates, further improving performance for both find_nearby and find_random.

Conclusion

This brief guide introduced Redis GEO commands, demonstrated how to store and query geospatial data, and showed practical examples such as locating nearby users and implementing an efficient random‑selection feature.