tatemz / IPToCC

Get country code of IPv4/IPv6 address. Address lookup is done offline.

IPToCC

Get ISO country code of IPv4/IPv6 address. Address lookup is done locally.

• No external API call.
• No paid GeoIP service.

Table of Contents

• Table of Contents
• Background
  • Features
• Install
• Usage
• Sources
• Libraries Used
• Old implementations
• References
• Maintainers
• Contribution
  • Install Dependencies
  • Testing
  • Build Geolocation Database
  • Docker Environment
• License

Background

To learn about using IP addresses for geolocation, read the Wikipedia article to gain a basic understanding.

Also read The Free and Simple Way To Know Who Visits Your Site.

Features

• Thread-safe
• Offline

Install

pip install IPToCC

Usage

import iptocc
country_code = iptocc.get_country_code('<IPv4/IPv6 address>')

Sources

The static database that comes with this library is built from the following sources

• ftp://ftp.afrinic.net/stats/afrinic/delegated-afrinic-extended-latest
• ftp://ftp.arin.net/pub/stats/arin/delegated-arin-extended-latest
• ftp://ftp.apnic.net/public/apnic/stats/apnic/delegated-apnic-extended-latest
• ftp://ftp.lacnic.net/pub/stats/lacnic/delegated-lacnic-extended-latest
• ftp://ftp.ripe.net/pub/stats/ripencc/delegated-ripencc-extended-latest

Libraries Used

• TinyDB
• UltraJSON

Old implementations

• SQLAlchemy + SQLite - Not thread-safe
• UnQLite - large database file, problems with thread-safety

References

• RIR Statistics Exhange Format
• How can I compile an IP address to country lookup database to make available for free?

Maintainers

• Ronie Martinez

Contribution

Install Dependencies

To setup your project, run the following setup.py script:

python setup.py install

Testing

To test your project, run the following setup.py script:

python setup.py test

Build Geolocation Database

To build the database, run the following database_builder.py script:

python database_builder.py

Docker Environment

This repo contains a Dockerfile in the case that a local development environment is needed to install the dependencies, build the database, as well as run tests in both Python 2 and Python 3.

To build the Docker image, see the following two example commands:

docker build --build-arg VERSION=2 -t iptocc:v2 ./
docker build --build-arg VERSION=3 -t iptocc:v3 ./

To build the Docker images without running the database_builder.py script, pass --build-arg SKIP_BUILD_DB=true to the build command.

The default command that is run within the Docker image is python setup.py test. To run the tests within a Docker container, see the following two example commands:

docker run --rm -it -e PYTHONPATH=. iptocc:v2
docker run --rm -it -e PYTHONPATH=. iptocc:v3

License

MIT © Ronie Martinez