malithrukshan/geoip-api repository overview

⁠GeoIP API

⁠✨ A self-hosted IP geolocation API and Python package that works completely offline! 🚀

⁠✨ Features

• 🌍 Fast and reliable IP geolocation lookups
• 🔒 Self-hosted solution with no external API dependencies
• 🛠️ Dual functionality: Python package and REST API
• 🐳 Easy deployment with Docker and cloud platforms
• 📊 Get country, city, coordinates, timezone, ISP, and ASN data
• 🎨 Beautiful, interactive demo UI for testing
• 🚀 Built with FastAPI for high performance
• 📦 Automatic GeoLite2 database downloads and updates

⁠🛠️ Usage

⁠Python Package

⁠Installation

pip install geoip-py

⁠Basic Usage

from geoip_api import GeoIPLookup

# Initialize the lookup service (downloads DB files if needed)
lookup = GeoIPLookup(download_if_missing=True)

# Look up an IP address
result = lookup.lookup('8.8.8.8')
print(result)

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

⁠REST API

✅ Demo : https://geoip-api.malith.dev/⁠

⁠Simple Endpoints

# Simple path parameter
https://your-domain.com/8.8.8.8

# Query parameter
https://your-domain.com/?ip=8.8.8.8

⁠Standard API Endpoint

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:

⁠🐳 Docker

The fastest way to deploy your own GeoIP API:

docker pull malithrukshan/geoip-api
docker run -p 8000:8000 malithrukshan/geoip-api

Your API will be available at http://localhost:8000⁠

⁠Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  geoip-api:
    image: malithrukshan/geoip-api
    ports:
      - "8000:8000"
    # volumes:
    #   - ./data:/app/api/db
    environment:
      - ENVIRONMENT=production

Then run:

docker-compose up -d

⁠🔨 Building Docker Image Locally

If you want to build and run the Docker image from source:

1. Clone the repository

   git clone https://github.com/Malith-Rukshan/geoip-api.git
   cd geoip-api
   

   Copy
2. Build the Docker image

   docker build -t geoip-api .
   

   Copy
3. Run the container

   docker run -p 8000:8000 geoip-api
   

   Copy
4. Access the API at http://localhost:8000⁠

⁠💻 Local Development

⁠Prerequisites

• Python 3.9+
• pip

⁠Setup

1. Clone the repository

   git clone https://github.com/Malith-Rukshan/geoip-api.git
   cd geoip-api
   

   Copy

2. Install dependencies

   pip install -r requirements/dev.txt
   pip install -e .
   

   Copy

3. Download GeoIP databases (optional, will be downloaded automatically if needed)

   mkdir -p ~/.geoip_api
   curl -L -o ~/.geoip_api/GeoLite2-City.mmdb https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-City.mmdb
   curl -L -o ~/.geoip_api/GeoLite2-ASN.mmdb https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-ASN.mmdb
   

   Copy

4. Run the FastAPI application

   uvicorn api.main:app --reload
   

   Copy

5. Visit http://localhost:8000⁠ to see the API in action

⁠Running Tests

pytest
black --check src tests api
mypy src tests api

⁠🌐 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

⁠🇺🇳 Flags By : Animated Country Flags⁠

⁠🤝 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⁠