GEORADIUS(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 GEORADIUS 💖

okay bestie, so this is a Valkey command — straight out of the Valkey Command Manual (3valkey), section 3. it's the one where you ask "hey, what's near this spot?" and the server actually tells you. let's get into it 🗺️✨

✨ NAME ✨

georadius — queries a geospatial index for members within a distance from a coordinate, optionally stores the result. 💫

🌸 SYNOPSIS 🌸

GEORADIUS key longitude latitude radius <M | KM | FT | MI> [WITHCOORD]
[WITHDIST] [WITHHASH] [COUNT count [ANY]] [ASC | DESC] [STORE key |
STOREDIST key]

🦋 DESCRIPTION 🦋

So basically: this returns the members of a sorted set that's been stuffed full of geospatial info using GEOADD, and it only gives you back the ones sitting inside the area you defined — the center location, plus a max distance from that center (that's the radius, bestie 🎯).

heads up: this manual page also covers the GEORADIUS_RO and GEORADIUSBYMEMBER_RO variants — scroll down to the read-only section, it's right there 👇

The classic glow-up use case here is grabbing geospatial items near a specific point, no farther than a given amount of meters (or whatever unit you vibe with). Like, literally: suggesting nearby places to mobile users in your app. main character location services energy fr fr 📍

The radius goes in one of these units:

  • m for meters.
  • km for kilometers.
  • mi for miles.
  • ft for feet.

The command can also hand you extra info if you ask nicely, with these options:

  • WITHDIST: also return the distance of the returned items from the specified center. and bestie, that distance comes back in the same unit you passed as the radius argument. no sneaky conversions 💅
  • WITHCOORD: also return the longitude,latitude coordinates of the matching items.
  • WITHHASH: also return the raw geohash-encoded sorted set score of the item, as a 52 bit unsigned integer. ngl this one is only useful for low level hacks or debugging — for the general user it's otherwise of little interest. iykyk 🔬

Default behavior? unsorted items. yes, chaos. but you can invoke two different sorting methods with these:

  • ASC: sort returned items from the nearest to the farthest, relative to the center.
  • DESC: sort returned items from the farthest to the nearest, relative to the center.

By default, all the matching items come back. want to cap it? use the COUNT <count> option to limit results to the first N matching items. and when you toss in ANY, the command returns as soon as it's found enough matches — so the results may not be the ones closest to your specified point. but on the other hand, the effort the server puts in is significantly lower. when ANY is not provided, the command does an effort proportional to the number of items matching the specified area and sorts them, so querying very large areas with a very small COUNT option may be slow even if just a few results come back. lowkey a trap, watch out 🪤

By default the command returns the items to the client. but you can store the results instead, with one of these:

  • STORE: store the items in a sorted set populated with their geospatial information.
  • STOREDIST: store the items in a sorted set populated with their distance from the center as a floating point number, in the same unit specified in the radius.

💀 Read-only variants 💀

Okay so here's the tea: since GEORADIUS and GEORADIUSBYMEMBER have a STORE and STOREDIST option, they're technically flagged as writing commands in the Valkey command table. because of that, read-only replicas will flag them, and Valkey Cluster replicas will redirect them to the primary instance even if the connection is in read-only mode (peep the READONLY command of Valkey Cluster).

So two read-only variants got added. they're exactly like the original commands but they refuse the STORE and STOREDIST options. their names? GEORADIUS_RO and GEORADIUSBYMEMBER_RO, and they can safely be used in replicas. slay 🫶

🌈 Alternative 🌈

GEOSEARCH and GEOSEARCHSTORE with the BYRADIUS argument. just saying 👀

🎀 REPLY 🎀

One of the following:

  • If no WITH* option is specified, a valkey-protocol(7) Array reply of matched member names.
  • If WITHCOORD, WITHDIST, or WITHHASH options are specified, the command returns a valkey-protocol(7) Array reply of arrays, where each sub-array represents a single item:
    1. The distance from the center as a floating point number, in the same unit specified in the radius.
    2. The Geohash integer.
    3. The coordinates as a two items x,y array (longitude,latitude).

For example, the command GEORADIUS Sicily 15 37 200 km WITHCOORD WITHDIST will return each item in the following way:

["Palermo","190.4424",["13.361389338970184","38.115556395496299"]]

⭐ COMPLEXITY ⭐

O(N+log(M)) where N is the number of elements inside the bounding box of the circular area delimited by center and radius and M is the number of items inside the index. math is giving iconic 🔥

💅 ACL CATEGORIES 💅

@geo @slow @write

🍓 HISTORY 🍓

  • Available since: 3.2.0
  • Changed in 6.2.0: Added the ANY option for COUNT.
  • Changed in 7.0.0: Added support for uppercase unit names.

🧚 EXAMPLES 🧚

127.0.0.1:6379> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
(integer) 2
127.0.0.1:6379> GEORADIUS Sicily 15 37 200 km WITHDIST
1) 1) "Palermo"
   2) "190.4424"
2) 1) "Catania"
   2) "56.4413"
127.0.0.1:6379> GEORADIUS Sicily 15 37 200 km WITHCOORD
1) 1) "Palermo"
   2) 1) "13.36138933897018433"
      2) "38.11555639549629859"
2) 1) "Catania"
   2) 1) "15.08726745843887329"
      2) "37.50266842333162032"
127.0.0.1:6379> GEORADIUS Sicily 15 37 200 km WITHDIST WITHCOORD
1) 1) "Palermo"
   2) "190.4424"
   3) 1) "13.36138933897018433"
      2) "38.11555639549629859"
2) 1) "Catania"
   2) "56.4413"
   3) 1) "15.08726745843887329"
      2) "37.50266842333162032"

💜 SEE ALSO 💜

geoadd(3valkey), geodist(3valkey), geohash(3valkey), geopos(3valkey), georadiusbymember(3valkey), georadiusbymember_ro(3valkey), georadius_ro(3valkey), geosearch(3valkey), geosearchstore(3valkey)

and that's the whole page bestie!! 🎉 this one's from Valkey version 9.0.0, dated 2025-10-21 — go query some coordinates, you absolute icon 👑✨

📦 where this page comes from