GEOSEARCH(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ GEOSEARCH — the valkey command manual page, but make it cute ✨

okay bestie, sit down, hydrate, because this one is a whole vibe. we're talking GEOSEARCH(3valkey), straight outta the Valkey Command Manual, and it's literally the glow-up of geospatial queries. 💖

🌸 NAME 🌸

geosearch — Queries a geospatial index for members inside an area of a box, circle, or a polygon.

(it's giving "find my friends but make it coordinates" 🗺️✨)

🎀 SYNOPSIS 🎀

GEOSEARCH key [FROMMEMBER member | FROMLONLAT longitude latitude]
<BYRADIUS radius <M | KM | FT | MI> | BYBOX width height <M | KM | FT |
MI> | BYPOLYGON num-vertices longitude latitude [longitude latitude
...]> [ASC | DESC] [COUNT count [ANY]] [WITHCOORD] [WITHDIST] [WITHHASH]

💅 DESCRIPTION 💅

So here's the tea. This command returns the members of a sorted set — one that's been populated with geospatial info via valkey-geoadd(7) GEOADD — that live inside the borders of whatever shape you specify. 🫶

And the way it's built? It literally extends the valkey-georadius(7) GEORADIUS command, so on top of searching in circles, it also handles rectangular areas and polygon shaped areas. versatility, slay. 👑

no cap: this command should be used in place of the deprecated GEORADIUS and valkey-georadiusbymember(7) GEORADIUSBYMEMBER commands. those two are the old era, we don't stan them anymore. 💀

🔷 the shape options (mandatory, pick exactly one)

The query's shape is provided by one of these mandatory options:

  • BYRADIUS — Similar to GEORADIUS, search inside circular area according to given <radius>.
  • BYBOX — Search inside an axis-aligned rectangle, determined by <height> and <width>.
  • BYPOLYGON — Search within an area enclosed by the polygon vertices, determined by <num-vertices> <lon> <lat> [<lon> <lat> ...].

📍 the center point options (mandatory for BYBOX and BYRADIUS)

For BYBOX and BYRADIUS based queries, the center point is provided by one of these mandatory options:

  • FROMMEMBER — Use the position of the given existing <member> in the sorted set.
  • FROMLONLAT — Use the given <longitude> and <latitude> position.

In case of BYPOLYGON based queries, the center point and the bounding box are computed based on the polygon vertices of the command. With this option, providing FROMMEMBER or FROMLONLAT is invalid. 🚫 (don't do it, bestie, the server will simply not be having it)

🎁 the bonus info options

The command optionally returns additional information using the following options:

  • WITHDIST — Also return the distance of the returned items from the specified center point. The distance is returned in the same unit as specified for the radius or height and width arguments.
  • WITHCOORD — Also return the longitude and latitude of the matching items.
  • WITHHASH — Also return the raw geohash-encoded sorted set score of the item, in the form of a 52 bit unsigned integer. This is only useful for low level hacks or debugging and is otherwise of little interest for the general user. 🙈 (iykyk, it's for the nerds, and I say that with love)

🔀 sorting

Matching items are returned unsorted by default. To sort them, use one of the following two options:

  • ASC — Sort returned items from the nearest to the farthest, relative to the center point.
  • DESC — Sort returned items from the farthest to the nearest, relative to the center point.

🔢 limiting with COUNT

All matching items are returned by default. To limit the results to the first N matching items, use the COUNT <count> option. When the ANY option is used, the command returns as soon as enough matches are found. This means that the results returned may not be the ones closest to the specified point, but the effort invested by the server to generate them is significantly less. When ANY is not provided, the command will perform an effort that is proportional to the number of items matching the specified area and sort them, so to query very large areas with a very small COUNT option may be slow even if just a few results are returned. 😭 (yes queen, ANY is the shortcut, but the results might not be the closest ones — trade-offs, periodt)

📬 REPLY 📬

One of the following:

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

⚡ COMPLEXITY ⚡

O(N+log(M)) where N is the number of elements in the grid-aligned bounding box area around the shape provided as the filter and M is the number of items inside the shape

🔐 ACL CATEGORIES 🔐

@geo @read @slow

📜 HISTORY 📜

  • Available since: 6.2.0
  • Changed in 7.0.0: Added support for uppercase unit names.
  • Changed in 9.0.0: Added support for the BYPOLYGON option.

🌈 EXAMPLES 🌈

time for the iconic demo. Sicily map, let's gooo 🍓

127.0.0.1:6379> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
(integer) 2
127.0.0.1:6379> GEOADD Sicily 12.758489 38.788135 "edge1"   17.241510 38.788135 "edge2"
(integer) 2
127.0.0.1:6379> GEOSEARCH Sicily FROMLONLAT 15 37 BYRADIUS 200 km ASC
1) "Catania"
2) "Palermo"
127.0.0.1:6379> GEOSEARCH Sicily FROMLONLAT 15 37 BYBOX 400 400 km ASC WITHCOORD WITHDIST
1) 1) "Catania"
   2) "56.4413"
   3) 1) "15.08726745843887329"
      2) "37.50266842333162032"
2) 1) "Palermo"
   2) "190.4424"
   3) 1) "13.36138933897018433"
      2) "38.11555639549629859"
3) 1) "edge2"
   2) "279.7403"
   3) 1) "17.24151045083999634"
      2) "38.78813451624225195"
4) 1) "edge1"
   2) "279.7405"
   3) 1) "12.7584877610206604"
      2) "38.78813451624225195"
127.0.0.1:6379> GEOSEARCH Sicily BYPOLYGON 5 12.41098696654226 38.05033923003755 15.107936245794182 38.00616649901906 18.148439288534455 38.63804787603499 17.80831874257693 39.50316813110968 12.458468633214036 38.57719533463012
1) "Palermo"
2) "edge2"
127.0.0.1:6379> GEOSEARCH Sicily BYPOLYGON 5 12.41098696654226 38.05033923003755 15.107936245794182 38.00616649901906 18.148439288534455 38.63804787603499 17.80831874257693 39.50316813110968 12.458468633214036 38.57719533463012 ASC WITHCOORD WITHDIST
1) 1) "Palermo"
   2) "166482.0159"
   3) 1) "13.36138933897018433"
      2) "38.11555639549629859"
2) 1) "edge2"
   2) "180861.7725"
   3) 1) "17.24151045083999634"
      2) "38.78813451624225195"

👀 SEE ALSO 👀

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

and that's the whole page, bestie!! 🦋✨ This one's from version 9.0.0, dated 2025-10-21 — so go forth, search your shapes, sort your results, and remember: GEOSEARCH ate and left no crumbs. 💅🎀💖

📦 where this page comes from