lionsoul2014 /ip2region

Ip2region is an offline IP-to-Region localization library and IP data management framework with both IPv4 and IPv6 supports, 10-microsecond level query efficiency, xdb search client for many programming languages

★ 19,934⑂ 3,109👁 433⑃ 247● 298▤ 26
GoNOASSERTIONCreated 2015-11-02ip2region.net
Download: v3.19.0v3.19.0 ↓3.19.02026-11-10
+1
Daily
+121
Weekly
+250
Monthly
19,934
stars
3,109
forks
433
watchers
247
prs
298
issues
26
releases

README

:globe_with_meridians: 中文简体 | English

 ip2region

ip2region - is an offline IP address localization library and IP localization data management framework. It supports both IPv4 and IPv6 with query efficiency at the 10-microsecond level. It provides xdb data generation and query client implementations for many mainstream programming languages.


 Features

 1. Offline Localization Library

The project itself provides raw data for both IPv4 (data/ipv4_source.txt) and IPv6 (data/ipv6_source.txt), along with corresponding xdb files (data/ip2region_v4.xdb and data/ip2region_v6.xdb) to achieve city-level query localization. The field format is: Country|Province|City|ISP|iso-alpha2-code. Localization information for China is entirely in Chinese, while regional information for non-China areas is entirely in English.

 2. Data Management Framework

xdb supports hundreds of millions of IP data segment rows. Region information supports full customization. The region information of the built-in data is fixed in the format: Country|Province|City|ISP|iso-alpha2-Code. You can append data for specific business needs to the region, such as: GPS information/International Standard Regional Codes/Zip codes, etc. In other words, you can fully use ip2region to manage your own IP localization data.

 3. Data Deduplication and Compression

The xdb format generation program automatically processes the input raw data, checks and completes the merging of adjacent IP segments, and performs deduplication and compression of identical regional information.

 4. High-Speed Query Response

Even for queries based entirely on the xdb file, the single query response time is at the 10-microsecond level. Memory-accelerated queries can be enabled through the following two methods:

1. vIndex Index Caching: Uses a fixed 512KiB of memory to cache vector index data, reducing one disk IO operation and maintaining average query efficiency within 100 microseconds.
2. Entire xdb File Caching: Loads the entire xdb file into memory. Memory usage is equal to the xdb file size. There is no disk IO operation, maintaining 10-microsecond level query efficiency.

 5. Unified Query Interface

xdb provides version-compatible query implementations. A unified API can simultaneously provide queries for both IPv4 and IPv6 data and return unified data.


 xdb Query

For API introductions, usage documentation, and test programs, please refer to the README introduction under the corresponding searcher query client. All query binding implementations are as follows:

| Language | Description | IPv4 Support | IPv6 Support |
| --- | --- | --- | --- |
| Golang         | golang query client          | :white_check_mark: | :white_check_mark: |
| PHP               | php query client             | :white_check_mark: | :white_check_mark: |
| Java             | java query client            | :white_check_mark: | :white_check_mark: |
| C                   | C[std=c99] query client      | :white_check_mark: | :white_che

Top issues

Latest release

v3.19.0 v3.19.0 2026-11-10
New Features
 IPv4 source and binary data updates with community reports merge.
 Type Annotations and UV package manager for Python binding, Pypi version 3.0.6.
 CI test for all binding and maker.
 Logstash filter plugin binding.
 fix the Possible heap-buffer-overflow due to corrupted .xdb file.

 What's Changed
 merge fix reported by community by @lionsoul2014 in https://github.com/lionsoul2014/ip2region/pull/528
 merge fixed reported by issue 529 by @lionsoul2014 in https://github.com/lionsoul2014/ip2region/pull/530
 ✨ Python type annotations by @sunkunxi in https://github.com/lion

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON