GEOADD(3valkey)

💖 GEOADD — the valkey geospatial glow-up 💖

ok so this is GEOADD from the valkey command manual (section 3valkey), and bestie, it is the way to drop pins on a map. let's get into it 🗺️✨

---

✨ NAME ✨

geoadd — adds one or more members to a geospatial index. the key gets created if it doesn't exist. no cap.

---

🎀 SYNOPSIS 🎀

GEOADD key [NX | XX] [CH] longitude latitude member [longitude latitude
member ...]

---

🌸 DESCRIPTION 🌸

so basically you're adding geospatial items — that's (longitude, latitude, name) triples — to the key you picked. the data lives inside that key as a sorted set, and it's stored in a way that lets you query everything later with the valkey-geosearch(7) GEOSEARCH command. it's giving organized. it's giving queryable. 💅

the command takes args in the standard x,y format, which means longitude comes BEFORE latitude. do not flip them, i am begging. 🙈

there are limits on which coordinates you can index: areas super close to the poles are not indexable. the exact limits, as specified by EPSG:900913 / EPSG:3785 / OSGEO:41001, are:

• valid longitudes are from -180 to 180 degrees.
• valid latitudes are from -85.05112878 to 85.05112878 degrees.

if you try to index coordinates outside those ranges, the command will report an error. so like, don't.

📝 note: there is no GEODEL command, because you can just use valkey-zrem(7) ZREM to remove elements. the Geo index structure is literally just a sorted set. the way that it's just a sorted set?? iconic behavior.

🫶 GEOADD options 🫶

GEOADD also gives you these options:

• XX — only update elements that already exist. never add new elements. it's giving "if you know you know, but if you're new, no entry."
• NX — don't update already-existing elements. always add new elements. brand new besties only ✨
• CH — modifies the return value from the number of new elements added to the total number of elements changed (CH is short for changed). "changed elements" means new elements added plus existing elements whose coordinates got updated. so elements you list that end up with the same score they already had are not counted. note: normally, the return value of GEOADD only counts the number of new elements added.

⚠️ note: XX and NX are mutually exclusive. pick one, you cannot have both, it's not that kind of party.

🔥 How does it work? 🔥

the sorted set gets populated using a technique called Geohash. latitude and longitude bits get interleaved to form a unique 52-bit integer, and we know a sorted set double score can represent a 52-bit integer without losing precision. math girlies stay winning 📐

this format allows bounding box and radius querying by checking the 1+8 areas needed to cover the whole shape, then discarding elements outside it. the areas get checked by calculating the range of the box covered, removing enough bits from the less significant part of the sorted set score, and computing the score range to query in the sorted set for each area. yes it's a whole thing. yes it slaps.

🌈 What Earth model does it use? 🌈

the model assumes Earth is a sphere, since it uses the Haversine formula to calculate distance. that formula is only an approximation when applied to the actual Earth, which is not a perfect sphere. the introduced errors are not an issue when it's used by, say, social networks and similar apps that need this kind of querying. however, in the worst case the error can be up to 0.5%, so for error-critical applications you might wanna consider other systems. not me being honest about my flaws 💀

---

⭐ REPLY ⭐

valkey-protocol(7) Integer reply: when used without optional arguments, it's the number of elements added to the sorted set (excluding score updates). if the CH option is specified, it's the number of elements that were changed (added or updated).

---

👑 COMPLEXITY 👑

O(log(N)) for each item added, where N is the number of elements in the sorted set.

---

🦋 ACL CATEGORIES 🦋

@geo @slow @write

---

💜 HISTORY 💜

• available since: 3.2.0
• changed in 6.2.0: added the CH, NX and XX options.

---

🍓 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> GEODIST Sicily Palermo Catania
"166274.1516"
127.0.0.1:6379> GEORADIUS Sicily 15 37 100 km
1) "Catania"
127.0.0.1:6379> GEORADIUS Sicily 15 37 200 km
1) "Palermo"
2) "Catania"

---

🌟 SEE ALSO 🌟

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

---

ok that's the whole page, you're so welcome 🫶 this was valkey 9.0.0, dated 2025-10-21, straight from the Valkey Command Manual. go add some coordinates, bestie, and remember: longitude first. always. 💅✨