explaingit

lionsoul2014/ip2region

📈 Trending★ 19,028JavaAudience · developerComplexity · 2/5ActiveLicenseSetup · easy

TLDR

Offline IP-to-location lookup library that translates IP addresses to country, city, and ISP without network requests. Ships with compact data file for fast, reliable geolocation.

Mindmap

mindmap
  root((repo))
    What it does
      IP to location
      Offline lookups
      No API calls
    Data format
      Compact xdb file
      IPv4 and IPv6
      10 microsecond speed
    Languages supported
      Java core
      Go Python JS
      Rust C++ PHP
    Use cases
      Region content
      Geo restrictions
      Traffic logging
    Deployment
      Ship with app
      Load into memory
      Nginx extension

Things people build with this

USE CASE 1

Show region-specific content or language to users based on their IP location without calling external APIs.

USE CASE 2

Enforce geo-restrictions or block traffic from specific countries directly in your application.

USE CASE 3

Log and analyze where your traffic originates for security and analytics without external dependencies.

Tech stack

JavaGoPythonJavaScriptRustC++PHPNginx

Getting it running

Difficulty · easy Time to first run · 5min
Use freely for any purpose including commercial. Keep the notice and disclose changes to the patent grant.

In plain English

ip2region is an offline library that translates an IP address into geographic and network information, specifically the country, province, city, and internet service provider, without making any network requests. Most IP-to-location lookups call a remote API, which adds latency, costs money, and stops working if you go offline. ip2region bundles all the lookup data in a compact binary file format called xdb that you ship with your application. Lookups against the xdb file take around 10 microseconds (incredibly fast, that's about ten millionths of a second). You can optionally load part or all of the file into memory to make it even faster. The library supports both IPv4 and IPv6 addresses and exposes a consistent API across many programming languages, including Go, Java, Python, JavaScript, Rust, C, C++, PHP, C#, Lua, Erlang, and even an Nginx extension. You would use ip2region when you need to geolocate users inside your own infrastructure, for example to show region-specific content, enforce geo-restrictions, or log where traffic comes from, without depending on an external service. The core project is written in Java, though client libraries are available in over a dozen languages. The bundled IP data is updated periodically; teams with high accuracy requirements can integrate commercial data from the ip2region community.

Copy-paste prompts

Prompt 1
How do I integrate ip2region into my Java application to look up a user's city and country from their IP address?
Prompt 2
Show me how to load the ip2region xdb file into memory for faster lookups in a production Python service.
Prompt 3
Can I use ip2region to block requests from specific countries? Walk me through the setup.
Prompt 4
How do I add the ip2region Nginx extension to geolocate incoming requests at the edge?
Open on GitHub → Explain another repo

Generated 2026-05-18 · Model: sonnet-4-6 · Verify against the repo before relying on details.