QQWry.ipdb

English | Chinese

QQWry.ipdb is a Delphi/Pascal reader for IPIP.net .ipdb geolocation databases. It is designed for Delphi and Free Pascal applications that need simple offline IP lookup support and currently focuses on IPDB databases such as QQWry-Raw.ipdb and QQWry.ipdb.

Features

• Reads IPIP.net .ipdb database files from a file path or TStream.
• Supports IPv4 and IPv6 lookups when the database contains both trees.
• Exposes metadata such as build time, field list, language offsets, node count, total size, and IP version support.
• Provides raw field lookup with TIPDBFile.Find.
• Provides typed lookup records with TIPDBCity.FindInfo, TIPDBDistrict.FindInfo, TIPDBBaseStation.FindInfo, and TIPDBIDC.FindInfo.
• Provides IPv4 record enumeration with TIPDBDataBase.Seek, RecordCount, and Language.
• Handles both IPDB Raw and Std layouts:
  • Raw layout: 5 compatible fields, normalized by the reader when district_name is absent.
  • Std layout: 8 structured fields, returned without extra normalization.
• Derives country and continent codes for Raw QQWry data through a built-in country-name lookup table.
• Includes DUnit tests and demos for VCL, FMX, Delphi console, and Free Pascal.

Requirements

• Delphi 2009 or later, or Free Pascal with {$MODE DELPHI}
• A valid .ipdb database file such as QQWry.ipdb
• JsonDataObjects.pas from the Source directory (already included in this repository)

Installation

Manual

1. Clone this repository.
2. Add the Source directory to your Delphi or Lazarus project search path.
3. Add IPDB to your unit uses clause.
4. Place an .ipdb database file where your application can read it.

uses
  System.SysUtils, IPDB;

Delphinus

This repository includes Delphinus metadata:

• Delphinus.Info.json
• Delphinus.Install.json

After publishing the repository, it can be indexed by Delphinus as a source-only package.

Getting the database file

Please download the latest qqwry.ipdb from the nmgliangwei/qqwry.ipdb project and place it where your application can access it.

Direct download:

• https://raw.githubusercontent.com/nmgliangwei/qqwry.ipdb/main/qqwry.ipdb
• https://raw.githubusercontent.com/nmgliangwei/qqwry.ipdb/main/qqwry-raw.ipdb

The database files are data products from their respective providers. Check the provider license and redistribution terms before publishing them with a release or committing them to a public repository.

Raw Layout

Raw QQWry IPDB files expose five compatible fields:

country_name
region_name
city_name
owner_domain
isp_domain

For this layout, FindInfo normalizes the combined location and ISP text into standard city fields and derives country_code and continent_code.

Std Layout

Standard QQWry IPDB files expose eight structured fields:

country_name
region_name
city_name
district_name
owner_domain
isp_domain
country_code
continent_code

For this layout, FindInfo preserves the structured fields from the database.

Usage

Basic Lookup

uses
  System.SysUtils, IPDB;

procedure LookupIP;
var
  DB: TIPDBCity;
  Info: TIPDBCityInfo;
begin
  DB := TIPDBCity.Create('QQWry.ipdb');
  try
    Info := DB.FindInfo('8.8.8.8');
    Writeln(Info.CountryName);
    Writeln(Info.RegionName);
    Writeln(Info.CityName);
    Writeln(Info.ISPDomain);
    Writeln(Info.CountryCode);
    Writeln(Info.ContinentCode);
  finally
    DB.Free;
  end;
end;

Raw Field Lookup

var
  DB: TIPDBCity;
  Values: TArray<string>;
begin
  DB := TIPDBCity.Create('QQWry.ipdb');
  try
    Values := DB.Find('8.8.8.8', 'CN');
    Writeln(Values[0]);
  finally
    DB.Free;
  end;
end;

Load from Stream

var
  DB: TIPDBCity;
  Stream: TFileStream;
begin
  Stream := TFileStream.Create('QQWry.ipdb', fmOpenRead or fmShareDenyWrite);
  try
    DB := TIPDBCity.Create(Stream);
    try
      Writeln(DB.FindInfo('8.8.8.8').ToString);
    finally
      DB.Free;
    end;
  finally
    Stream.Free;
  end;
end;

Enumerate IPv4 Records

TIPDBDataBase builds an in-memory IPv4 record index and lets you iterate records by index:

var
  DB: TIPDBDataBase;
  StartIP, EndIP: string;
  Values: TArray<string>;
  I: Integer;
begin
  DB := TIPDBDataBase.Create('QQWry.ipdb');
  try
    DB.Language := 'CN';
    for I := 0 to DB.RecordCount - 1 do
    begin
      if DB.Seek(I, StartIP, EndIP, Values) then
        Writeln(Format('%s - %s: %s', [StartIP, EndIP, Values[0]]));
    end;
  finally
    DB.Free;
  end;
end;

Metadata

Writeln(DB.BuildDateTime);
Writeln(FormatDateTime('yyyy-mm-dd hh:nn:ss', DB.Meta.BuildDateTime));
Writeln(DB.Meta.Fields.CommaText);
Writeln(DB.Meta.NodeCount);
Writeln(DB.Meta.TotalSize);
Writeln(BoolToStr(DB.IPv4Support, True));
Writeln(BoolToStr(DB.IPv6Support, True));

Error Handling

The reader raises EIPDB for invalid database files, unsupported IP versions, unsupported languages, invalid IP input, and missing data. Wrap database loading and lookups in normal Delphi try/except blocks when integrating into an application.

Notes

• Source files are kept as UTF-8 with Windows CRLF line endings.
• Find returns database fields exactly as stored for the selected language.
• FindInfo maps lookup results into typed records. For Raw QQWry data, the reader splits combined location and ISP text and may add derived country and continent codes.
• TIPDBCityInfo also supports IPIP-style extended fields such as ASN, timezone, coordinates, district info, and IDC/base-station markers when the database provides them.
• FindJson is private on TIPDBFile; application code should use Find or FindInfo.
• TIPDBDataBase.Seek currently enumerates IPv4 records only.

Contributing

Contributions are welcome! Please fork this repository and submit pull requests with your improvements. Behavior changes should include matching DUnit coverage in UnitTest/.

License

This project is licensed under the Mozilla Public License 2.0. See LICENSE for details.

Acknowledgements

Thanks to the QQWry / CZ88 ecosystem for providing the IPDB database format used by this project.

If you need a more accurate or commercially supported dataset, consider the official commercial offerings from the QQWry provider.