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:
- Payment processing: Determine customer currency from IP for automatic payment localization
- Feature restrictions: Implement geo-blocking or feature availability based on country codes
- Compliance: Meet data residency requirements by identifying user locations
- Analytics: Understand user geographic distribution without third-party services
- Offline environments: Work in air-gapped systems or areas with limited internet connectivity
- 100% Public Data: Uses only official RIR delegated files from APNIC, ARIN, RIPE NCC, LACNIC, and AFRINIC
- No External Dependencies: Operates completely offline after initial data download
- Always Free: No API keys, accounts, or subscription fees required
- Country Codes: ISO 3166-1 alpha-2 country codes (US, DE, JP, etc.)
- Country Names: Full country names ("United States of America")
- Currency Codes: ISO 4217 currency codes (USD, EUR, JPY, etc.)
- Dual Stack: Full IPv4 and IPv6 support
- Radix Tree Lookup: O(prefix length) complexity for sub-microsecond lookups
- Prefix Aggregation: 30-70% reduction in dataset size while maintaining accuracy
- Memory Efficient: Optimized data structures for minimal RAM usage
- Auto-loading: Data loads automatically on first use
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?
- Longest Prefix Matching: Automatically finds the most specific route for any IP
- Memory Efficient: Shared prefixes are stored only once
- Cache Friendly: Tree traversal exhibits good spatial locality
- Predictable Performance: Lookup time depends only on address length, not dataset size
The library implements CIDR prefix aggregation to optimize storage and lookup performance:
Aggregation Process:
- Grouping: Group prefixes by country code and IP version
- Sorting: Sort prefixes by network address for efficient processing
- Merging: Use
ipaddress.collapse_addresses()to merge adjacent prefixes - Validation: Ensure aggregation preserves country code boundaries
Benefits:
- Reduced Memory: 30-70% fewer prefixes to store
- Faster Loading: Less data to process during initialization
- Maintained Accuracy: No loss of geographic precision
- Better Cache Utilization: Fewer tree nodes improve cache hit rates
# 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 statusimport 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 |
- Download: Fetch latest delegated files from all 5 RIRs
- Parse: Extract IPv4/IPv6 allocations with country codes
- Filter for
allocatedandassignedstatus only - Convert IPv4 address counts to CIDR blocks
- Parse IPv6 prefix lengths directly
- Filter for
- Deduplicate: Resolve overlapping entries
- Prefer most recent allocation date
- Use lexicographic registry ordering for ties
- Aggregate: Optimize prefix lists using CIDR aggregation
- Generate: Create optimized CSV files and metadata
ipmapper 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 directoryipmapper status - Show local data status
ipmapper status [OPTIONS]
Options:
--data-dir Custom data directoryipmapper country IP # Get country name
ipmapper country_code IP # Get country code
ipmapper currency IP # Get currency codeAfter 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 statistics
Note: 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 Trueimport 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.8This 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.
- GeoLite2 - MaxMind's free geolocation database
- ip2location-lite - Commercial IP geolocation with city-level data
- python-geoip - Another Python IP geolocation library
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: Create an issue for fastest response
Built with ❤️ for the open internet community