|
| 1 | +--- |
| 2 | +description: "Learn how to use GEORADIUS to add geographical data to your Dragonfly database by defining latitude and longitude." |
| 3 | +--- |
| 4 | + |
| 5 | +import PageTitle from '@site/src/components/PageTitle'; |
| 6 | + |
| 7 | +# GEORADIUS |
| 8 | + |
| 9 | +<PageTitle title="GEORADIUS Command (Documentation) | Dragonfly" /> |
| 10 | + |
| 11 | +## Syntax |
| 12 | + |
| 13 | + GEORADIUS key longitude latitude radius <M | KM | FT | MI> [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count [ANY]] [ASC | DESC] [STORE key | STOREDIST key] |
| 14 | + |
| 15 | +**Time complexity:** O(N+log(M)) where N is the number of elements inside the bounding box of the circular area delimited by center and radius and M is the number of items inside the index. |
| 16 | + |
| 17 | +**ACL categories:** @write, @geo, @slow |
| 18 | + |
| 19 | +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). |
| 20 | + |
| 21 | +The radius is specified in one of the following units: |
| 22 | +- `m` for meters. |
| 23 | +- `km` for kilometers. |
| 24 | +- `mi` for miles. |
| 25 | +- `ft` for feet. |
| 26 | + |
| 27 | +By default the command returns the items to the client. It is possible to store the results with one of these options: |
| 28 | + |
| 29 | +- `STORE`: Store the items in a sorted set populated with their geospatial information. |
| 30 | +- `STOREDIST`: Store the items in a sorted set populated with their distance from the center as a floating point number, in the same unit specified in the radius. |
| 31 | + |
| 32 | +## Return |
| 33 | + |
| 34 | + - If no `WITH*` option is specified, an array reply of matched member names |
| 35 | + - If `WITHCOORD`, `WITHDIST`, or `WITHHASH` options are specified, the command returns an array reply of arrays, where each sub-array represents a single item: |
| 36 | + - The distance from the center as a floating point number, in the same unit specified in the radius. |
| 37 | + - The Geohash integer. |
| 38 | + - The coordinates as a two items x,y array (longitude,latitude). |
| 39 | + |
| 40 | +The command default is to return unsorted items. Two different sorting methods can be invoked using the following two options: |
| 41 | + |
| 42 | +- `ASC`: Sort returned items from the nearest to the farthest, relative to the center. |
| 43 | +- `DESC`: Sort returned items from the farthest to the nearest, relative to the center. |
| 44 | + |
| 45 | +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` option. When `ANY` is provided the command will return as soon as enough matches are found, so the results may not be the ones closest to the specified point, but on the other hand, the effort invested by the server is significantly lower. When `ANY` is not provided, the command will perform an effort that is proportional to the number of items matching the specified area and sort them, so to query very large areas with a very small `COUNT` option may be slow even if just a few results are returned. |
| 46 | + |
| 47 | +## Examples |
| 48 | + |
| 49 | +```shell |
| 50 | +dragonfly> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania" |
| 51 | +(integer) 2 |
| 52 | +dragonfly> GEORADIUS Sicily 15 37 200 km WITHDIST |
| 53 | +1) 1) "Palermo" |
| 54 | + 2) "190.4424" |
| 55 | +2) 1) "Catania" |
| 56 | + 2) "56.4413" |
| 57 | +dragonfly> GEORADIUS Sicily 15 37 200 km WITHCOORD |
| 58 | +1) 1) "Palermo" |
| 59 | + 2) 1) "13.36138933897018433" |
| 60 | + 2) "38.11555639549629859" |
| 61 | +2) 1) "Catania" |
| 62 | + 2) 1) "15.08726745843887329" |
| 63 | + 2) "37.50266842333162032" |
| 64 | +dragonfly> GEORADIUS Sicily 15 37 200 km WITHDIST WITHCOORD |
| 65 | +1) 1) "Palermo" |
| 66 | + 2) "190.4424" |
| 67 | + 3) 1) "13.36138933897018433" |
| 68 | + 2) "38.11555639549629859" |
| 69 | +2) 1) "Catania" |
| 70 | + 2) "56.4413" |
| 71 | + 3) 1) "15.08726745843887329" |
| 72 | + 2) "37.50266842333162032" |
| 73 | +``` |
0 commit comments