Case Study - Geospatial Location with Redis in Spring Boot

📖 Information

Project Definition — Geospatial Location with Redis in Spring Boot

A Spring Boot service that stores vehicle coordinates in Redis GEO and provides REST APIs to:

• Add vehicle locations
• Query nearest vehicles by a point or by a center vehicle
• Calculate distance between two vehicles

All responses are wrapped in a consistent CustomResponse<T> envelope, and paging is returned as CustomPage<T>.

---

End-to-end Flow

1) Add Vehicle Location (POST /api/vehicles/location)

• Client sends a JSON request (VehicleLocationRequest) containing:
  • vehicleName, latitude, longitude
• Service writes the coordinate using Redis GEO (GEOADD) and reads back optional metadata (e.g., geohash).
• Returns:
  • 200 OK with CustomResponse<VehicleLocationResponse>

2) Nearest Vehicles by Point (POST /api/vehicles/nearest/point)

• Client sends a JSON request (FindNearestByPointRequest) containing:
  • longitude, latitude, km
  • optional paging/sorting inherited from CustomPagingRequest
• Service searches Redis GEO using a circle radius query (includes coordinates & distance).
• Returns:
  • 200 OK with CustomResponse<CustomPage<VehicleLocationResponse>>

3) Nearest Vehicles by Center Vehicle (POST /api/vehicles/nearest/member)

• Client sends a JSON request (FindNearestByMemberRequest) containing:
  • centerVehicleName, km
  • optional paging/sorting inherited from CustomPagingRequest
• Service searches Redis GEO around the center vehicle (member-based radius).
• Returns:
  • 200 OK with CustomResponse<CustomPage<VehicleLocationResponse>>

4) Distance Between Two Vehicles (POST /api/vehicles/distance)

• Client sends a JSON request (VehicleDistanceRequest) containing:
  • vehicleA, vehicleB (must be different)
• Service calculates the distance using Redis GEO distance query.
• Returns:
  • 200 OK with CustomResponse<VehicleDistanceResponse>

---

Error Semantics

• 400 Bad Request — Validation errors (@Valid) such as missing fields, invalid ranges (e.g., km < 1), etc.
• 404 Not Found — Vehicle not found (e.g., querying distance or member-center not in Redis).
• 409 Conflict — Vehicle already exists (if your service enforces uniqueness on add).
• 500 Internal Server Error — Redis/data access failures or unexpected errors.

Custom Exceptions (examples)

• VehicleAlreadyExistsException → 409 CONFLICT
• VehicleNotFoundException → 404 NOT_FOUND
• GeoSearchFailedException → 500 INTERNAL_SERVER_ERROR

---

Explore REST APIs

Endpoints Summary

Method	URL	Description	Request Body	Headers	Response	Status Codes
POST	/api/vehicles/location	Add a vehicle location into Redis GEO.	JSON: VehicleLocationRequest	Content-Type: application/json	CustomResponse<VehicleLocationResponse>	200, 400, 409, 500
POST	/api/vehicles/nearest/point	Find nearest vehicles around a longitude/latitude within km radius (paged).	JSON: FindNearestByPointRequest	Content-Type: application/json	CustomResponse<CustomPage<VehicleLocationResponse>>	200, 400, 500
POST	/api/vehicles/nearest/member	Find nearest vehicles around a center vehicle within km radius (paged).	JSON: FindNearestByMemberRequest	Content-Type: application/json	CustomResponse<CustomPage<VehicleLocationResponse>>	200, 400, 404, 500
POST	/api/vehicles/distance	Calculate distance between two vehicles (km).	JSON: VehicleDistanceRequest	Content-Type: application/json	CustomResponse<VehicleDistanceResponse>	200, 400, 404, 500

---

Technologies

• Java 25
• Spring Boot 3.0
• Restful API
• Open Api (Swagger)
• Maven
• Junit5
• Mockito
• Integration Tests
• Mapstruct
• Docker
• Docker Compose
• CI/CD (Github Actions)
• Postman
• Redis
• Kubernetes
• JaCoCo (Test Report)
• AOP

---

Postman

Import postman collection under postman_collection folder

---

Prerequisites

Define Variable in .env file

REDIS_HOST=localhost
REDIS_PORT=6379

---

Open Api (Swagger)

http://localhost:1441/swagger-ui/index.html

JaCoCo (Test Report)

After the command named mvn clean install completes, the JaCoCo report will be available at:

target/site/jacoco/index.html

Navigate to the target/site/jacoco/ directory.

Open the index.html file in your browser to view the detailed coverage report.

---

Maven, Docker and Kubernetes Running Process

Maven Run

To build and run the application with Maven, please follow the directions shown below;

$ git clone https://github.com/Rapter1990/geospatial-location-with-redis.git
$ cd geospatial-location-with-redis
$ docker-compose -f docker-compose-local.yml up -d
$ mvn clean install
$ mvn spring-boot:run

---

Docker Run

The application can be built and run by the Docker engine. The Dockerfile has multistage build, so you do not need to build and run separately.

Please follow directions shown below in order to build and run the application with Docker Compose file;

$ cd geospatial-location-with-redis
$ docker-compose -f docker-compose.yml up -d 

If you change anything in the project and run it on Docker, you can also use this command shown below

$ cd geospatial-location-with-redis
$ docker-compose -f docker-compose.yml up -d  --build

---

Check Values in Redis running on Docker

$ docker exec -it redis redis-cli
$ KEYS *
$ ZRANGE vehicle_location 0 -1
$ KEYS *

---

Kubernetes Run

To run the application, please follow the directions shown below;

• Start Minikube

$ minikube start

• Open Minikube Dashboard

$ minikube dashboard

• To deploy the application on Kubernetes, apply the Kubernetes configuration file underneath k8s folder

$ kubectl apply -f k8s

• To learn url to be used for App through Minikube

minikube service geospatial-location-with-redis --url

It will print something like:

http://127.0.0.1:xxxxx

Then call:

http://127.0.0.1:xxxxx/api/vehicles/nearest/point

---

Docker Image Location

https://hub.docker.com/repository/docker/noyandocker/geospatial-location-with-redis/general

---

📸 Screenshots

Click here to show the screenshots of project

Figure 1

Figure 2

Figure 3

Figure 4

---

Contributors

• Sercan Noyan Germiyanoğlu