GEOADD

Syntax text Syntax diagram API methods

GEOADD key [NX | XX] [CH] longitude latitude member [longitude
  latitude member ...]

Client:

geoadd(
    name: KeyT,
    values: Sequence[EncodableT],
    nx: bool = False,
    xx: bool = False,
    ch: bool = False
) → ResponseT

GEOADD(
    key: RedisArgument,
    toAdd: GeoMember | Array<GeoMember>,
    options?: GeoAddOptions
) → Any

geoadd(
    key: byte[],
    longitude: double,
    member: double latitude final byte[]
) → long  // The number of elements added

geoadd(
    key: byte[],
    memberCoordinateMap: Map<byte[], GeoCoordinate>  // Members names with their geo coordinates
) → long  // The number of elements added

geoadd(
    key: byte[],
    params: GeoAddParams,  // Additional options
    memberCoordinateMap: Map<byte[], GeoCoordinate>  // Members names with their geo coordinates
) → long  // The number of elements added

geoadd(
    key: String,
    longitude: double,
    member: double latitude final String
) → long  // The number of elements added

geoadd(
    key: String,
    memberCoordinateMap: Map<String, GeoCoordinate>  // Members names with their geo coordinates
) → long  // The number of elements added

geoadd(
    key: K,  // the key of the geo set.
    longitude: double,
    latitude: double,
    member: V
) → Long  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    longitude: double,
    latitude: double,
    member: V,
    args: GeoAddArgs  // additional arguments.
) → Long  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    lngLatMember: Object...
) → Long  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    values: GeoValue<V>...  // io.lettuce.core.GeoValue values to add.
) → Long  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    args: GeoAddArgs,  // additional arguments.
    lngLatMember: Object...
) → Long  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    longitude: double,
    latitude: double,
    member: V
) → RedisFuture<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    longitude: double,
    latitude: double,
    member: V,
    args: GeoAddArgs  // additional arguments.
) → RedisFuture<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    lngLatMember: Object...
) → RedisFuture<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    values: GeoValue<V>...  // io.lettuce.core.GeoValue values to add.
) → RedisFuture<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    args: GeoAddArgs,  // additional arguments.
    lngLatMember: Object...
) → RedisFuture<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    longitude: double,
    latitude: double,
    member: V
) → Mono<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    longitude: double,
    latitude: double,
    member: V,
    args: GeoAddArgs  // additional arguments.
) → Mono<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    lngLatMember: Object...
) → Mono<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    values: GeoValue<V>...  // io.lettuce.core.GeoValue values to add.
) → Mono<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

geoadd(
    key: K,  // the key of the geo set.
    args: GeoAddArgs,  // additional arguments.
    lngLatMember: Object...
) → Mono<Long>  // Long integer-reply the number of elements that were added to the set. @since 6.1

GeoAdd(
    ctx: context.Context,
    key: string,
    geoLocation: ...*GeoLocation
) → *IntCmd

GeoAdd(
    key: RedisKey,  // The key of the set.
    longitude: double,
    latitude: double,
    member: RedisValue,
    flags: CommandFlags  // The flags to use for this operation.
) → bool  // The number of elements that were added to the set, not including all the elements already present into the set.

GeoAdd(
    key: RedisKey,  // The key of the set.
    value: GeoEntry,
    flags: CommandFlags  // The flags to use for this operation.
) → bool  // The number of elements that were added to the set, not including all the elements already present into the set.

GeoAdd(
    key: RedisKey,  // The key of the set.
    values: GeoEntry[],  // The geo values add to the set.
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The number of elements that were added to the set, not including all the elements already present into the set.

GeoAdd(
    key: RedisKey,  // The key of the set.
    longitude: double,
    latitude: double,
    member: RedisValue,
    flags: CommandFlags  // The flags to use for this operation.
) → bool  // The number of elements that were added to the set, not including all the elements already present into the set.

GeoAdd(
    key: RedisKey,  // The key of the set.
    value: GeoEntry,
    flags: CommandFlags  // The flags to use for this operation.
) → bool  // The number of elements that were added to the set, not including all the elements already present into the set.

GeoAdd(
    key: RedisKey,  // The key of the set.
    longitude: double,
    latitude: double,
    member: RedisValue,
    flags: CommandFlags  // The flags to use for this operation.
) → bool  // The number of elements that were added to the set, not including all the elements already present into the set.

GeoAdd(
    key: RedisKey,  // The key of the set.
    value: GeoEntry,
    flags: CommandFlags  // The flags to use for this operation.
) → bool  // The number of elements that were added to the set, not including all the elements already present into the set.

GeoAdd(
    key: RedisKey,  // The key of the set.
    values: GeoEntry[],  // The geo values add to the set.
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The number of elements that were added to the set, not including all the elements already present into the set.

GeoAdd(
    key: RedisKey,  // The key of the set.
    longitude: double,
    latitude: double,
    member: RedisValue,
    flags: CommandFlags  // The flags to use for this operation.
) → bool  // The number of elements that were added to the set, not including all the elements already present into the set.

GeoAdd(
    key: RedisKey,  // The key of the set.
    value: GeoEntry,
    flags: CommandFlags  // The flags to use for this operation.
) → bool  // The number of elements that were added to the set, not including all the elements already present into the set.

geoadd(
    $key: string,
    $longitude: Any,
    $latitude: Any,
    $member: Any
) → int

geo_add(
    key: K,
    members: M
) → (usize)

geo_add(
    key: K,
    members: M
) → (usize)

Available since:: Redis Open Source 3.2.0
Time complexity:: O(log(N)) for each item added, where N is the number of elements in the sorted set.
ACL categories:: @write, @geo, @slow,
Compatibility:: Redis Software and Redis Cloud compatibility

Adds the specified geospatial items (longitude, latitude, name) to the specified key. Data is stored into the key as a sorted set, in a way that makes it possible to query the items with the GEOSEARCH command.

The command takes arguments in the standard format x,y so the longitude must be specified before the latitude. There are limits to the coordinates that can be indexed: areas very near to the poles are not indexable.

The exact limits, as specified by EPSG:900913 / EPSG:3785 / OSGEO:41001 are the following:

Valid longitudes are from -180 to 180 degrees.
Valid latitudes are from -85.05112878 to 85.05112878 degrees.

The command will report an error when the user attempts to index coordinates outside the specified ranges.

Note: there is no GEODEL command because you can use ZREM to remove elements. The Geo index structure is just a sorted set.

GEOADD options

GEOADD also provides the following options:

XX: Only update elements that already exist. Never add elements.
NX: Don't update already existing elements. Always add new elements.
CH: Modify the return value from the number of new elements added, to the total number of elements changed (CH is an abbreviation of changed). Changed elements are new elements added and elements already existing for which the coordinates was updated. So elements specified in the command line having the same score as they had in the past are not counted. Note: normally, the return value of GEOADD only counts the number of new elements added.

Note: The XX and NX options are mutually exclusive.

How does it work?

The way the sorted set is populated is using a technique called Geohash. Latitude and Longitude bits are interleaved to form a unique 52-bit integer. We know that a sorted set double score can represent a 52-bit integer without losing precision.

This format allows for bounding box and radius querying by checking the 1+8 areas needed to cover the whole shape and discarding elements outside it. The areas are checked by calculating the range of the box covered, removing enough bits from the less significant part of the sorted set score, and computing the score range to query in the sorted set for each area.

What Earth model does it use?

The model assumes that the Earth is a sphere since it uses the Haversine formula to calculate distance. This formula is only an approximation when applied to the Earth, which is not a perfect sphere. The introduced errors are not an issue when used, for example, by social networks and similar applications requiring this type of querying. However, in the worst case, the error may be up to 0.5%, so you may want to consider other systems for error-critical applications.

Examples

Redis Software and Redis Cloud compatibility

Redis Software	Redis Cloud	Notes
✅ Standard ✅ Active-Active	✅ Standard ✅ Active-Active

Return information

RESP2 RESP3

Integer reply: When used without optional arguments, the number of elements added to the sorted set (excluding score updates). If the CH option is specified, the number of elements that were changed (added or updated).

History

Starting with Redis version 6.2.0: Added the CH, NX and XX options.

Products

Tools

Get Redis

Connect

Learn

Latest

See how it works