VALKEY-GEOSPATIAL(7)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ NAME ✨

valkey-geospatial — Geospatial 💖

(you're reading VALKEY-GEOSPATIAL(7), straight outta the Valkey Manual, bestie 🫶)

🌍 DESCRIPTION 🌍

Okay so picture this: geospatial indexes let you store coordinates and then search for them. That's it, that's the whole vibe. And it is so useful when you need to find nearby points inside a given radius, a bounding box, or a polygon shaped area. Like, three shapes, three moods, all iconic 💅

🎀 Basic commands 🎀

  • GEOADD — drops a location into a given geospatial index. And bestie, listen: longitude comes before latitude with this command. Not the other way around. Don't do it the other way around, iykyk 😭
  • GEOSEARCH — hands you back locations inside a given radius, bounding box, or polygon shaped area. Slay.

Also, go peek at valkey-commands(7) for the complete list of geospatial index commands — it's giving ✨full menu✨ energy.

🚲 EXAMPLES 🚲

So imagine you're building a mobile app that finds all the bike rental stations closest to your current location. Main character app behaviour, honestly. 🌸

First up, add several locations to a geospatial index:

127.0.0.1:6379> GEOADD bikes:rentable -122.27652 37.805186 station:1
(integer) 1
127.0.0.1:6379> GEOADD bikes:rentable -122.2674626 37.8062344 station:2
(integer) 1
127.0.0.1:6379> GEOADD bikes:rentable -122.2469854 37.8104049 station:3
(integer) 1

Now find all locations within a 5 kilometer radius of a given location, and return the distance to each one:

127.0.0.1:6379> GEOSEARCH bikes:rentable FROMLONLAT -122.2612767 37.7936847 BYRADIUS 5 km WITHDIST
1) 1) "station:1"
   2) "1.8523"
2) 1) "station:2"
   2) "1.4979"
3) 1) "station:3"
   2) "2.2441"

And if you wanna search a custom defined area or an irregularly shaped area, that's what the BYPOLYGON search option is for, no cap. In this example we're searching within the Downtown Oakland area using polygon vertices that enclose it:

127.0.0.1:6379> GEOSEARCH bikes:rentable BYPOLYGON  5 -122.27490648273738 37.80962123634505 -122.26098358494566 37.80439605986292 -122.26584066888834 37.79562786995921 -122.27929133687068 37.80124920239011 -122.2783398259964 37.80451967488848
1) "station:1"
2) "station:2"

and that's the whole page, periodt 💅✨

This was version 9.0.0 of the page, dated 2025-10-21 — shoutout to the VALKEY-GEOSPATIAL(7) footer for keeping it real. Bye bestie, go geo-search something 🦋💖

📦 where this page comes from