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
The key containing the geospatial index.
The center point to search from:Show FROMLONLAT - Search from coordinates
{
type: "FROMLONLAT" | "fromlonlat",
coordinate: { lon: number, lat: number }
}
Show FROMMEMBER - Search from existing member
{
type: "FROMMEMBER" | "frommember",
member: string
}
The search area shape:Show BYRADIUS - Circular search area
{
type: "BYRADIUS" | "byradius",
radius: number,
radiusType: "M" | "KM" | "FT" | "MI"
}
Show BYBOX - Rectangular search area
{
type: "BYBOX" | "bybox",
rect: { width: number, height: number },
rectType: "M" | "KM" | "FT" | "MI"
}
order
'ASC' | 'DESC' | 'asc' | 'desc'
required
Sort order:
ASC - Sort by distance from center (nearest first)DESC - Sort by distance from center (farthest first)
Optional search options:
Limit the number of results:{
limit: number,
any?: boolean // Return as soon as enough matches are found
}
Include coordinates in the response.
Include distance from center in the response.
Include Geohash string in the response.
Response
An array of search results, each containing:
The member name (always included).
Distance from the center point (if withDist: true).
coord
{ long: number, lat: number }
Coordinates of the member (if withCoord: true).
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 }
);
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
- 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 |