Using the ip2region Offline IP Geolocation Library with Java

Many online platforms now display the geographic location of authors and commenters, a feature that can be implemented by using IP‑to‑location services.

While some commercial platforms offer paid APIs for this purpose, their free quotas are limited and may not meet production needs.

The article recommends the open‑source ip2region offline library, which boasts up to 99.9% accuracy, a tiny 10 MB database, and bindings for Java, PHP, C, Python, Node.js, Go, and C#.

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

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

Download the offline data file ip2region.xdb and place it on your filesystem. A simple Java example that creates a Searcher object, queries an IP address, prints the region, I/O count, and latency, and finally closes the resource is shown below:

public class IpTest {
    public static void main(String[] args) throws Exception {
        // 1. Create searcher (use offline file 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(); // Happyjava
            String region = searcher.search(ip);
            long cost = TimeUnit.NANOSECONDS.toMicros((long) (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 resource
        searcher.close();
        // Note: In concurrent scenarios each thread should create its own Searcher instance.
    }
}

The program produces output similar to:

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

The region string follows the format Country|Area|Province|City|ISP , with missing parts represented by 0 . The library works for both domestic and foreign IP addresses.

In summary, ip2region is a highly accurate, lightweight offline solution that can be easily integrated into Java (and other language) back‑end projects requiring IP location functionality.