Unified, free geolocation service built with Java 17 + Spring Boot + Clean Architecture.
GeoLocateAPI provides a simple, reliable and fully free way to obtain geolocation data without relying on commercial APIs or paid subscriptions.
It exposes a clean REST interface for three essential operations:
- IP → Location
- Coordinates → City/Country
- City Name → Coordinates
The service acts as a unified layer over public, open-data providers (ip-api, OpenStreetMap/Nominatim, Open-Meteo), avoiding the friction of API keys, quotas and billing constraints.
The project is intentionally stateless, lightweight and easy to integrate, suitable for backend systems, mobile apps, internal tooling, analytics or prototyping.
- IP → Location lookup
- Coordinates → Reverse geocoding
- City → Coordinates search
- Unified
GeoLocationDatadomain model - Clean Architecture
- Hexagonal provider integration
- Global exception handling
- WireMock integration tests
- MockMvc controller tests
- Auto-generated Swagger/OpenAPI documentation
GET /api/v1/geo/ip/{ip}
Example:
curl http://localhost:8080/api/v1/geo/ip/8.8.8.8
GET /api/v1/geo/coordinates?lat=40.0&lon=-8.0
Example:
curl http://localhost:8080/api/v1/geo/coordinates?lat=40.0&lon=-8.0
GET /api/v1/geo/city/{name}
Example:
curl http://localhost:8080/api/v1/geo/city/Lisbon
src/
├─ domain/
├─ application/
├─ infrastructure/
└─ presentation/
Rendered SVG: architecture.svg
Source (PlantUML): architecture.puml
git clone https://github.com/your-user/GeoLocateAPI.git
cd GeoLocateAPI
./gradlew bootRun
Once the app is running:
- Swagger UI:
http://localhost:8080/swagger-ui/index.html - OpenAPI JSON:
/v3/api-docs
./gradlew test
- Provider fallback
- Rate limiting
- API key authentication
- CI pipeline + coverage badge
- Dockerfile (optional)
GeoLocateAPI follows a simple and clean release flow:
- main → stable, production-ready versions
- develop → upcoming improvements and planned features
v1.0.0 — Initial Stable Release
Includes:
- Core geolocation features (IP lookup, reverse geocoding, city search)
- Clean Architecture + Hexagonal structure
- Swagger/OpenAPI documentation
- WireMock + MockMvc test suite
- Architecture diagrams (PlantUML + SVG)
- MIT License
👉 View all releases:
https://github.com/your-user/GeoLocateAPI/releases
The core of GeoLocateAPI is complete. Contributions are welcome.
This service was originally built as part of my backend engineering portfolio, focusing on clean architecture, external API integration, structured testing and maintainability.
Developed by Marco Domingues. Focused on clean, testable backend services that are easy to understand, extend and deploy.
This project is distributed under the MIT License.
See the LICENSE file for details.