GeoIP API

✨ A self-hosted REST API for IP geolocation that works completely offline! 🚀

🚀 Live Demo: https://geoip-api.malith.dev/

✨ Features

• 🌍 Fast and reliable IP geolocation lookups via a REST API
• 🔒 Self-hosted solution with no external API dependencies
• 🐳 Easy deployment with Docker and cloud platforms
• 📊 Get country, city, coordinates, timezone, ISP, and ASN data
• 🎨 Beautiful, interactive demo UI for testing available at the root endpoint
• 🚀 Built with FastAPI for high performance
• 📦 Automatic GeoLite2 database downloads and updates

🛠️ Usage

The GeoIP API provides simple endpoints to perform IP lookups.

REST API Endpoints

# Simple path parameter

[https://your-domain.com/8.8.8.8](https://your-domain.com/8.8.8.8)

# Query parameter

[https://your-domain.com/?ip=8.8.8.8](https://your-domain.com/?ip=8.8.8.8)

Standard API Endpoint

[https://your-domain.com/api/v1/geoip/lookup/8.8.8.8](https://your-domain.com/api/v1/geoip/lookup/8.8.8.8)

Response Format

{
  "ip": "8.8.8.8",
  "code": "US",
  "country": "United States",
  "city": "Mountain View",
  "lat": 37.4056,
  "lon": -122.0775,
  "tz": "America/Los_Angeles",
  "isp": "Google LLC",
  "asn": 15169
}

📦 Deployment Options

🚀 Cloud Deployment

One-click deployment to popular platforms, ideal for quickly getting your own instance running:

🌐 Use Cases

• Security & Compliance: Enhance security systems with IP-based threat detection while maintaining data sovereignty
• Content Localization: Deliver region-specific content based on visitor location without sharing user data
• Analytics: Analyze traffic patterns and user demographics with geographic data that remains within your infrastructure
• Fraud Prevention: Identify suspicious login attempts based on geographic anomalies
• Development Environment: Use a local GeoIP service in your development environment without external API dependencies

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Database License Notice

This project uses GeoLite2 data created by MaxMind, available from https://www.maxmind.com. The GeoLite2 databases are licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.

🔧 Acknowledgements

• GeoLite2 databases provided by MaxMind
• Mirror of GeoLite2 databases maintained by P3TERX
• Built with FastAPI and Python
• Powered by geoip2 library

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🌟 Support and Community

If you found this project helpful, please give it a ⭐ on GitHub. This helps more developers discover the project! 🫶

📬 Contact

If you have any questions, feedback, or just want to say hi, you can reach out to me:

• Email: [email protected]
• GitHub: @Malith-Rukshan

🧑‍💻 Built with 💖 by Malith Rukshan