W3cubDocs

/Redis

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] [WITHCOORD] [WITHDIST] [WITHHASH]

Return the members of a sorted set populated with geospatial information using GEOADD, which are within the borders of the area specified by a given shape. This command extends the GEORADIUS command, so in addition to searching within circular areas, it supports searching within rectangular areas.

The query's center point is provided by one of these mandatory options:

  • FROMMEMBER: Use the position of the given existing <member> in the sorted set.
  • FROMLONLAT: Use the given <longitude> and <latitude>.

The query's shape is provided by one of these mandatory options:

  • BYRADIUS: Similar to GEORADIUS, search inside circular area according to given <radius>.
  • BYBOX: Search inside an axis-aligned rectangle, determined by <height> and <width>.

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 specified for the radius or height and width arguments.
  • WITHCOORD: Also return the longitude and latitude 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.

By default, the command returns unsorted items. Two different sorting methods can be invoked using one of 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 or WITHHASH 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.

  1. The distance from the center as a floating point number, in the same unit specified in the shape.
  2. The geohash integer.
  3. The coordinates as a two items x,y array (longitude,latitude).

Examples

redis> GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania" (integer) 2 redis> GEOADD Sicily 12.758489 38.788135 "edge1" 17.241510 38.788135 "edge2" (integer) 2 redis> GEOSEARCH Sicily FROMLONLAT 15 37 BYRADIUS 200 km ASC 1) "Catania" 2) "Palermo" redis> GEOSEARCH Sicily FROMLONLAT 15 37 BYBOX 400 400 km ASC 1) "Catania" 2) "Palermo" 3) "edge2" 4) "edge1"

© 2009–2020 Salvatore Sanfilippo
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.
https://redis.io/commands/geosearch