geospatial-location-with-redis

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

geospatial-location-with-redis

★ 10 Open GitHub ↗

Case Study - Geospatial Location with Redis in Spring Boot (Java 25, Spring Boot, Redis, JUnit, Docker, Kubernetes, Github Action (CI/CD), TestContainer)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## 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

-----

### 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;

```sh
$ 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;

```sh
$ 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

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

### Check Values in Redis running on Docker

```sh
$ 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

```sh
$ minikube start
```

- Open Minikube Dashboard

```sh
$ minikube dashboard
```

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

```sh
$ kubectl apply -f k8s
```

- To learn url to be used for App through Minikube
```sh
minikube service geospatial-location-with-redis --url
```

It will print something like:

```sh
http://127.0.0.1:xxxxx
```

Then call:
```sh
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

<details>
<summary>Click here to show the screenshots of project</summary>
 Figure 1 
 <img src ="screenshots/1.PNG">
 Figure 2 
 <img src ="screenshots/2.PNG">
 Figure 3 
 <img src ="screenshots/3.PNG">
 Figure 4 
 <img src ="screenshots/4.PNG">
</details>

-----

### Contributors

- [Sercan Noyan Germiyanoğlu](https://github.com/Rapter1990)

geospatial-location-with-redis

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README