Bitip is a professional GeoIP lookup service that provides IP geolocation data through a REST API and user-friendly web interface. Built with Express.js, TypeScript, React, and MaxMind GeoLite2 databases.

✨ Features

🔍 IP Geolocation Lookup: Get detailed location information for any public IP address
🌐 Web Interface: Clean, professional web UI with interactive maps
📡 REST API: Comprehensive API for single and batch IP lookups
🗺️ Interactive Maps: Static preview and interactive map popups using OpenStreetMap/Leaflet
🔐 API Key Authentication: Secure access with configurable rate limiting
⚡ Performance: In-memory caching and efficient database access
📊 Structured Logging: Optional integration with Seq for advanced logging
🐳 Docker Ready: Production deployment with Docker and geoipupdate integration
🔧 Configurable: Runtime configuration via environment variables

🚀 Quick Start

Local Development (No Docker Required)

Prerequisites

Node.js >= 18.0.0
npm >= 9.0.0
MaxMind GeoLite2 databases (download from https://www.maxmind.com/en/geolite2/signup or use geoipupdate)

1. Clone and Setup

git clone <repository-url>
cd Bitip

2. Install Dependencies

npm run install:all

3. Configure Environment

Create a .env file in the root directory:

# API Keys (change these for production!)
FRONTEND_API_KEY=frontend-dev-key
EXTERNAL_API_KEYS=external-dev-key-1,external-dev-key-2

# Server Configuration
PORT=3000
BASE_PATH=/
NODE_ENV=development

# Database Path - Point to your MaxMind databases location
MAXMIND_DB_PATH=D:\tools\maxmind-dbs  # Windows
# MAXMIND_DB_PATH=/usr/share/GeoIP   # Linux/Mac

# Rate Limiting Configuration
FRONTEND_RATE_WINDOW_MS=60000
FRONTEND_RATE_MAX=30
EXTERNAL_RATE_WINDOW_MS=60000
EXTERNAL_RATE_MAX=1000

# Batch Configuration
BATCH_LIMIT=100
DEBOUNCE_MS=2000

# Seq Logging (Optional)
# SEQ_URL=http://localhost:5341
# SEQ_API_KEY=your-seq-api-key

4. Start Development Servers

npm run dev

This will start:

Backend API server on http://localhost:3000
Frontend dev server on http://localhost:5173 (or next available port)
Frontend proxies API requests to backend

5. Access the Application

Web Interface: http://localhost:5173 (or the port shown in console)
API Endpoint: http://localhost:3000/api
Health Check: http://localhost:3000/api/health

Production Deployment (Docker)

Prerequisites

Docker and Docker Compose
MaxMind GeoLite2 account (free): https://www.maxmind.com/en/geolite2/signup

1. Configure Environment

Edit .env file with your MaxMind credentials:

GEOIPUPDATE_ACCOUNT_ID=your_account_id_here
GEOIPUPDATE_LICENSE_KEY=your_license_key_here
FRONTEND_API_KEY=your-secure-frontend-api-key-here
EXTERNAL_API_KEYS=your-secure-external-api-key-1,your-secure-external-api-key-2

2. Start Services

docker-compose up -d

3. Access the Service

Web Interface: http://localhost:3000
API Endpoint: http://localhost:3000/api
Health Check: http://localhost:3000/api/health

📖 API Documentation

Authentication

All API requests require an API key sent via header or query parameter:

# Via Header (recommended)
curl -H "X-API-Key: your-api-key" http://localhost:3000/api/lookup?ip=8.8.8.8

# Via Query Parameter
curl "http://localhost:3000/api/lookup?ip=8.8.8.8&apikey=your-api-key"

Endpoints

Get Current IP

GET /api/ip

Returns the client's current IP address.

Response:

{
  "ip": "203.0.113.42"
}

Simple IP Lookup

GET /api/lookup?ip=8.8.8.8

Returns basic location information:

{
  "ip": "8.8.8.8",
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "city": "Mountain View",
  "latitude": 37.4056,
  "longitude": -122.0775,
  "timezone": "America/Los_Angeles",
  "postal_code": "94043"
}

Detailed IP Lookup

GET /api/lookup/detailed?ip=8.8.8.8

Returns comprehensive MaxMind database information including all available fields.

Batch IP Lookup

POST /api/lookup/batch
Content-Type: application/json

{
  "ips": ["8.8.8.8", "1.1.1.1", "208.67.222.222"]
}

Response:

{
  "results": [
    {
      "ip": "8.8.8.8",
      "country": "United States",
      ...
    },
    {
      "ip": "1.1.1.1",
      "country": "Australia",
      ...
    }
  ]
}

Health Check

GET /api/health

Returns service health status including database connectivity.

Error Handling

The API returns appropriate HTTP status codes:

400 - Bad Request (invalid IP, private IP, validation errors)
401 - Unauthorized (missing or invalid API key)
404 - Not Found (IP not in database)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error
503 - Service Unavailable (database maintenance)

🛠️ Development

Project Structure

Bitip/
├── src/
│   ├── backend/              # Express.js API server
│   │   ├── routes/           # API route handlers
│   │   ├── services/         # Business logic (GeoIP, config, logger)
│   │   ├── middleware/       # Express middleware (auth, rate limiting)
│   │   ├── types/            # TypeScript type definitions
│   │   ├── index.ts          # Main server entry point
│   │   ├── nodemon.json      # Nodemon configuration
│   │   ├── tsconfig.json     # TypeScript configuration
│   │   └── package.json      # Backend dependencies
│   └── frontend/             # React web application
│       ├── src/
│       │   ├── components/   # React components (MapComponent)
│       │   ├── services/     # API client services
│       │   ├── types/        # TypeScript types
│       │   ├── App.tsx       # Main App component
│       │   ├── App.css       # Application styles
│       │   └── main.tsx      # React entry point
│       ├── index.html        # HTML template
│       ├── vite.config.ts    # Vite configuration
│       ├── tsconfig.json     # TypeScript configuration
│       └── package.json      # Frontend dependencies
├── docs/                     # Documentation (PRD, tech stack)
├── .env                      # Environment variables (not in git)
├── .env.example              # Example environment file
├── Dockerfile                # Production Docker image
├── docker-compose.yml        # Production deployment
└── package.json              # Root package configuration

Available Scripts

# Development
npm run dev              # Start both frontend and backend in dev mode
npm run dev:backend      # Start backend development server only
npm run dev:frontend     # Start frontend development server only

# Building
npm run build            # Build both frontend and backend for production
npm run build:backend    # Build backend only
npm run build:frontend   # Build frontend only

# Production
npm start                # Start production backend server (after build)

# Code Quality
npm run lint             # Lint both frontend and backend
npm run lint:fix         # Fix linting issues
npm run format           # Format code with Prettier

# Utilities
npm run clean            # Clean build artifacts
npm run install:all      # Install all dependencies (root + backend + frontend)

Technology Stack

Backend:

Express.js 4.x with TypeScript
@maxmind/geoip2-node 5.x - GeoIP database reader
node-cache - In-memory caching
express-rate-limit - Rate limiting
helmet - Security headers
joi - Request validation
seq-logging - Optional structured logging

Frontend:

React 18.x with TypeScript
Vite 4.x - Build tool and dev server
Leaflet & react-leaflet - Interactive maps
Axios - HTTP client
OpenStreetMap - Map tiles

Development Tools:

TypeScript 5.x
ESLint & Prettier
nodemon - Auto-restart on changes
ts-node - TypeScript execution

⚙️ Configuration

Environment Variables

Variable	Default	Description
`PORT`	`3000`	Server port
`BASE_PATH`	`/`	Application base path
`NODE_ENV`	`development`	Environment mode (development/production)
`MAXMIND_DB_PATH`	`/usr/share/GeoIP`	MaxMind database directory
`FRONTEND_API_KEY`	`frontend-default-key`	Frontend API key
`EXTERNAL_API_KEYS`	`external-default-key`	External API keys (comma-separated)
`FRONTEND_RATE_WINDOW_MS`	`60000`	Frontend rate limit window (milliseconds)
`FRONTEND_RATE_MAX`	`30`	Frontend rate limit max requests
`EXTERNAL_RATE_WINDOW_MS`	`60000`	External rate limit window (milliseconds)
`EXTERNAL_RATE_MAX`	`1000`	External rate limit max requests
`BATCH_LIMIT`	`100`	Maximum IPs per batch request
`DEBOUNCE_MS`	`2000`	Frontend input debounce delay (milliseconds)
`SEQ_URL`	-	Seq logging server URL (optional)
`SEQ_API_KEY`	-	Seq API key (optional)

MaxMind Database Setup

The service requires MaxMind GeoLite2-City database. You have two options:

Option 1: Manual Download

Sign up at https://www.maxmind.com/en/geolite2/signup
Download GeoLite2-City database (.mmdb file)
Place it in a directory (e.g., D:\tools\maxmind-dbs on Windows)
Set MAXMIND_DB_PATH environment variable to that directory

Option 2: Using geoipupdate (Production)

Use the provided docker-compose.yml which includes geoipupdate service
geoipupdate automatically downloads and updates databases
Both services share a Docker volume for database access

Rate Limiting

Bitip implements different rate limiting for frontend and external API consumers:

Frontend: More restrictive limits for web UI usage (default: 100 req/min)
External: Higher limits for programmatic API access (default: 1000 req/min)

Rate limits are fully configurable via environment variables and include standard HTTP headers in responses.

🐳 Docker Deployment

Production Setup

The service is designed to run alongside MaxMind's geoipupdate service:

# Start both services
docker-compose up -d

# View logs
docker-compose logs -f bitip

# Stop services
docker-compose down

The docker-compose.yml includes:

geoipupdate: Downloads and updates MaxMind databases
bitip: Main application server (API + Web UI)
Shared volume: For database access between services

Health Monitoring

The service includes comprehensive health checks:

Docker health check endpoint: /api/health
Database connectivity verification
Service status monitoring

🔧 Troubleshooting

Common Issues

1. Database Not Found

Ensure databases are downloaded to the path specified in MAXMIND_DB_PATH
Check that GeoLite2-City.mmdb file exists in that directory
Verify file permissions (read access required)

2. TypeScript Errors

Run npm run install:all to ensure all dependencies are installed
Check that Node.js version is >= 18.0.0
Try deleting node_modules and reinstalling

3. API Authentication Errors

Verify API key in .env file matches the one you're using
Check X-API-Key header or apikey query parameter format
Ensure API key doesn't contain extra spaces

4. Rate Limiting

Check rate limit headers in API responses (X-RateLimit-*)
Adjust rate limiting configuration if needed
Use external API keys for higher limits

5. Map Display Issues

Verify internet connectivity for OpenStreetMap tiles
Check browser console for JavaScript errors
Ensure Leaflet CSS is loading correctly

6. Port Already in Use

Frontend dev server will auto-increment port (5173, 5174, etc.)
Backend port can be changed via PORT environment variable
Check for other services using the same ports

Logs and Debugging

Application logs are printed to console
Use npm run dev for detailed development logs
Configure Seq integration for structured logging
Docker logs: docker-compose logs -f bitip

📦 Package Versions

Current versions (as of project creation):

Major packages are on stable versions but not latest
Consider updating for newer features and security fixes
Check npm outdated for available updates
Test thoroughly after major version updates

Key outdated packages:

Express 4.x (5.x available but still beta)
React 18.x (19.x available)
Vite 4.x (7.x available - major update)
Many dev dependencies have newer versions

📄 License

This software is proprietary and confidential. Unauthorized use, copying, modification, distribution, or reverse engineering of this software, in whole or in part, is strictly prohibited without explicit written permission from the copyright holder.

License Summary

✅ Evaluation Period: 30-day trial for evaluation purposes
✅ Approved Use: Requires explicit written approval from Tudor Stanciu
❌ No Redistribution: Cannot be distributed, sublicensed, or transferred to third parties
❌ No Modification: Cannot be modified or create derivative works without permission
❌ No Commercial Use: Cannot be used for commercial services without separate license

Obtaining a License

For licensing inquiries, commercial use, or approval requests:

Contact: Tudor Stanciu Email: tudor.stanciu94@gmail.com

Please include:

Intended use case
Organization name and size
Expected deployment scale
Duration of use

See LICENSE file for complete terms and conditions.

🙏 Acknowledgments

MaxMind for providing GeoLite2 databases
OpenStreetMap for map tiles
Leaflet for interactive mapping
All open-source contributors

Bitip - Professional GeoIP Lookup Service 🌍 Built with ❤️ using Express.js, React, and MaxMind GeoLite2

Languages

TypeScript 58.2%

C# 30.7%

CSS 7.1%

JavaScript 2.1%

Dockerfile 1.5%

Other 0.4%