IP to Country Code - A fast, cross-platform CLI tool for looking up country and provider information for IP addresses.

• Fast offline lookups: Uses a local Patricia trie index for O(k) prefix matching
• IPv4 and IPv6 support: Full support for both IP versions
• Provider/ISP detection: Identifies the network operator via BGP/ASN or WHOIS
• Historical data: Query data for specific dates using --time flag
• Batch processing: Process thousands of IPs via stdin
• Cross-platform: Linux, macOS, Windows (amd64, arm64)
• Self-contained: Single binary with no runtime dependencies

curl -fsSL https://raw.githubusercontent.com/hightemp/ip2cc/main/scripts/install.sh | bash

iwr -useb https://raw.githubusercontent.com/hightemp/ip2cc/main/scripts/install.ps1 | iex

go install github.com/hightemp/ip2cc/cmd/ip2cc@latest

# Download the IP prefix database
ip2cc update

# Look up an IP address
ip2cc 8.8.8.8

# Basic lookup
ip2cc 8.8.8.8
# Output: 8.8.8.8	US	United States	8.8.8.0/24	GOOGLE LLC

# JSON output
ip2cc --json 8.8.8.8

# Offline mode (no provider lookup)
ip2cc --offline 8.8.8.8

# Use historical snapshot
ip2cc --time 2025-01-01 8.8.8.8

# From file
cat ips.txt | ip2cc

# From command
echo -e "8.8.8.8\n1.1.1.1" | ip2cc

# JSON array output
cat ips.txt | ip2cc --json

# Download latest data (all countries)
ip2cc update

# Download for specific date
ip2cc update --time 2025-01-01

# Limit concurrency
ip2cc update --concurrency 4

# Keep raw JSON responses
ip2cc update --keep-raw

# Force rebuild existing snapshot
ip2cc update --force

# BGP mode (default) - uses network-info + as-overview APIs
ip2cc --provider-mode bgp 8.8.8.8

# WHOIS mode - uses whois API
ip2cc --provider-mode whois 8.8.8.8

# Off - disable provider lookup
ip2cc --provider-mode off 8.8.8.8

Tab-separated values:

<ip>	<country_code>	<country_name>	<network>	<provider>

Example:

8.8.8.8	US	United States	8.8.8.0/24	GOOGLE LLC

{
  "ip": "8.8.8.8",
  "country_code": "US",
  "country_name": "United States",
  "network": "8.8.8.0/24",
  "provider": {
    "mode": "bgp",
    "asns": [15169],
    "holders": ["GOOGLE LLC"],
    "source": "RIPEstat network-info + as-overview",
    "cached": false
  },
  "snapshot_time": "2025-02-02",
  "index_built_at": "2025-02-02T10:00:00Z"
}

This tool uses data from RIPEstat Data API:

• Country prefixes: country-resource-list endpoint
• Network info (BGP): network-info endpoint
• ASN holders: as-overview endpoint
• WHOIS data: whois endpoint

The country/network data represents IP address registration and delegation from Regional Internet Registries (RIRs), not physical geolocation. An IP registered to one country may be used in another.

The binary index uses a Patricia trie structure for efficient longest-prefix-match queries:

• Version: 1
• Magic: IP2CCIDX
• Complexity: O(k) lookup where k = address bits (32 for IPv4, 128 for IPv6)
• Storage: ~/.ip2cc/cache/snapshots/<date>/

~/.ip2cc/cache/
├── snapshots/
│   ├── 2025-02-02/
│   │   ├── metadata.json
│   │   ├── index_v4.bin
│   │   ├── index_v6.bin
│   │   └── raw/           # (optional)
│   └── latest -> 2025-02-02
└── provider_cache.json

Default: ~/.ip2cc/cache

Override with --cache-dir:

ip2cc --cache-dir /custom/path update

Default: 7 days

ASN-to-holder mappings are cached locally to reduce API calls.

go build -o ip2cc ./cmd/ip2cc/

go test -v ./...

VERSION=v1.0.0
go build -ldflags="-s -w -X main.version=${VERSION}" -o ip2cc ./cmd/ip2cc/

MIT

• Data provided by RIPE NCC via RIPEstat
• Country codes from ISO 3166