Fast offline IP-to-country lookup using RIR data with country names and currency support
Fast, offline IP geolocation using Regional Internet Registry (RIR) data
No API calls • No rate limits • No signup required • Download once, use forever
IPMapper addresses the need for reliable, offline IP geolocation without dependencies on external APIs or services. Built entirely on public Regional Internet Registry (RIR) data, it provides:
IPMapper uses a radix tree (compressed trie) for IP prefix lookups, providing optimal search complexity:
Time Complexity: O(k) where k = IP address bit length (32 for IPv4, 128 for IPv6)
Space Complexity: O(n×k) where n = number of unique prefixes
Why Radix Trees?
The library implements CIDR prefix aggregation to optimize storage and lookup performance:
Aggregation Process:
ipaddress.collapse_addresses() to merge adjacent prefixesBenefits:
# Install from PyPI
pip install ipmapper
# Or install from source
git clone https://github.com/anxkhn/ipmapper
cd ipmapper
pip install -e .
# Download and process RIR data (run once or when updating)
ipmapper update
# Basic lookup
ipmapper lookup 8.8.8.8
ipmapper lookup 2001:4860:4860::8888
# Multiple IPs with additional data
ipmapper lookup 8.8.8.8 1.1.1.1 --country-name --currency
# Quick shortcuts
ipmapper country 8.8.8.8 # Just country name
ipmapper country_code 8.8.8.8 # Just country code
ipmapper currency 8.8.8.8 # Just currency
# Output formats
ipmapper lookup 8.8.8.8 --format json
ipmapper lookup 8.8.8.8 --format csv
# Check status
ipmapper status
import ipmapper
# Simple lookups (auto-loads data on first use)
result = ipmapper.lookup('8.8.8.8')
print(result)
# {'ip': '8.8.8.8', 'country_code': 'US', 'country_name': 'United States of America', 'currency': 'USD'}
# Direct attribute access
country_name = ipmapper.get_country_name('8.8.8.8') # 'United States of America'
country_code = ipmapper.get_country_code('8.8.8.8') # 'US'
currency = ipmapper.get_country_currency('8.8.8.8') # 'USD'
# Selectively use IPv4 or IPv6 tree with IP version hints
result = ipmapper.lookup('192.168.1.1', ip_version='ipv4') # Skip IPv6 tree
result = ipmapper.lookup('2001:db8::1', ip_version='ipv6') # Skip IPv4 tree
# Advanced usage with custom data directory
lookup_engine = ipmapper.IPLookup(data_dir='/custom/path')
result = lookup_engine.lookup_full('8.8.8.8')
| RIR | Region | Data Source |
|---|---|---|
| APNIC | Asia-Pacific | delegated-apnic-extended-latest |
| ARIN | North America | delegated-arin-extended-latest |
| RIPE NCC | Europe/Middle East/Central Asia | delegated-ripencc-extended-latest |
| LACNIC | Latin America/Caribbean | delegated-lacnic-extended-latest |
| AFRINIC | Africa | delegated-afrinic-extended-latest |
allocated and assigned status onlyipmapper update - Download and process RIR data
ipmapper update [OPTIONS]
Options:
--force Force re-download even if data exists
--data-dir Custom data directory (default: ~/.ipmapper)
ipmapper lookup - Look up IP addresses
ipmapper lookup [OPTIONS] IP1 [IP2 ...]
Options:
--format [table|json|csv] Output format (default: table)
--country-name Include country names
--currency Include currency codes
--data-dir Custom data directory
ipmapper status - Show local data status
ipmapper status [OPTIONS]
Options:
--data-dir Custom data directory
ipmapper country IP # Get country name
ipmapper country_code IP # Get country code
ipmapper currency IP # Get currency code
After running ipmapper update, these files are generated:
prefixes_ipv4_agg.csv - Aggregated IPv4 prefixes (format: cidr,country_code)prefixes_ipv6_agg.csv - Aggregated IPv6 prefixes (format: cidr,country_code)metadata.json - Source URLs, timestamps, checksums, and statisticsNote: Only aggregated files are generated for optimal performance. Raw files are cleaned up automatically.
import ipmapper
def determine_currency(client_ip):
"""Automatically set payment currency based on client location"""
currency = ipmapper.get_country_currency(client_ip)
return currency or 'USD' # Default to USD
# Usage
client_ip = request.remote_addr
payment_currency = determine_currency(client_ip)
import ipmapper
RESTRICTED_COUNTRIES = {'CN', 'IR', 'KP'} # Example restrictions
def check_feature_availability(client_ip, feature_name):
"""Check if feature is available in client's country"""
country_code = ipmapper.get_country_code(client_ip)
if country_code in RESTRICTED_COUNTRIES:
return False
return True
import ipmapper
from collections import Counter
def analyze_user_geography(ip_list):
"""Analyze geographic distribution of users"""
countries = []
for ip in ip_list:
country = ipmapper.get_country_name(ip)
if country:
countries.append(country)
return Counter(countries)
# Clone repository
git clone https://github.com/anxkhn/ipmapper
cd ipmapper
# Install in development mode
pip install -e .
# Run from source
python -m ipmapper update
python -m ipmapper lookup 8.8.8.8
This project will always remain free and open source because:
| Public Data Foundation | Built entirely on publicly available RIR allocation data |
| Educational Mission | Helps people understand internet infrastructure and IP allocation |
| Community Driven | Created for developers, by developers, with no commercial agenda |
| Transparency First | All code, data sources, and methodologies are completely open |
| Self-Contained | No ongoing infrastructure costs or API maintenance requirements |
MIT License - see LICENSE file for details.
The IP allocation data is derived from public RIR delegated files, available under their respective terms of use. This library inherits those terms for the data while the code remains MIT licensed.
FAQs
Fast offline IP-to-country lookup using RIR data with country names and currency support
We found that ipmapper demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.
Security News
CISA’s 2025 draft SBOM guidance adds new fields like hashes, licenses, and tool metadata to make software inventories more actionable.