Chunzhen (QQWry): The Legendary Chinese IP Geolocation Database

If you spent any time on the Chinese internet during the early 2000s, you lived through one of the most chaotic, innovative, and culturally vibrant eras in digital history. Long before smartphones, WeChat, and centralized cloud platforms took over everyday life, the undisputed king of Chinese cyberspace was desktop instant messaging—specifically, Tencent QQ (originally known as OICQ).

Back then, the internet felt vastly larger, more mysterious, and deeply thrilling. You would log into QQ from a smoke-filled neighborhood cybercafe (网吧), listen to the iconic cough of a new incoming message, and strike up conversations with anonymous strangers hundreds or thousands of miles away.

However, official versions of Tencent QQ kept users’ physical locations deliberately obscured. You never truly knew if the person on the other end of the chat window claiming to be a college student in Shanghai was actually sitting in an internet cafe two streets over.

That mystery spawned a massive underground software counterculture. Independent programmers began modifying the official QQ client, giving rise to legendary modded versions like Coral QQ (珊瑚虫QQ), Wood Bird QQ (木子版QQ), and the open-source LumaQQ. These modified clients did two things that official software refused to do: they completely stripped out intrusive desktop advertisements, and, crucially, they displayed the real-time IP address and exact geographic location of the person you were chatting with.

To pull off that feat entirely on client desktop machines without lag, these modded clients did not ping remote web servers. Instead, they relied on a single, compact, offline binary file bundled directly into the installation folder: `QQWry.dat`.

That file was the product of Chunzhen (纯真网络, cz88.net).

Decades before “crowdsourcing” became a celebrated Silicon Valley buzzword, Chunzhen built one of the largest, most accurate, and deeply community-maintained grassroots databases on the planet. From its humble origins in 2002–2005 to its modern commercial evolution as the encrypted CZDB database in 2026, Chunzhen represents an indispensable chapter in Chinese computer science.

I have spent decades inspecting network protocols, parsing binary datasets, and building offline diagnostic utilities. Here is my deep-dive architectural and historical breakdown of the Chunzhen (QQWry) database, how its binary structure revolutionized offline IP lookups, and where it stands today against modern enterprise APIs like IPIP.net and MaxMind.

---

The Cultural Phenomenon: QQ Mods, Cybercafes, and Grassroots Crowdsourcing

To appreciate why `QQWry.dat` became so revered among Chinese developers, you have to understand the unique technological landscape of early-2000s China.

+-------------------------------------------------------------------------+
|                  The Early 2000s Chinese QQ Mod Ecosystem               |
+-------------------------------------------------------------------------+
                                     |
    +--------------------------------+--------------------------------+
    |                                                                 |
    v                                                                 v
[ Peer-to-Peer Chat Packets ]                       [ Client-Side Resolution ]
  - Direct UDP socket negotiation                     - Local binary file lookup
  - Exposed counterparty IPv4 address                 - Zero network latency overhead
  - No server-side privacy proxy                      - Displays: "Guangdong Telecom"
                                     |
                                     v
+-------------------------------------------------------------------------+
|                 The Chunzhen Crowdsourced Engine (cz88.net)              |
| Millions of users submit IP corrections -> Bi-weekly community updates  |
+-------------------------------------------------------------------------+

1. Peer-to-Peer Packets and Direct IP Exposure

In the early days of instant messaging, network bandwidth was expensive and servers were heavily constrained. To minimize central server load, early versions of Tencent QQ negotiated direct peer-to-peer (P2P) UDP connections between two chatting clients whenever possible.

Modified clients like Chen Shouyuan’s (陈寿元) Coral QQ hooked into network socket handlers. When an incoming message arrived, the modified client captured the sender’s raw IPv4 header. But displaying a raw string of numbers like 218.19.144.32 meant nothing to an ordinary user. Users wanted to see: “Guangdong Province, Guangzhou City, Tianhe District, Cybercafe”.

Querying an external HTTP server for every incoming message was impossible:

• Dial-up modems and early ADSL connections had strict bandwidth constraints.
• Remote HTTP requests introduced noticeable UI freezes.
• Centralized IP lookup servers would have been instantly crushed under millions of simultaneous queries.

The resolution had to happen 100% offline, locally, in memory, in less than a millisecond.

2. The Bi-Weekly Ritual: The Crowdsourced Update

Chunzhen’s maintainers solved the accuracy dilemma not through corporate telemetry, but through immense community participation.

On the official cz88.net website, users could download a lightweight Windows utility. Whenever a netizen discovered that their local internet cafe, university dormitory, or regional office IP address was labeled incorrectly, they used the client to submit a correction report back to the Chunzhen team.

The Chunzhen team acted as benevolent curators. Every five days (on the 5th, 10th, 15th, 20th, 25th, and final day of every calendar month), Chunzhen compiled, sanitized, and packaged hundreds of thousands of user-submitted corrections into a fresh `QQWry.dat` file.

Downloading the latest `QQWry.dat` update became an ingrained ritual for millions of internet enthusiasts. It was open-source data curation in its purest, most altruistic form.

---

Under the Hood: The Genius of the QQWry.dat Binary Format

From an engineering perspective, the true brilliance of `QQWry.dat` lies in its file architecture. In the year 2003, typical consumer PCs had between 64 megabytes and 256 megabytes of RAM. Hard drive space was measured in single-digit gigabytes.

The author of the `QQWry.dat` format needed a structure that could store hundreds of thousands of IP ranges, map each range to two descriptive text strings (Country/Province and City/ISP), support lightning-fast searches, and keep the total file footprint under 10 to 15 megabytes without requiring a heavyweight database engine like MySQL or SQLite.

The result was an extraordinarily elegant binary file layout divided into three distinct segments: The Header, The Index Zone, and The Record Zone.

+-------------------------------------------------------------------------+
|                       QQWry.dat Binary File Map                         |
+-------------------------------------------------------------------------+
| 0x00 - 0x03 : First Index Offset (Little-Endian uint32)                 |
| 0x04 - 0x07 : Last Index Offset  (Little-Endian uint32)                 |
+-------------------------------------------------------------------------+
|                             RECORD ZONE                                 |
| - Arbitrary length, stores location strings and IP end boundaries       |
| - Uses 0x01 and 0x02 redirection pointers to eliminate duplicates       |
+-------------------------------------------------------------------------+
|                              INDEX ZONE                                 |
| - Strictly sorted 7-byte records:                                       |
|     Bytes 0-3: Start IP (uint32)                                        |
|     Bytes 4-6: Record Offset (3-byte Pointer)                           |
+-------------------------------------------------------------------------+

1. The Header (8 Bytes)

The file opens with an ultra-compact 8-byte header:

• Bytes 0–3: An unsigned 32-bit integer indicating the absolute byte offset of the first index entry.
• Bytes 4–7: An unsigned 32-bit integer indicating the absolute byte offset of the last index entry.

By reading just these 8 bytes upon opening the file, a program immediately knows the exact boundaries of the Index Zone, allowing it to calculate the total number of index records:

$$ ext{Total Records} = rac{ ext{Last Offset} - ext{First Offset}}{7} + 1$$

2. The Index Zone: Enabling O(log N) Binary Search

The Index Zone is located toward the latter portion of the file. Every single record in the Index Zone is strictly fixed at 7 bytes:

• First 4 Bytes: The Starting IP address of a block, encoded as a 32-bit unsigned Little-Endian integer.
• Last 3 Bytes: A 24-bit pointer representing the absolute byte offset pointing to the corresponding data record in the Record Zone.

Because every entry is identical in length (7 bytes) and, crucially, strictly sorted in ascending numerical order by starting IP, an application never needs to scan the file sequentially.

Instead, it executes a classic Binary Search (二分查找) directly on disk or in memory:

1. Set low index to 0, high index to Total Records - 1.
2. Calculate the midpoint: mid = (low + high) // 2.
3. Jump directly to first_offset + (mid * 7) and read the 4-byte starting IP.
4. If target IP is smaller, search the lower half; if larger, search the upper half.

Across a database containing over 500,000 distinct IP blocks, a binary search resolves any IPv4 address in at most 19 iterations ($\log_2(500{,}000) pprox 18.9$). On a modern server, this takes less than 0.005 milliseconds, permitting tens of thousands of queries per second per CPU core entirely offline.

3. The Record Zone: String Deduplication via Redirection (0x01 and 0x02)

In geographic databases, text strings are massively redundant. A telecom provider like China Telecom Guangdong might own thousands of disparate IP ranges. Repeating the strings "广东省广州市" (Country/Region field) and "电信" (Area/ISP field) half a million times would inflate the file to hundreds of megabytes.

To combat this, the creator of `QQWry.dat` implemented a brilliant pointer redirection scheme using two special single-byte control flags:

+-------------------------------------------------------------------------+
|                  QQWry String Redirection Mechanics                     |
+-------------------------------------------------------------------------+

Case A: Normal Record (No Redirection)
[ End IP (4B) ] -> [ Country String (Null-terminated) ] -> [ Area String ]

Case B: Mode 0x01 (Full Redirection)
[ End IP (4B) ] -> [ 0x01 ] -> [ 3-Byte Pointer to Another Record ]

Case C: Mode 0x02 (Country Redirection Only)
[ End IP (4B) ] -> [ 0x02 ] -> [ 3-Byte Pointer to String ] -> [ Local Area String ]

• Mode `0x01` (Full Redirect): Encountering byte 0x01 means both the Country string and the Area string are identical to an existing record elsewhere in the file. The flag is followed by a 3-byte offset. The parser jumps to that offset and resumes parsing.
• Mode `0x02` (Partial Country Redirect): Encountering byte 0x02 means only the Country/Region string is shared. The flag is followed by a 3-byte offset pointing to the shared country string, while the Area string follows immediately after or has its own subsequent 0x02 redirect.

Through this recursive pointer mechanism, thousands of distinct IP ranges share identical physical memory locations for common city and ISP names. It was a masterclass in low-level data compression engineered before modern compression libraries like Zstandard were ever conceived.

---

Step-by-Step Code Walkthrough: Building a Pure-Python QQWry Parser

Because of its elegance, writing a parser for `QQWry.dat` became a rite of passage for generations of Chinese programmers. Parsers were implemented in C, C++, Delphi, Pascal, Java, PHP, Python, Golang, Node.js, and Rust.

Here is a streamlined, educational Python implementation demonstrating how binary search and byte redirection work in practice:

import struct
import socket

class QQWryParser:
    def __init__(self, filename):
        with open(filename, 'rb') as f:
            self.data = f.read()
        
        # Read the 8-byte header
        self.first_index, self.last_index = struct.unpack('<II', self.data[0:8])
        self.total_records = (self.last_index - self.first_index) // 7 + 1

    def _ip_to_int(self, ip_str):
        # Convert dotted quad IPv4 string to big-endian integer
        return struct.unpack('!I', socket.inet_aton(ip_str))[0]

    def _read_string(self, offset):
        # Read null-terminated GBK-encoded string
        end = self.data.find(b'\x00', offset)
        if end == -1:
            return "", offset
        raw_bytes = self.data[offset:end]
        return raw_bytes.decode('gbk', errors='replace'), end + 1

    def _read_area(self, offset):
        byte = self.data[offset]
        if byte in (1, 2):
            new_offset = struct.unpack('<I', self.data[offset+1:offset+4] + b'\x00')[0]
            if byte == 2:
                return self._read_string(new_offset)[0], offset + 4
            return self._read_area(new_offset)[0], offset + 4
        return self._read_string(offset)

    def lookup(self, ip_str):
        ip_num = self._ip_to_int(ip_str)
        low = 0
        high = self.total_records - 1
        record_offset = 0

        # Perform binary search on the 7-byte Index Zone
        while low <= high:
            mid = (low + high) // 2
            idx_pos = self.first_index + (mid * 7)
            start_ip = struct.unpack('<I', self.data[idx_pos:idx_pos+4])[0]

            if ip_num >= start_ip:
                record_offset = struct.unpack('<I', self.data[idx_pos+4:idx_pos+7] + b'\x00')[0]
                low = mid + 1
            else:
                high = mid - 1

        if not record_offset:
            return "Unknown", "Unknown"

        # Check ending IP
        end_ip = struct.unpack('<I', self.data[record_offset:record_offset+4])[0]
        if ip_num > end_ip:
            return "Not Found", "Not Found"

        # Parse Country and Area strings via redirect flags
        cur = record_offset + 4
        flag = self.data[cur]

        if flag == 1: # Full Redirect
            cur = struct.unpack('<I', self.data[cur+1:cur+4] + b'\x00')[0]
            flag = self.data[cur]

        if flag == 2: # Country Redirect
            country_offset = struct.unpack('<I', self.data[cur+1:cur+4] + b'\x00')[0]
            country, _ = self._read_string(country_offset)
            area, _ = self._read_area(cur + 4)
        else:
            country, next_pos = self._read_string(cur)
            area, _ = self._read_area(next_pos)

        return country, area

Notice how the entire parsing logic requires zero third-party dependencies, relies strictly on standard binary unpacking (struct), and executes instantly.

---

The Modern Transformation: From Open QQWry to CZDB and Commercial APIs

As the internet shifted into the cloud and mobile era, Chunzhen could no longer survive as an informal, unpaid hobby project. Operating high-bandwidth servers and curating massive datasets required legitimate business infrastructure.

The project officially incorporated as Changsha Activity Communication Technology Co., Ltd. (长沙活跃网络科技有限公司) and executed a series of major structural modernizations.

1. The Retirement of Plaintext QQWry.dat and the Birth of CZDB

For over two decades, the plaintext `QQWry.dat` file was freely downloadable by anyone. However, this open accessibility led to rampant commercial abuse:

• Unscrupulous data brokers scraped Chunzhen’s dataset, rebranded it, and resold it to commercial clients.
• Automated bots hammered cz88.net servers, racking up thousands of dollars in monthly bandwidth bills.
• The lack of cryptographic verification left end users vulnerable to malicious third parties distributing trojan-infected .dat files.

In response, Chunzhen officially deprecated the legacy `QQWry.dat` format in favor of a modern, proprietary binary format called CZDB (Chunzhen Database).

The new CZDB architecture introduces:

• AES-Based Cryptographic Encryption: Database files are encrypted and cannot be unpacked without a valid authorization key.
• Dynamic Key Generation: Users must register an account on cz88.net to receive an official token/license key.
• Official Decryption SDKs: Chunzhen provides audited, official client libraries in Java, Go, Python, C++, and PHP to parse CZDB files securely.

2. Tiered Packaging in 2026: Community vs. Enterprise

Chunzhen structured its modern offerings into distinct free and paid tiers:

Tier Level	Cost / Pricing	Update Frequency	Granularity & Depth	Ideal Use Case
Community Edition (CZDB)	Free (Registration required)	Updated Weekly	Province / City level, Major ISP attribution	Open-source tools, student projects, personal homelabs
Standard Commercial	Subscription (Annual)	Updated Daily	District / County level, Detailed ISP categorization	Regional e-commerce, fraud detection, log auditing
Enterprise High-Precision	Custom Quote	Real-time / Daily	Base Station / Campus / Datacenter / VPN tagging	Telecom routing, banking security, CDN edge scheduling
Cloud HTTP REST API	Pay-as-you-go	Real-time	High-concurrency low-latency cloud endpoint	Cloud-native microservices, mobile apps

While some older netizen purists initially lamented the end of unauthenticated .dat downloads, the transition was essential to secure the database’s survival and fund full-time engineering staff.

---

Head-to-Head Comparison: Chunzhen vs. The Global Giants

How does Chunzhen compare in 2026 against its primary domestic and international rivals?

Comparison Criteria	Chunzhen (cz88.net)	IPIP.net (高春辉)	MaxMind (GeoIP2)	IP138.com
Primary Geographic Focus	Mainland China (Deepest Grassroots)	Global & China Enterprise BGP	Global (North America/Europe first)	Mainland China (Web portal)
Data Sourcing Methodology	Historic Crowdsourcing + Modern Telemetry	Active BGP/ASN Multi-Hop Traceroute	Enterprise Routing + Commercial Scraping	Commercial API Aggregator
Local Offline Database	Yes (CZDB / QQWry binary)	Yes (IPDB binary format)	Yes (MMDB binary format)	No (Web / API only)
Township / Cybercafe Granularity	Unmatched in rural China	Moderate (Focuses on datacenters)	Very Poor in China	Good
Datacenter / Proxy Detection	Good (Commercial tiers)	Industry Benchmark (Very strict)	Excellent (Global coverage)	Basic
Free Tier Accessibility	Free Community CZDB with registration	Limited free IPDB, mostly paid	Free GeoLite2 with account	Web queries free with ads
Developer Ecosystem	Cult Legend (Decades of code heritage)	Premier choice for Chinese DevOps	Universal standard in Western stacks	Casual web/script lookups

1. Chunzhen vs. IPIP.net

IPIP.net, founded by Chinese internet pioneer Gao Chunhui (高春辉), represents the academic, high-precision engineering end of the spectrum. IPIP.net builds its databases using thousands of globally distributed BGP monitoring nodes, traceroute probes, and deep network path analysis. For enterprise anti-fraud, commercial CDN traffic scheduling, and detecting cloud proxy IPs, IPIP.net is widely regarded as the gold standard in China.

However, Chunzhen holds an almost mythical advantage in grassroots municipal granularity. Because of its twenty-year history of user-submitted cybercafe, residential broadband, and township-level reports, Chunzhen frequently identifies the specific suburban district, university campus, or local broadband provider in tier-3 and tier-4 Chinese cities where algorithmic BGP tools only see a generic provincial telecom gateway.

2. Chunzhen vs. MaxMind GeoIP2

MaxMind is the undisputed universal standard across Western cloud computing. If you spin up an Nginx server or configure an AWS firewall, GeoIP2 is the default plugin.

However, MaxMind’s accuracy within mainland China has historically been notoriously underwhelming. MaxMind frequently bundles entire Chinese provinces into a single metropolitan coordinate (often dumping hundreds of millions of IP addresses onto Beijing or Shanghai) and struggles to differentiate between China Telecom, China Unicom, and China Mobile municipal sub-nets. For domestic Chinese traffic analysis, deploying Chunzhen or IPIP.net is vastly superior to relying on MaxMind.

---

High-Throughput Production Use Cases for Chunzhen

Why do modern systems engineers still choose an offline database like Chunzhen over a cloud HTTP API?

1. Extreme-Throughput Firewall & Syslog Auditing

Imagine a large enterprise network perimeter processing 50,000 firewall connection attempts per second. If you attempt to resolve those IPs by making outbound HTTP requests to a commercial cloud API:

• You would be rate-limited within seconds.
• You would spend tens of thousands of dollars per month on API credit overages.
• The network round-trip time (RTT) would stall your logging pipeline.

With an in-memory CZDB instance, your logging worker executes lookups using pure pointer arithmetic directly against RAM. A single multi-threaded Go or Rust daemon can effortlessly parse 100,000+ IP addresses per second with sub-microsecond latency and zero external network bandwidth consumption.

2. Air-Gapped and Confidential Environments

Financial institutions, government networks, and military intranet facilities operate in strict air-gapped environments with zero access to the public internet. Cloud APIs cannot function behind these perimeters. Chunzhen’s offline database can be transferred via secure media and deployed on air-gapped internal servers, providing rich geolocation intelligence without opening a single outbound firewall port.

3. Edge CDN Routing and Regional Content Localization

Content delivery networks and web servers need to make instant routing decisions at the edge. When a user requests a static asset, an edge Nginx or Envoy proxy can evaluate the user’s IP against a local CZDB in memory in 5 microseconds, routing the visitor to the nearest regional node without adding any latency to the critical rendering path.

---

Frequently Asked Questions (FAQ)

Is the original QQWry.dat format completely dead?

The official Chunzhen team no longer publishes plaintext, unencrypted `QQWry.dat` files on cz88.net, having transitioned fully to the encrypted CZDB format. However, several independent community preservation projects and third-party mirrors continue to maintain legacy-compatible .dat files derived from public routing tables for open-source enthusiasts.

Can I use Chunzhen for commercial projects without paying?

The Community Edition of CZDB is provided free of charge for non-commercial, personal, and educational use (subject to registration and license terms). If you intend to embed Chunzhen data into a commercial software product, cloud SaaS platform, or enterprise firewall, you are required to purchase a commercial license from Changsha Activity Communication Technology Co., Ltd.

What encoding did the original QQWry.dat use?

The legacy `QQWry.dat` format exclusively utilized GBK (CP936) string encoding, reflecting its Windows-centric, Chinese-domestic roots. Modern CZDB SDKs handle UTF-8 string conversion automatically.

Why does Chunzhen occasionally return “CZ88.NET” in the area field?

When Chunzhen’s maintainers knew the country or province of an IP range but lacked specific municipal or ISP data, they historically filled the secondary area field with a polite promotional string like "纯真网络" or "CZ88.NET". Seeing this string simply meant that the specific IP block was recognized at the broad regional level, but lacked detailed district-level crowdsourced data.

---

Final Verdict and Legacy

Evaluation Dimension	Score (out of 10)	Practical Assessment
Offline Performance & Speed	9.9	In-memory binary search delivers sub-microsecond lookups at 100k+ QPS.
Domestic China Granularity	9.2	Decades of grassroots crowdsourcing provide rich township/campus depth.
Architecture & Engineering	9.5	A timeless Web 1.0 masterclass in pointer redirection and deduplication.
Global / International Depth	6.0	Focus is strictly Chinese domestic; international data is basic.
Modern Licensing Accessibility	7.2	Mandatory encryption and registration ended the golden era of open downloads.
Overall Score	8.0 / 10	An enduring cultural and technical monument of the Chinese internet.

The Bottom Line

Chunzhen (QQWry) is far more than just a database file; it is an enduring cultural and technical monument to the early days of the Chinese internet. It proved that a dedicated community, united by curiosity and a desire for transparency, could build a dataset that rivaled multi-million-dollar telecommunication conglomerates.

Its binary design taught an entire generation of Chinese software engineers how to think about memory layouts, binary search trees, and byte-level optimization. Even in an era dominated by trillion-parameter neural networks and hyperscale cloud APIs, the humble binary search over `QQWry` remains a breath of fresh air: lightning-fast, self-contained, utterly reliable, and impervious to cloud outages.

For developers building high-throughput network monitoring, offline log auditing, or localized infrastructure across mainland China, Chunzhen remains a legendary and indispensable tool in the network diagnostics arsenal.