Tutorial

Redis Geo Commands Tutorial: Location-Based Queries and Search

February 25, 202617 minute read

Prasan Rajpurohit

William Johnston

Redis GEO commands let you store latitude/longitude coordinates and run proximity queries entirely in memory. Use GEOADD to index locations, GEOSEARCH to find items within a radius, and GEODIST to calculate distances — all with sub-millisecond latency. This tutorial walks through a complete e-commerce example: indexing store locations, querying nearby inventory, and exposing the results through a REST API.

#What you will learn in this tutorial

How to store and index geospatial data in Redis using GEO commands
How to perform radius-based proximity searches with FT.SEARCH and FT.AGGREGATE
How to set up Redis OM for geospatial indexing in a Node.js project
How to build a REST API endpoint for location-based product search
How to sort and filter results by distance from a user's location

#What does the demo application look like?

GITHUB CODE

Below is a command to the clone the source code for the application used in this tutorial

git clone --branch v10.1.0 https://github.com/redis-developer/redis-microservices-ecommerce-solutions

The demo application uses a microservices architecture:

1. products service: handles querying products from the database and returning them to the frontend

2. orders service: handles validating and creating orders

3. order history service: handles querying a customer's order history

4. payments service: handles processing orders for payment

5. api gateway: unifies the services under a single endpoint

6. mongodb/ postgresql: serves as the write-optimized database for storing orders, order history, products, etc.

TIP

You don't need to use MongoDB/ Postgresql as your write-optimized database in the demo application; you can use other prisma supported databases as well. This is just an example.

The e-commerce microservices application consists of a frontend, built using Next.js with TailwindCSS. The application backend uses Node.js. The data is stored in Redis and either MongoDB or PostgreSQL, using Prisma. Below are screenshots showcasing the frontend of the e-commerce app.

Dashboard: Displays a list of products with different search functionalities, configurable in the settings page.

E-commerce app dashboard showing a product grid with search bar, filters, and product cards displaying images, names, and prices

Settings: Accessible by clicking the gear icon at the top right of the dashboard. Control the search bar, chatbot visibility, and other features here.

Settings page with toggle switches for enabling geo location search, vector search, and chatbot features

Dashboard (Geo Location Search): Configured for Geo location search, the search bar enables location queries. Note: In our demo, each zipCode location is mapped with lat long coordinates.

Dashboard with geo location search enabled, showing a zip code input field and product results filtered by proximity

Shopping Cart: Add products to the cart and check out using the "Buy Now" button.

Shopping cart sidebar showing selected products with quantities, individual prices, and a total order summary

Order History: Post-purchase, the 'Orders' link in the top navigation bar shows the order status and history.

Order history page listing past orders with order IDs, dates, statuses, and item summaries

Admin Panel: Accessible via the 'admin' link in the top navigation. Displays purchase statistics and trending products.

Admin panel with bar charts showing purchase statistics over time and a table of trending products

#What are Redis GEO commands?

Redis GEO commands are a set of built-in commands for storing and querying geospatial data. They use a sorted set under the hood, encoding latitude and longitude pairs into geohash values for efficient indexing. The core commands include:

GEOADD — add members with longitude/latitude coordinates to a sorted set
GEOSEARCH — find members within a given radius or bounding box
GEODIST — calculate the distance between two members
GEOPOS — retrieve the coordinates of one or more members
GEOHASH — return the geohash string for one or more members

When combined with the RediSearch module, you can also use FT.SEARCH and FT.AGGREGATE to run geospatial queries alongside full-text search, numeric filtering, and aggregation — all in a single command.

#Why use Redis for geo location search?

Geo location search involves querying data based on geographical coordinates (latitude and longitude). Common use cases include finding nearby stores, tracking delivery drivers, building ride-sharing features, and powering "buy-online-pickup-in-store" (BOPIS) experiences.

Redis is well suited for geo location search because:

In-memory speed — geospatial queries execute with sub-millisecond latency and high throughput
Combined queries — RediSearch lets you filter by location, text, numeric ranges, and tags in a single query
Real-time updates — inventory and location data can be updated and queried instantly
Simple API — a few commands handle the entire lifecycle from indexing to querying

Consider a multi-store shopping scenario where consumers locate a product online and pick up at the nearest store. Redis enables a real-time view of store inventory and a seamless BOPIS shopping experience. For a deeper look at inventory-specific patterns, see the Real-time Local Inventory Search tutorial.

#How do you set up the database for geo queries?

#What data collections are needed?

The demo application utilizes two primary data collections within Redis to simulate an e-commerce platform's inventory system:

1. products collection: This collection stores detailed information about each product, including name, description, category and price.

Redis Insight browser view showing the products JSON collection with fields for productId, displayName, price, and category

TIP

Utilize Redis Insight to interactively explore your Redis database and execute raw Redis commands in a user-friendly workbench environment.

2. storeInventory collection: This collection maintains the inventory status of products across different store locations. It records the quantity of each product available at various stores, facilitating inventory tracking and management.

Redis Insight browser view showing the storeInventory JSON collection with fields for storeId, storeLocation, productId, and stockQty

For the purpose of this demo, we simulate an e-commerce operation in various regions across New York (US), with each store location identified by a storeId and associated stockQty for products.

Map of the New York region with pins marking each simulated store location used in the demo application

#How do you index geospatial data in Redis?

To enable geo location searches within the storeInventory collection, you need to index the data appropriately. Redis offers multiple methods for creating indexes: using the Command Line Interface (CLI) or using client libraries like Redis OM, node redis, etc.

#Using CLI command

To facilitate geo-spatial queries and other search operations on the storeInventory collection, follow these commands:

#Using Redis OM

For applications leveraging the Node.js environment, Redis OM provides an elegant, object-mapping approach to interact with Redis. Below is an implementation example to set up the index using Redis OM:

#How do you build geo location search queries in Redis?

#How do you search for products within a radius?

Once the data is indexed, you can execute raw Redis queries to perform geo location searches. Here are two sample queries to demonstrate the capabilities:

1. Searching products within a radius: This query finds products within a 50-mile radius of a specific location (New York City) with a particular product name (puma). It combines geo-spatial search with text search to filter results based on both location and product name.

This query leverages the FT.SEARCH command to perform a search within the storeInventory:storeInventoryId:index. It specifies a circular area defined by the center's longitude and latitude and a radius of 50 miles. Additionally, it filters products by availability (@stockQty:[(0 +inf])) and @statusCode indicating an active status ([1 1]), combined with a match on the product display name containing puma.

Redis Insight workbench showing FT.SEARCH query results with matching store inventory entries within 50 miles of New York City

2. Aggregate query for sorted results: This aggregate query extends the first example by sorting the results based on geographical distance from the search location and limiting the results to the first 100.

In this query, FT.AGGREGATE is used to process and transform search results. The APPLY clause calculates the distance between each store location and the specified coordinates, converting the result into miles. The SORTBY clause orders the results by this distance, and LIMIT caps the output to 100 entries, making the query highly relevant for applications requiring sorted proximity-based search results.

Redis Insight workbench showing FT.AGGREGATE results with a distInMiles column calculated for each store entry

#How do you expose geo search through an API?

The getStoreProductsByGeoFilter API endpoint enables clients to search for store products based on geographical location and product name, demonstrating a practical application of Redis geo location search capabilities.

API Request

The request payload specifies the product name to search for, the search radius in miles, and the user's current location in latitude and longitude coordinates.

API Response

The response returns an array of products matching the search criteria, including detailed information about each product and its distance from the user's location.

#How is the geo search API implemented?

This section outlines the implementation of the getStoreProductsByGeoFilter API, focusing on the searchStoreInventoryByGeoFilter function that executes the core search logic.

Function Overview: searchStoreInventoryByGeoFilter accepts an inventory filter object that includes optional product display name, search radius in miles, and user location. It constructs a query to find store products within the specified radius that match the product name.
Query Construction: The function builds a search query using Redis OM's fluent API, specifying conditions for product availability, stock quantity, and proximity to the user's location. It also optionally filters products by name if specified.
Executing the Query: The constructed query is executed against Redis using the ft.aggregate method, which allows for complex aggregations and transformations. The query results are processed to calculate the distance in miles from the user's location and sort the results accordingly.
Result Processing: The function filters out duplicate products across different stores, ensuring unique product listings in the final output. It then formats the store locations into a more readable structure and compiles the final list of products to return.

The implementation demonstrates a practical use case for Redis geo location search, showcasing how to perform proximity searches combined with other filtering criteria (like product name) and present the results in a user-friendly format.

#How do you enable geo search in the frontend?

Make sure to select Geo location search in settings page to enable the feature.

Settings page with the Geo location search toggle switch highlighted and enabled

Within the dashboard, users have the option to select a random zip code and search for products (say titled "puma"). The search results are comprehensively displayed, including essential details such as the product name, available stock quantity, the name of the store, and the distance of the store from the user's selected location.

Dashboard search results for "puma" showing product cards with store name, stock quantity, and distance in miles from the selected zip code

#Next steps

Now that you know how to build geo location search with Redis, here are some ways to go further:

Real-time Local Inventory Search — extend this pattern with real-time inventory availability across multiple store locations
Redis GEO command reference — explore the full set of GEO commands including GEOSEARCHSTORE and bounding box queries
Search and query documentation — learn more about combining geospatial filters with full-text search, numeric ranges, and aggregations
Redis Insight — visualize your Redis data and test geo queries interactively in the workbench
Try Redis Cloud for free — get started with a managed Redis instance that supports all GEO commands and RediSearch

#References

Redis YouTube channel
Clients like Node Redis and Redis OM Node help you to use Redis in Node.js applications.
Redis Insight: To view your Redis data or to play with raw Redis commands in the workbench
Try Redis Cloud for free