geoip-py 1.0.2

Self-hosted IP geolocation library and API with currency support that works completely offline!

GeoIP API

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

- Deploy your own private GeoIP service with complete control over your data and infrastructure -
^{_{Powered by MaxMind's GeoLite2 databases ツ}}

✨ 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
   

2. Build the Docker image

   docker build -t geoip-api .
   

3. Run the container

   docker run -p 8000:8000 geoip-api
   

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
   

2. Install dependencies

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

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
   

4. Run the FastAPI application

   uvicorn api.main:app --reload
   

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: [e-mail]
• GitHub: @Malith-Rukshan

🧑‍💻 Built with 💖 by Malith Rukshan