geoadd

Add one or more geospatial items to a key

Usage

import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: "<UPSTASH_REDIS_URL>",
  token: "<UPSTASH_REDIS_TOKEN>",
});

await redis.geoadd("locations", {
  longitude: -122.4194,
  latitude: 37.7749,
  member: "San Francisco"
});

Parameters

key · string · required

The key to store the geospatial index.

member · GeoMember | GeoMember[] · required

One or more geospatial members to add. Each member includes:

Show GeoMember properties

longitude · number · required

The longitude coordinate. Note: Redis expects longitude first, then latitude.

Valid range: -180 to 180 degrees

latitude · number · required

The latitude coordinate.

Valid range: -85.05112878 to 85.05112878 degrees

member · string | number · required

The unique identifier for this location.

options · GeoAddCommandOptions

Optional configuration:

Show options

nx · boolean

Only add new elements. Don’t update existing elements.

xx · boolean

Only update existing elements. Don’t add new elements.

ch · boolean

Return the number of changed elements instead of just added elements. Only works with xx option.

Response

result · number | null

The number of elements added to the sorted set (not including elements already existing for which the score was updated).

Returns null when used with xx or nx options and the conditions are not met.

Examples

Add a single location

const added = await redis.geoadd("cities", {
  longitude: -0.1276,
  latitude: 51.5074,
  member: "London"
});
// Returns: 1

Add multiple locations

const added = await redis.geoadd(
  "cities",
  {
    longitude: -122.4194,
    latitude: 37.7749,
    member: "San Francisco"
  },
  {
    longitude: -118.2437,
    latitude: 34.0522,
    member: "Los Angeles"
  },
  {
    longitude: -73.935242,
    latitude: 40.730610,
    member: "New York"
  }
);
// Returns: 3

Only add new locations (nx)

// First add
await redis.geoadd("cities", {
  longitude: 2.3522,
  latitude: 48.8566,
  member: "Paris"
});

// Try to add again with nx option
const result = await redis.geoadd(
  "cities",
  { nx: true },
  {
    longitude: 2.3522,
    latitude: 48.8566,
    member: "Paris" // Already exists
  }
);
// Returns: 0 (nothing added)

Update existing locations only (xx)

const updated = await redis.geoadd(
  "cities",
  { xx: true, ch: true },
  {
    longitude: -0.1278, // Updated coordinates
    latitude: 51.5075,
    member: "London" // Must already exist
  }
);
// Returns: 1 if updated, 0 if member doesn't exist

Important Notes

Coordinate Order

Redis stores geospatial data as a sorted set using the Geohash technique. The coordinate order is longitude first, then latitude:

// ✅ Correct - longitude first
{
  longitude: -122.4194,  // longitude (x-axis)
  latitude: 37.7749,     // latitude (y-axis)
  member: "San Francisco"
}

// ❌ Don't confuse with latitude/longitude order used in some other systems

Valid Ranges

• Longitude: -180 to 180 degrees
• Latitude: -85.05112878 to 85.05112878 degrees

Coordinates outside these ranges will return an error.