Geo IP Generator

A professional geolocation IP address generation service built with T3 Stack, supporting real IP address generation for 250+ countries and territories worldwide.

🌍 中文文档 | English

✨ Features

🎲 Random IP Generation: Generate real IP addresses by country code or name
📊 Batch Generation: Support generating 1-10 IP addresses at once
🌍 Global Coverage: Support 250+ countries and territories (including sovereign states and territories)
🏛️ Territory Classification: Clear distinction between sovereign countries and territories (e.g., Hong Kong, Taiwan, Macao)
📋 One-Click Copy: Support single or batch copying of generated IP addresses
📍 Detailed Information: Display IP geolocation, ISP, and other detailed information
🔍 Data Validation: Automated quality assurance with multi-API cross-validation
🚀 Modern Tech Stack: Next.js + TypeScript + Prisma + Tailwind CSS
📱 Responsive Design: Support for desktop and mobile devices
🔗 API Support: Provide RESTful API interface for external integration

🛠️ Tech Stack

Frontend: Next.js 15 with App Router
Backend: Next.js API Routes with type-safe validation
Database: Prisma ORM with SQLite
Styling: Tailwind CSS
Type Safety: TypeScript
Development Tools: Biome for linting and formatting
Automation: GitHub Actions for data sync and validation

🚀 Quick Start

Prerequisites

Node.js 18+
pnpm
Git (for automated data synchronization)

1. Clone and Install

git clone <repository-url>
cd geo-ip-generator
pnpm install

2. Environment Setup

Create environment variables file:

cp .env.example .env

Edit the .env file and set the database path:

DATABASE_URL="file:./db.sqlite"
REDIS_URL="redis://localhost:6379"  # Optional, for caching acceleration

3. Data Source & Environment 🚀

We recommend running from the prebuilt combined dataset (JSON) and importing it at service start.

# Database
DATABASE_URL="file:./prisma/db.sqlite"

# Dataset (http/https, absolute/relative path, or file://)
# Default: GitHub raw URL of this repo's combined data
#GEO_DATA_URL=https://raw.githubusercontent.com/<your-org>/<repo>/main/data/combined-geo-ip-data.json
GEO_DATA_URL=./data/combined-geo-ip-data.json

Start commands:

pnpm run prestart   # prisma db push + import data from GEO_DATA_URL (clear & refill)
pnpm run dev        # or pnpm run start

🚀 Performance Optimization

Batch Insert: Using transactions and batch operations, improving import speed by 10-50x
SQLite Optimization: Enable WAL mode, optimize cache and sync settings
Progress Display: Real-time display of import progress and statistics

💡 Note: The initialization process takes about 3-5 minutes, most of the time is spent downloading data. The actual import speed has been significantly optimized!

4. Start Development Server

pnpm run dev

Visit http://localhost:3000

🔄 Data Management & Automation

🤖 Automated Synchronization (Recommended)

The project is configured with GitHub Actions automated data synchronization:

# Manually trigger complete data sync (includes backup/update/multi-format export)
pnpm run data:sync

# Individual format exports
pnpm run data:export:csv
pnpm run data:export:excel

# Data quality validation
pnpm run data:validate          # Full validation (100 samples)
pnpm run data:validate:sample   # Quick validation (50 samples)

Automation Features:

✅ Daily automatic run at UTC 02:00 (Beijing time 10:00)
✅ Automatic backup of current data, rollback on failure
✅ Smart detection of data changes, skip commit when no changes
✅ Automatic generation of multiple formats: JSON, CSV, Excel
✅ Automatic creation of GitHub Release and download links
✅ Retain 7-day backup history
✅ Integrated data quality validation (50 sample quick detection)

Manual Trigger Synchronization:

Visit the project's GitHub Actions page
Select "Daily Data Sync" workflow
Click "Run workflow" button
Optionally choose force update (even if no data changes)

📋 Manual Data Updates (dev/CI only)

# Re-fetch latest territory data
pnpm run data:import:territories

# Re-download latest IP data
pnpm run data:import:ip2location

# Generate combined JSON
pnpm run data:export:combined

💡 Tip: Automated synchronization has configured optimal update strategies, usually no manual operation is required.

💻 Usage Guide

Web Interface

IP Generation: Enter country code or name in the input box:
- Country codes: CN, US, JP, HK, TW, MO
- Chinese names: 中国, 美国, 日本, 香港, 台湾, 澳门
- English names: China, America, Japan, Hong Kong, Taiwan, Macao
Batch Generation: Select generation count (1-10)
One-Click Copy: Support single or batch copying of generated IP addresses
Data Download: Visit /download page to get complete datasets
Quality Monitoring: Visit /validation page to view data quality reports

Data Download Center

Dedicated data download page providing multiple formats:

📄 JSON Format: Complete and minified versions, suitable for APIs and programmatic access
📋 CSV Format: Complete and light versions, suitable for Excel analysis and database import
📊 Excel Format: Multi-worksheet version, including statistical analysis and data visualization
📈 Real-time Statistics: Display latest data volume, update time, and other information

Data Quality Monitoring

Dedicated data validation page providing:

🔍 Automatic Validation: Weekly automatic runs to verify IP geolocation data accuracy
📊 Quality Reports: Accuracy statistics, confidence analysis, third-party API comparison
⚠️ Anomaly Detection: Automatically create GitHub Issues when accuracy drops below 85%
📚 Historical Records: Save validation history for trend analysis
🔄 Cross-validation: Use multiple third-party APIs for cross-validation, avoiding single points of failure

API Integration

Generate Random IP Addresses (GET-only)

API Endpoint: /api/generate-ip

# Generate 1 China IP
GET /api/generate-ip?country=CN

# Generate 3 US IPs
GET /api/generate-ip?country=US&count=3

# Using Chinese names
GET /api/generate-ip?country=中国&count=2

Response Format:

{
  "success": true,
  "data": {
    "country": {
      "id": "CHN",
      "code2": "CN",
      "nameEn": "China",
      "nameZh": "中国",
      "continent": "Asia",
      "region": "Eastern Asia"
    },
    "ips": [{
      "ip": "1.2.3.4",
      "location": { "region": "Beijing", "city": "Beijing", "isp": "China Telecom" },
      "ipRange": { "startIp": "1.2.0.0", "endIp": "1.2.255.255" }
    }],
    "totalRanges": 1250,
    "cached": false
  }
}

🎯 Use Cases

Development & Testing

Network Proxy Testing: Generate test IPs from different regions
Geolocation Services: Simulate user origins
CDN Distribution Testing: Test content delivery networks

Data Analysis

User Behavior Simulation: Simulate user access from different regions
A/B Testing: Geographic location-related feature testing
Load Testing: Simulate global user load

Security Testing

Firewall Rule Testing: Test regional access restrictions
IP Whitelist Testing: Verify access control
Geofencing Testing: Test regional restriction features

📊 Project Status

Latest Updates (v2.1)

✅ Automated Synchronization: GitHub Actions daily automatic data synchronization
✅ Backup Mechanism: Automatic backup and failure rollback to ensure data security
✅ Multi-format Export: Added CSV and Excel format support
✅ Download Center: Dedicated data download page
✅ Quality Monitoring: Brand new data validation system and Web interface
✅ Smart Validation: Multi-third-party API cross-validation for data accuracy
✅ Anomaly Detection: Low accuracy automatic alerts and Issue creation
✅ Timestamp Management: Filenames include timestamps for easy version management
✅ Smart Detection: Only commit updates when data changes
✅ Release Automation: Automatic creation of GitHub Release and download links

Data Statistics

Supported Territories: 250+ countries and territories
Sovereign Countries: 195 (UN members + non-member sovereign countries)
Territories: 55+ (e.g., Hong Kong, Taiwan, Macao, Puerto Rico, etc.)
IP Ranges: 450,000+ records
Data Source: IP2Location LITE (free version)

📈 Performance Metrics

Query Performance

IP Query: < 50ms (after enabling indexes)
Territory Query: < 100ms
Random Generation: < 200ms

Storage Requirements

JSON Data: ~2-5MB (depending on IP range count)
CSV Data: ~3-8MB (tabular format)
Excel Data: ~1-3MB (multi-worksheet)
Complete Database: ~500MB (3 million IP records)
Backup Storage: ~50MB (7-day history retention)

Automation Performance

Sync Frequency: Daily
Data Detection: < 30 seconds
Backup Creation: < 2 minutes
Format Export: < 5 minutes
Data Validation: < 3 minutes (50 samples)
Failure Rollback: < 1 minute

Data Quality Metrics

Validation Frequency: Weekly (manually triggerable)
Sample Size: 100 IP addresses (standard) / 50 (quick)
Accuracy Target: ≥ 85% (alerts triggered below this threshold)
API Providers: 3 (rotating usage to avoid single point dependency)
Confidence Calculation: Multi-API consensus scoring

⚙️ Deployment Configuration

GitHub Actions Setup

The project includes automated data synchronization functionality, no additional Secrets configuration required, uses default GITHUB_TOKEN.

For custom configuration:

Scheduled Tasks: Modify cron expressions in .github/workflows/data-sync.yml
Data Sources: Configure different data source URLs in scripts
Backup Strategy: Adjust backup retention days and storage location

Local Development

# Import dataset & start
pnpm run prestart && pnpm run dev

# Test individual exports
pnpm run data:export:csv
pnpm run data:export:excel

# Check generated files
ls -la data/

# Test validation system (quick)
pnpm run data:validate:sample

🗃️ Database Structure

Core Table Structure

-- Territory information table (includes countries and territories)
Country {
  id: String         // Three-letter territory code (CHN, USA, HKG, TWN, MAC)
  code2: String      // Two-letter territory code (CN, US, HK, TW, MO)
  nameEn: String     // English name
  nameZh: String     // Chinese name
  continent: String  // Continent
  region: String     // Region
  independent: Boolean // Whether it's a sovereign country
  unMember: Boolean    // Whether it's a UN member
}

-- IP range information table
IpRange {
  startIp: String    // Start IP
  endIp: String      // End IP
  countryId: String  // Associated territory code
  isp: String        // ISP provider
}

🛡️ Political Stance

This project maintains political neutrality:

Strictly follows ISO 3166-1 international standards
Objectively reflects real-world administrative divisions
Does not express any political tendencies or positions
Serves technical purposes without involving political disputes

🤝 Contributing

Welcome to contribute code! Please refer to the following steps:

Fork the project
Create a feature branch
Test automated synchronization functionality
Submit changes (follow Conventional Commits)
Send Pull Request

📄 License

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

Data sources:

Territory data: mledoze/countries (ODbL License)
IP data: IP2Location LITE (CC BY-SA 4.0)

Name		Name	Last commit message	Last commit date
Latest commit History 169 Commits
.github		.github
data		data
docs		docs
prisma		prisma
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh_CN.md		README.zh_CN.md
biome.jsonc		biome.jsonc
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

License

Fog3211/geo-ip-generator

Folders and files

Latest commit

History

Repository files navigation