Using the ip2region Offline IP Location Library with Java

Many online platforms now display the author’s and commenters’ IP location, which can be implemented either via paid third‑party APIs or by using a free offline database.

Paid APIs often have limited free quotas and may not meet production needs, so a cost‑effective alternative is the open‑source ip2region library, which offers 99.9% accuracy, sub‑millisecond query speed, and a small 10 MB database file.

The library supports multiple languages (Java, PHP, C, Python, Node.js, Go, C#) and provides three query algorithms: Binary, B‑Tree, and Memory.

To use it in a Java project, add the Maven dependency:

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

Download the offline database file ip2region.xdb and place it on your filesystem.

Below is a complete example that creates a Searcher object, queries the IP 110.242.68.66 , measures the query time, and prints the region information:

public class IpTest {

    public static void main(String[] args) throws Exception {
        // 1. Create searcher (replace with your XDB path)
        String dbPath = "C:\\Users\\Administrator\\Desktop\\ip2region.xdb";
        Searcher searcher = null;
        try {
            searcher = Searcher.newWithFileOnly(dbPath);
        } catch (Exception e) {
            System.out.printf("failed to create searcher with `%s`: %s\n", dbPath, e);
            return;
        }

        // 2. Query
        String ip = "110.242.68.66";
        try {
            long sTime = System.nanoTime(); // start timer
            String region = searcher.search(ip);
            long cost = TimeUnit.NANOSECONDS.toMicros(System.nanoTime() - sTime);
            System.out.printf("{region: %s, ioCount: %d, took: %d μs}\n", region, searcher.getIOCount(), cost);
        } catch (Exception e) {
            System.out.printf("failed to search(%s): %s\n", ip, e);
        }

        // 3. Close resources
        searcher.close();

        // Note: For concurrent use, each thread should create its own Searcher instance.
    }
}

The output looks like:

{region: 中国|0|河北省|保定市|联通, ioCount: 3, took: 1192 μs}

The region string follows the format Country|Region|Province|City|ISP , where missing information is represented by 0 . The library works for both domestic and international IP addresses.

In summary, the ip2region offline library provides a fast, accurate, and lightweight solution for IP‑location needs in Java backend projects.