lionsoul2014/ip2region

A sensible choice when IP-region lookup has to happen inside your own process and outbound geo-API calls are unwelcome. The trade-off is data freshness: the shipped source files are updated irregularly, and the project points users with strict accuracy needs toward commercial data.

The problem

You receive a request with a client IP and need to attach a country, province, city or ISP before logging, routing, fraud checks or content decisions. Calling a hosted geo-IP service means a network round trip per lookup, an external dependency and a per-query cost model. With ip2region, that lookup becomes a local function call against a binary xdb file shipped with the app, so the pipeline step is the same but the result comes from disk or memory rather than the network.

What's different

The project is two things: a query client available for many mainstream languages, and an xdb generation program in Go and Java that builds the database from raw segment files. The format handles both IPv4 and IPv6 through one API, and the maker merges adjacent IP segments and deduplicates identical region strings, so a large source list does not have to be carried around verbatim. For speed, the README documents three modes: pure file queries at roughly 10 microseconds, a fixed 512 KiB vector-index cache that reduces disk I/O with average queries within 100 microseconds, and loading the whole xdb into memory for roughly 10-microsecond queries at a memory cost equal to the file size. Those figures are the project's claims, not independent benchmarks.

The interesting part is that the region field is not fixed to the built-in Country|Province|City|ISP|iso-alpha2-Code layout. You can append GPS coordinates, ZIP codes or business-specific attributes, which makes xdb usable as a small IP-data management format rather than only a lookup table. The main cost is operational: you own the build step, the resulting file's updates and any custom field compatibility across the language bindings you actually use. The bundled China data is in Chinese while non-China data is in English, which matters if you need a uniform locale.

Who should try it

This fits backends and services that need high-volume, low-latency region lookups and can tolerate a periodic data-refresh process — for example, enriching request logs or doing coarse region checks inside an application already written in Go, PHP, Java or another supported binding. It is a poor fit for products where the IP region must be current and authoritative, such as compliance decisions or targeted offers tied to precise location, because the README itself says the included source files are updated irregularly and recommends commercial offline data for accuracy-sensitive and frequently updated scenarios. Teams that only need an occasional lookup, or cannot ship and maintain a binary data file, should measure whether a hosted API is simpler for them.

Requirements and limitations

You need a supported client binding for your language and, if you build your own database, the Go or Java maker. Data maintenance is the real ongoing constraint: the repository's raw data is not on a fixed update schedule, so a production plan must account for refreshing it — either from your own source data or from a purchased feed. The README points to a detection-based update concept described in video sessions rather than a ready-made turnkey sync service, so expect to write or adapt that program.

Performance settings also carry trade-offs: the 512 KiB index cache is fixed-size, full-file caching uses memory equal to the database size, and the latency numbers are the project's stated figures. The xdb binary and its field layout become part of your storage or serialization boundary; adding fields is supported, but the bindings you use must agree on the format your maker produces.

HotRepo's take

The repository is 4013 days old, and the only recorded daily-board observation is 2026-10-28 at 19,774 stars with +22 that day. With one comparable dated sample, HotRepo cannot judge whether interest is rising, fading or sustained; this is a snapshot, not a trend. As a long-lived project it has a mature-looking multi-language client line, but before adopting it, verify that the binding you need documents the same xdb version and IPv6 behavior as your maker build, and decide explicitly how often you will refresh the data file project overview.