georadius
GEORADIUS
GEORADIUS key longitude latitude radius m|km|ft|mi [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count] [ASC|DESC] [STORE key] [STOREDIST key]
Return the members of a sorted set populated with geospatial information using GEOADD, which are within the borders of the area specified with the center location and the maximum distance from the center (the radius)-
The common use case for this command is to retrieve geospatial items near a specified point and no far than a given amount of meters (or other units)- This allows, for example, to suggest mobile users of an application nearby places-
The radius is specified in one of the following units:
- m for meters-
- km for kilometers-
- mi for miles-
- ft for feet-
The command optionally returns additional information using the following options:
-
WITHDIST
: Also return the distance of the returned items from the specified center- The distance is returned in the same unit as the unit specified as the radius argument of the command- -
WITHCOORD
: Also return the longitude,latitude coordinates 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-
The command default is to return unsorted items- Two different sorting methods can be invoked using the following two options:
-
ASC
: Sort returned items from the nearest to the farthest, relative to the center- -
DESC
: Sort returned items from the farthest to the nearest, relative to the center-
By default all the matching items are returned- It is possible to limit the results to the first N matching items by using the COUNT <count>
option- However note that internally the command needs to perform an effort proportional to the number of items matching the specified area, so to query very large areas with a very small COUNT
option may be slow even if just a few results are returned- On the other hand COUNT
can be a very effective way to reduce bandwidth usage if normally just the first results are used-
Return value
Array reply, specifically:
- Without any
WITH
option specified, the command just returns a linear array like ["New York","Milan","Paris"]. - If
WITHCOORD
,WITHDIST
orWITHHASH
options are specified, the command returns an array of arrays, where each sub-array represents a single item.
When additional information is returned as an array of arrays for each item, the first item in the sub-array is always the name of the returned item. The other information is returned in the following order as successive elements of the sub-array.
- 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).
So for example the command GEORADIUS Sicily 15 37 200 km WITHCOORD WITHDIST
will return each item in the following way:
["Palermo","190.4424",["13.361389338970184","38.115556395496299"]]
Examples
(integer) 2
redis> GEORADIUS Sicily 15 37 200 km WITHDIST 1) 1) "Palermo"
2) "190.4424"
2) 1) "Catania"
2) "56.4413"
redis> GEORADIUS Sicily 15 37 200 km WITHCOORD 1) 1) "Palermo"
2) 1) "13.36138933897018433"
2) "38.11555639549629859"
2) 1) "Catania"
2) 1) "15.08726745843887329"
2) "37.50266842333162032"
redis> GEORADIUS Sicily 15 37 200 km WITHDIST WITHCOORD 1) 1) "Palermo"
2) "190.4424"
3) 1) "13.36138933897018433"
2) "38.11555639549629859"
2) 1) "Catania"
2) "56.4413"
3) 1) "15.08726745843887329"
2) "37.50266842333162032"
© 2009–2017 Salvatore Sanfilippo
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.
https://redis.io/commands/georadius