Skip to main content
Version: 2.x

Geo

The geo commands store longitude and latitude pairs in a sorted set and answer distance and radius queries over them. This page documents the eight geo commands and the option types they accept.

All commands are methods on the Redis service. Keys and members are encoded with the configured CodecSupplier. See Getting Started for how to build the layer.

Commandsโ€‹

The commands are grouped below by purpose:

GroupMethodRedis CommandResult
AddRedis#geoAddGEOADDLong
InspectRedis#geoDistGEODISTOption[Double]
InspectRedis#geoHashGEOHASHChunk[Option[String]]
InspectRedis#geoPosGEOPOSChunk[Option[LongLat]]
SearchRedis#geoRadiusGEOSEARCH (FROMLONLAT)Chunk[GeoView]
SearchRedis#geoRadiusByMemberGEOSEARCH (FROMMEMBER)Chunk[GeoView]
StoreRedis#geoRadiusStoreGEOSEARCHSTORE (FROMLONLAT)Long
StoreRedis#geoRadiusByMemberStoreGEOSEARCHSTORE (FROMMEMBER)Long

The search commands are sent as GEOSEARCH and GEOSEARCHSTORE, so they require Redis 6.2 or later. None of the commands uses returning, because the member name is always read back as a String.

Option Typesโ€‹

The following types are available after import zio.redis._:

TypeShapeUsed by
LongLatLongLat(longitude: Double, latitude: Double)geoAdd, geoPos, geoRadius and more
RadiusUnitMeters, Kilometers, Feet or MilesgeoDist and every radius command
WithCoordSingleton WithCoord, adds the position to each resultgeoRadius, geoRadiusByMember
WithDistSingleton WithDist, adds the distance from the center to each resultgeoRadius, geoRadiusByMember
WithHashSingleton WithHash, adds the raw geohash integer to each resultgeoRadius, geoRadiusByMember
CountCount(count: Long)Radius commands
OrderOrder.Ascending or Order.DescendingRadius commands
StoreStore(key: String), the destination keyStoreResults, StoreBoth
StoreDistStoreDist(key: String)StoreDistances, StoreBoth
StoreOptionsStoreResults, StoreDistances or StoreBothgeoRadiusStore, geoRadiusByMemberStore
GeoViewGeoView(member, dist, hash, longLat) where the last three are OptionsResult of the search commands

A GeoView only has the optional fields that were requested with WithDist, WithHash and WithCoord. The others are None.

Adding Membersโ€‹

Redis#geoAdd takes a key and at least one pair of a LongLat and a member. It returns the number of new members added. The LongLat is built with the longitude first, then the latitude:

import zio._
import zio.redis._

def addCities(redis: Redis): IO[RedisError, Long] =
redis.geoAdd(
"cities",
(LongLat(13.361389, 38.115556), "Palermo"),
(LongLat(15.087269, 37.502669), "Catania")
)

Inspecting Membersโ€‹

Redis#geoDist returns the distance between two members, or None if either one is missing. The unit defaults to meters when radiusUnit is None:

import zio._
import zio.redis._

def distance(redis: Redis): IO[RedisError, Option[Double]] =
redis.geoDist("cities", "Palermo", "Catania", Some(RadiusUnit.Kilometers))

Redis#geoPos and Redis#geoHash return one entry per requested member, with None for members that do not exist:

import zio._
import zio.redis._

def positions(redis: Redis): IO[RedisError, (Chunk[Option[LongLat]], Chunk[Option[String]])] =
for {
pos <- redis.geoPos("cities", "Palermo", "Catania")
hashes <- redis.geoHash("cities", "Palermo", "Catania")
} yield (pos, hashes)

Searching by Radiusโ€‹

Redis#geoRadius finds members within a radius of a coordinate, and Redis#geoRadiusByMember does the same around an existing member. Both accept the optional withCoord, withDist, withHash, count and order parameters, and return a Chunk[GeoView]:

import zio._
import zio.redis._

def nearby(redis: Redis): IO[RedisError, Chunk[GeoView]] =
redis.geoRadius(
"cities",
LongLat(15.0, 37.0),
200.0,
RadiusUnit.Kilometers,
withDist = Some(WithDist),
count = Some(Count(5)),
order = Some(Order.Ascending)
)

To search around a member that is already in the key, pass the member instead of a coordinate. Here the position is also returned:

import zio._
import zio.redis._

def aroundPalermo(redis: Redis): IO[RedisError, Chunk[(String, Option[LongLat])]] =
redis
.geoRadiusByMember("cities", "Palermo", 200.0, RadiusUnit.Kilometers, withCoord = Some(WithCoord))
.map(_.map(view => (view.member, view.longLat)))

Storing Search Resultsโ€‹

Redis#geoRadiusStore and Redis#geoRadiusByMemberStore write the matches into another key and return how many members were stored. They take a StoreOptions value instead of the with* flags. Use StoreResults to store the matching members:

import zio._
import zio.redis._

def storeNearby(redis: Redis): IO[RedisError, Long] =
redis.geoRadiusStore(
"cities",
LongLat(15.0, 37.0),
200.0,
RadiusUnit.Kilometers,
StoreResults(Store("cities:nearby")),
count = Some(Count(10))
)

The StoreDistances variant stores the distances in a second key with STOREDIST, and StoreBoth stores the members and the distances in two keys. To store both, pass a Store and a StoreDist:

import zio._
import zio.redis._

def storeNearbyWithDistances(redis: Redis): IO[RedisError, Long] =
redis.geoRadiusStore(
"cities",
LongLat(15.0, 37.0),
200.0,
RadiusUnit.Kilometers,
StoreBoth(Store("cities:nearby"), StoreDist("cities:distances")),
count = Some(Count(10))
)

Next Stepsโ€‹

  • Sorted Sets explains the structure that geo members are stored in, so commands such as Redis#zRem and Redis#zCard work on geo keys.
  • Keys covers expiry and deletion.

ZIO Chat

๐ŸŒŸ Greetings from ZIO Chat! ๐ŸŒŸ Have questions about ZIO? Look no further! I'm here to be your ZIO guru. Whether you're a seasoned pro or just starting out, I've got answers tailored just for you. Fire away with your ZIO queries, and I'll hit you back with the best insights I've got. Let's dive into the world of ZIO together!