Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

GEOSEARCH

Last updated 
GEOSEARCH key <FROMMEMBER member | FROMLONLAT longitude latitude> <BYRADIUS radius <M | KM | FT | MI> | BYBOX width height <M | KM | FT | MI>> [ASC | DESC] [COUNT count [ANY]] [WITHCOORD] [WITHDIST] [WITHHASH]
Group
Geospatial
Complexity
O(N + log M), N being the members in the area searched
Arity
-7 (at least 7 words, counting the command name)
Flags
read-only
Keys
first 1, last 1, step 1
HotKV Cloud
All plans
On-Premise
no license needed

GEOSEARCH returns the members of the geospatial index at key that lie inside a circle or a rectangle. The center is either an existing member or a longitude and latitude.

Options

Section titled “Options”
Option Effect
FROMMEMBER member Center the search on this member’s position.
FROMLONLAT longitude latitude Center the search on this position.
BYRADIUS radius unit Members within radius of the center.
BYBOX width height unit Members within a rectangle width wide (east to west) and height high (north to south), centered on the center.
ASC Nearest first (the default).
DESC Farthest first.
COUNT count Return only the count nearest (or farthest, with DESC) matches.
ANY Accepted with COUNT. HotKV still returns the nearest matches.
WITHCOORD Add each member’s longitude and latitude.
WITHDIST Add each member’s distance from the center, in the unit of the shape.
WITHHASH Add each member’s raw score (its encoded position) as an integer.

Exactly one of FROMMEMBER and FROMLONLAT, and exactly one of BYRADIUS and BYBOX, is required. Units are M, KM, FT and MI, in any case. Options can come in any order.

Return value

Section titled “Return value”

Without WITH... options, an array of member names. With any of them, an array of arrays: the member name, then the distance (bulk string, 4 decimals), the hash (integer) and the coordinates ([longitude, latitude]), in that order, for the options given.

Case RESP2 RESP3
Matches Array as described Array; coordinates are doubles
No matches, or no such key Empty array Empty array

Error replies:

  • ERR exactly one of FROMMEMBER or FROMLONLAT can be specified for GEOSEARCH
  • ERR exactly one of BYRADIUS and BYBOX can be specified for GEOSEARCH
  • ERR could not decode requested zset member when the FROMMEMBER member is not in the set.
  • ERR the ANY argument requires COUNT argument and ERR COUNT must be > 0
  • ERR need numeric radius, ERR radius cannot be negative, ERR need numeric width, ERR need numeric height, ERR height or width cannot be negative
  • ERR unsupported unit provided. please use M, KM, FT, MI
  • ERR syntax error for an unknown or repeated option, and WRONGTYPE.

Examples

Section titled “Examples”
127.0.0.1:6379> GEOADD cities -0.1276 51.5072 london 2.3522 48.8566 paris 4.3517 50.8503 brussels 4.9041 52.3676 amsterdam
(integer) 4
127.0.0.1:6379> GEOSEARCH cities FROMLONLAT 2 50 BYRADIUS 250 km WITHDIST
1) 1) "paris"
   2) "129.7029"
2) 1) "brussels"
   2) "191.5969"
3) 1) "london"
   2) "224.7426"
127.0.0.1:6379> GEOSEARCH cities FROMMEMBER brussels BYBOX 300 500 km DESC
1) "paris"
2) "amsterdam"
3) "brussels"
127.0.0.1:6379> GEOSEARCH cities FROMLONLAT 2 50 BYRADIUS 250 km COUNT 1 WITHCOORD
1) 1) "paris"
   2) 1) "2.35219806432724"
      2) "48.8565995303493"

Compatibility

Section titled “Compatibility”

Same options and errors as Redis 7 and Valkey 8, with two differences in ordering: HotKV always sorts results by distance (nearest first unless you pass DESC), where Redis leaves them unsorted when neither ASC, DESC nor COUNT is given; and with COUNT ... ANY HotKV returns the nearest matches rather than the first ones found.

See also

Section titled “See also”

GEOSEARCHSTORE, GEOADD, GEODIST, GEORADIUS