geosearch

Search for members within a geographic area

Usage

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

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

const results = await redis.geosearch(
  "cities",
  { type: "FROMLONLAT", coordinate: { lon: -122.4194, lat: 37.7749 } },
  { type: "BYRADIUS", radius: 100, radiusType: "MI" },
  "ASC"
);

Parameters

key · string · required

The key containing the geospatial index.

centerPoint · CenterPoint · required

The center point to search from:

Show FROMLONLAT - Search from coordinates

{
  type: "FROMLONLAT" | "fromlonlat",
  coordinate: { lon: number, lat: number }
}

Search from specific longitude/latitude coordinates.

Show FROMMEMBER - Search from existing member

{
  type: "FROMMEMBER" | "frommember",
  member: string
}

Search from the position of an existing member.

shape · Shape · required

The search area shape:

Show BYRADIUS - Circular search area

{
  type: "BYRADIUS" | "byradius",
  radius: number,
  radiusType: "M" | "KM" | "FT" | "MI"
}

Search within a circular radius.

Show BYBOX - Rectangular search area

{
  type: "BYBOX" | "bybox",
  rect: { width: number, height: number },
  rectType: "M" | "KM" | "FT" | "MI"
}

Search within a rectangular bounding box.

order · 'ASC' | 'DESC' | 'asc' | 'desc' · required

Sort order:

• ASC - Sort by distance from center (nearest first)
• DESC - Sort by distance from center (farthest first)

options · GeoSearchCommandOptions

Optional search options:

Show options

count · object

Limit the number of results:

{
  limit: number,
  any?: boolean  // Return as soon as enough matches are found
}

withCoord · boolean

Include coordinates in the response.

withDist · boolean

Include distance from center in the response.

withHash · boolean

Include Geohash string in the response.

Response

result · GeoSearchResponse[]

An array of search results, each containing:

Show result properties

member · string

The member name (always included).

dist · number

Distance from the center point (if withDist: true).

coord · { long: number, lat: number }

Coordinates of the member (if withCoord: true).

hash · string

Geohash string of the member (if withHash: true).

Examples

Search by radius from coordinates

// Add some cities
await redis.geoadd(
  "cities",
  { longitude: -122.4194, latitude: 37.7749, member: "San Francisco" },
  { longitude: -122.2711, latitude: 37.8044, member: "Oakland" },
  { longitude: -118.2437, latitude: 34.0522, member: "Los Angeles" },
  { longitude: -121.8863, latitude: 37.3382, member: "San Jose" }
);

// Find cities within 50 miles of San Francisco coordinates
const nearby = await redis.geosearch(
  "cities",
  { type: "FROMLONLAT", coordinate: { lon: -122.4194, lat: 37.7749 } },
  { type: "BYRADIUS", radius: 50, radiusType: "MI" },
  "ASC"
);
// Returns: [
//   { member: "San Francisco" },
//   { member: "Oakland" },
//   { member: "San Jose" }
// ]

Search from existing member

const nearby = await redis.geosearch(
  "cities",
  { type: "FROMMEMBER", member: "San Francisco" },
  { type: "BYRADIUS", radius: 100, radiusType: "MI" },
  "ASC"
);

Include distance and coordinates

const results = await redis.geosearch(
  "cities",
  { type: "FROMMEMBER", member: "San Francisco" },
  { type: "BYRADIUS", radius: 100, radiusType: "MI" },
  "ASC",
  { withDist: true, withCoord: true }
);
// Returns: [
//   {
//     member: "San Francisco",
//     dist: 0,
//     coord: { long: -122.41940104961395, lat: 37.77490009603002 }
//   },
//   {
//     member: "Oakland",
//     dist: 8.7156,
//     coord: { long: -122.27110177278519, lat: 37.80439996259009 }
//   },
//   ...
// ]

Limit results

const results = await redis.geosearch(
  "cities",
  { type: "FROMMEMBER", member: "San Francisco" },
  { type: "BYRADIUS", radius: 500, radiusType: "MI" },
  "ASC",
  { count: { limit: 3 }, withDist: true }
);
// Returns only the 3 nearest cities

Search by rectangular box

const results = await redis.geosearch(
  "cities",
  { type: "FROMLONLAT", coordinate: { lon: -122.4194, lat: 37.7749 } },
  { type: "BYBOX", rect: { width: 100, height: 100 }, rectType: "MI" },
  "ASC"
);
// Returns cities within a 100x100 mile box centered on the coordinates

Sort by distance descending

const results = await redis.geosearch(
  "cities",
  { type: "FROMMEMBER", member: "San Francisco" },
  { type: "BYRADIUS", radius: 500, radiusType: "MI" },
  "DESC",  // Farthest first
  { withDist: true }
);

Include all metadata

const results = await redis.geosearch(
  "cities",
  { type: "FROMMEMBER", member: "San Francisco" },
  { type: "BYRADIUS", radius: 100, radiusType: "MI" },
  "ASC",
  {
    withDist: true,
    withCoord: true,
    withHash: true,
    count: { limit: 5 }
  }
);
// Returns: [
//   {
//     member: "San Francisco",
//     dist: 0,
//     hash: "9q8yyk8yuv0",
//     coord: { long: -122.41940104961395, lat: 37.77490009603002 }
//   },
//   ...
// ]

Important Notes

Performance Considerations

• Use count.any: true for better performance when you don’t need exact ordering of all results
• Smaller search areas are faster than larger ones
• Consider using BYBOX for rectangular areas instead of very large radius searches

Coordinate Order

Note that centerPoint uses lon and lat (shortened forms) while the response coord uses long and lat:

// Input: uses 'lon'
{ type: "FROMLONLAT", coordinate: { lon: -122.4194, lat: 37.7749 } }

// Output: uses 'long'
{ member: "...", coord: { long: -122.4194, lat: 37.7749 } }

Distance Units

Unit	Abbreviation
Meters	M
Kilometers	KM
Feet	FT
Miles	MI