A backend API for a game where you need to find a randomly chosen capital city. You input guesses of capital cities and the system tells you how far you are from the correct one — using distances and beautiful gradient lines.
- Start a game — a random capital city is secretly chosen.
- Guess a capital — type any capital city name.
- System responds with:
- Distance in kilometers between your guess and the target.
- A colorful CSS gradient line representing closeness.
- Try again — you keep guessing until you find the correct capital.
- Game ends once the correct city is guessed.
Each attempt is visualized with coordinates and gradients. The closer your guess, the more intense the red in the gradient.
This project was inspired by the amazing game Globle Capitals.
All code, logic, and architecture presented here are entirely self-written. The game mechanics were built from scratch, inspired only by the core idea. No code or assets were reused or copied from the original website.
All rights to the original Globle Capitals game belong to Trainwreck Labs. This is a developer-made homage, not a commercial clone.
- Autocomplete for cities via Elasticsearch
- Real-time distance calculations (Haversine formula)
- Stylish visual feedback via CSS gradients
- Persistent game sessions stored in PostgreSQL
- Redis caching for fast lookup and TTL-based game expiration
- Clean Architecture with DDD principles
- Fully documented OpenAPI spec via ReDoc
- Go (Golang) — backend API
- Gin — HTTP web framework
- GORM — ORM for PostgreSQL
- Redis — for fast cache and session TTL
- PostgreSQL — for persistent game sessions
- Elasticsearch — full-text search for cities
- Docker & Docker Compose — containerized development
- Makefile — for devtools and automation
- OpenAPI + ReDoc — API documentation
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/autocomplete?q= |
Autocomplete capital city names |
| POST | /v1/game/start |
Start a new game session |
| POST | /v1/game/guess |
Make a guess for a capital city |
| GET | /v1/game/list |
List all games played by user (by IP) |
| GET | /v1/game/info/{uuid} |
Get info about a specific game |
Postman collection: Find Capitals API.postman_collection.json
# Clone the repo
git clone https://github.com/m1n64/find-capital-apicd find-capital-api# Copy environment variables
cp .env.example .env# Start environment
make up# Seed database
make seedGo to http://localhost:8000/docs
| Command | Description |
|---|---|
make up |
Start the DEV environment |
make prod |
Start the PROD environment |
make stop |
Stop all containers |
make down |
Remove all containers and volumes |
make restart |
Restart all containers |
make restart-container CONTAINER=name |
Restart a specific container |
make stop-container CONTAINER=name |
Stop a specific container |
make bash |
Open a bash shell inside the app container |
make logs name |
View logs of a specific container |
make app-logs |
View last logs from the app container |
make psql |
Open psql shell with credentials from .env |
make redis |
Open redis-cli inside the Redis container |
make seed |
Run seeders to populate countries & cities |
ReDoc is available at: 👉 http://localhost:8000/docs
Raw OpenAPI JSON: 👉 http://localhost:8000/docs/openapi.json
API host: 👉 http://localhost:8000/v1
Made with ❤️ by the Kirill Sakharov (LinkedIn)