# GEOSEARCH

> Find members of a geospatial index within a radius or a box around a point or a member.

URL: https://docs.hotkv.com/commands/geosearch/

```
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
- 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

| 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

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

```
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

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

[GEOSEARCHSTORE](https://docs.hotkv.com/commands/geosearchstore/index.md), [GEOADD](https://docs.hotkv.com/commands/geoadd/index.md), [GEODIST](https://docs.hotkv.com/commands/geodist/index.md),
[GEORADIUS](https://docs.hotkv.com/commands/georadius/index.md)