Master Offline IP Geolocation with ip2region: Fast, Accurate, Multi‑Language Support

ip2region is an offline IP address location library with 99.9% accuracy, sub‑millisecond query latency, and a database file only a few megabytes in size. It provides bindings for Java, PHP, C, Python, Node.js, Go, C#, Rust, Lua, Nginx and more, supporting three query algorithms.

Ip2region Features

99.9% Accuracy

The data aggregates sources such as Taobao IP library (>80% coverage), GeoIP (~10%), and pure IP library (~2%). Accuracy is verified to be higher than classic pure‑IP solutions.

Standardized Data Format

Each IP segment follows the format: _cityId|country|region|province|city|ISP_ Only Chinese data is resolved to city level; other countries may stop at country level.

Small Size

The generated ip2region.db file ranges from 1.5 MB to under 8 MB depending on data detail.

Fast Query Speed

All client queries run in sub‑millisecond time. Three algorithms are provided:

memory : loads the whole DB into memory; queries complete within ~0.1 ms (C client ~0.00x ms).

binary : binary search on the file; queries complete within ~0.x ms.

b‑tree : B‑tree search on the file; slightly faster than binary, also ~0.x ms.

Multiple Language Bindings

Supported bindings include Java, C#, PHP, C, Python, Node.js, Go, Rust, Lua, Lua‑C, Nginx, and more.

Quick Test

Run the CLI demo for each binding. Example for the C binding:

cd binding/c/
 gcc -g -O2 testSearcher.c ip2region.c
 ./a.out ../../data/ip2region.db

Sample output shows the queried IP, location hierarchy, ISP, and execution time.

Installation

Various installation methods are available:

Maven

<dependency>
    <groupId>org.lionsoul</groupId>
    <artifactId>ip2region</artifactId>
    <version>1.7.2</version>
</dependency>

Node.js

npm install node-ip2region --save

NuGet

Install-Package IP2Region

PHP Composer

# Plugin from https://github.com/zoujingli/ip2region
composer require zoujingli/ip2region

Concurrent Usage

All search interfaces are not thread‑safe; create separate search objects per thread. For high concurrency, increase the OS file‑descriptor limit or use the persistent memory algorithm.

The memorySearch interface can be safely used in multithreaded environments after a pre‑query that loads the DB into memory.

Generating ip2region.db

Since version 1.8, a Java program for generating ip2region.db is provided. Use the supplied JAR:

java -jar dbMaker-{version}.jar -src textDataFile -region regionCsvFile [-dst outputDir]

Example command:

cd ${ip2region_root}/java/
java -jar dbMaker-1.2.2.jar -src ./data/ip.merge.txt -region ./data/global_region.csv