ip-info/README.md

IP Info Service

A high-performance IP geolocation service built with Go that provides detailed information about IP addresses including country, ASN (Autonomous System Number), and other geolocation data.

Features

• 🌍 IP geolocation lookup with country information
• 🏢 ASN (Autonomous System Number) information
• 🚀 High-performance HTTP API
• 🔄 Automatic database updates
• 🐳 Docker support
• 📊 Metrics endpoint for monitoring
• 🛡️ Input validation and error handling

Quick Start

Using Docker (Recommended)

1. Clone the repository:

git clone <repository-url>
cd ip-info

2. Start the service using Docker Compose:

docker-compose up -d

The service will be available at http://localhost:28080

Manual Installation

1. Install Go 1.22 or later
2. Clone and build:

git clone <repository-url>
cd ip-info
go mod download
go build -o ip-info
./ip-info

API Endpoints

1. Get Your IP Information

Plain Text Response:

curl http://localhost:28080/
# Returns: 192.168.1.100

JSON Response:

curl http://localhost:28080/json

Response:

{
  "ip": "192.168.1.100",
  "country": "US",
  "country_name": "United States",
  "asn": "AS15169",
  "asn_org": "Google LLC"
}

2. Look Up Specific IP Address

Query any IP address:

curl http://localhost:28080/8.8.8.8

Response:

{
  "ip": "8.8.8.8",
  "country": "US",
  "country_name": "United States",
  "asn": "AS15169",
  "asn_org": "Google LLC"
}

3. Metrics Endpoint

Monitor service health and performance:

curl http://localhost:28080/metrics

Configuration

Environment Variables

Variable	Default	Description
API_PORT	8080	Port for the HTTP server
GIN_TRUSTED_PROXY_IP	-	Trusted proxy IP for client IP detection
GIN_MODE	debug	Gin framework mode (debug, release)

Using .env File

Create a .env file in the project root:

API_PORT=8080
GIN_TRUSTED_PROXY_IP=127.0.0.1
GIN_MODE=release

Docker Configuration

Docker Compose

The included docker-compose.yml provides:

• Service on port 28080 (maps to container port 8080)
• Persistent cache volume
• Auto-restart policy
• Vietnam timezone configuration

Custom Docker Build

# Build image
docker build -t ip-info .

# Run container
docker run -p 8080:8080 -v $(pwd)/.cache:/app/.cache ip-info

Data Sources

The service automatically downloads and updates IP geolocation databases from:

• Country Data: GeoLite2 Country database via jsDelivr CDN
• ASN Data: GeoLite2 ASN database via jsDelivr CDN

Database updates happen automatically in the background to ensure data freshness.

Usage Examples

Basic IP Lookup

# Get information about Google's DNS
curl http://localhost:28080/8.8.8.8

# Get information about Cloudflare's DNS
curl http://localhost:28080/1.1.1.1

# Get your own IP info
curl http://localhost:28080/json

Integration Examples

JavaScript/Node.js:

const response = await fetch('http://localhost:28080/8.8.8.8');
const ipInfo = await response.json();
console.log(ipInfo);

Python:

import requests

response = requests.get('http://localhost:28080/8.8.8.8')
ip_info = response.json()
print(ip_info)

cURL with jq:

curl -s http://localhost:28080/8.8.8.8 | jq .

Response Format

All JSON responses include:

• ip: The queried IP address
• country: ISO 3166-1 alpha-2 country code
• country_name: Full country name
• asn: Autonomous System Number (when available)
• asn_org: ASN organization name (when available)

Error Handling

Invalid IP Address

curl http://localhost:28080/invalid-ip

Response:

{
  "error": "invalid ip"
}

Service Unavailable

If the database is not loaded yet:

HTTP 500: Try again later

Performance

• Startup Time: Database loads automatically on startup
• Response Time: Sub-millisecond IP lookups after database load
• Memory Usage: Optimized MMDB format for efficient memory usage
• Concurrency: Built with Go's excellent concurrency support

Monitoring

Health Check

curl http://localhost:28080/metrics

Logs

The service provides structured JSON logging with different log levels. In Docker:

docker-compose logs -f ip-info

Development

Local Development

# Install dependencies
go mod download

# Run in development mode
go run main.go

# Build for production
go build -o ip-info

Project Structure

├── main.go                 # Application entry point
├── configs/               # Configuration files
├── internal/
│   ├── data/             # Database handling
│   └── services/
│       ├── api/          # HTTP API handlers
│       └── db_updater/   # Database update service
├── pkg/                  # Shared packages
├── data/                 # Database files (auto-generated)
└── docker-compose.yml    # Docker configuration

License

[Add your license information here]

Contributing

[Add contribution guidelines here]

Support

For issues and questions, please open an issue or contact the maintainers.