Database docs

The offline databases contain the same data as the lookups on this site. Deploy them on your own servers and query locally: no network round trip and no request limits. Every edition comes in mmdb and xdb format and covers IPv4 and IPv6.

• mmdb: one file for IPv4 and IPv6 with every field (Chinese and English names). The structure is GeoIP2-City compatible, so existing mmdb readers work as is.
• xdb: one file each for IPv4 and IPv6. Each record is a text of 18 segments separated by |; small files and very fast lookups for high-traffic services.
• Updated on the 1st of every month. File names stay the same for an edition, so upgrading means replacing the file.

Files and editions

File names are derived from the edition code, for example ipdb-enterprise:

Editions differ in the fields they contain; see the “Included in” column below, or the full comparison on Downloads.

Fields

mmdb paths use dots for nesting and [0] for the first array item. The xdb position is the segment number in the 18-segment region text; “—” means the field is not in xdb. Examples are the real record of 42.203.32.1.

Location

Network / ASN

English names

International

mmdb format

The mmdb structure is GeoIP2-City compatible: continent, country, subdivisions, city and location follow the standard layout, with names in zh-CN and en. ISP, ASN and usage type are in traits; district, division code and other additions are in extra.

The full record of 42.203.32.1 (editions with fewer fields contain a subset):

{
  "continent": { "code": "AS", "names": { "en": "Asia", "zh-CN": "亚洲" } },
  "country": { "iso_code": "CN", "names": { "en": "China", "zh-CN": "中国" } },
  "registered_country": { "iso_code": "CN", "names": { "en": "China", "zh-CN": "中国" } },
  "subdivisions": [ { "names": { "en": "Liaoning", "zh-CN": "辽宁" } } ],
  "city": { "names": { "en": "Anshan", "zh-CN": "鞍山" } },
  "location": { "latitude": 41.089748, "longitude": 122.990852, "time_zone": "Asia/Shanghai" },
  "isp": "中国电信",
  "autonomous_system_number": 4134,
  "autonomous_system_organization": "CHINANET BACKBONE",
  "traits": {
    "isp": "中国电信",
    "autonomous_system_number": 4134,
    "autonomous_system_organization": "CHINANET BACKBONE",
    "domain": "chinatelecom.com.cn",
    "user_type": "broadband"
  },
  "extra": {
    "district": { "en": "Tiedong", "zh-CN": "铁东" },
    "geo_id": "210302",
    "country_alpha3": "CHN",
    "currency_code": "CNY",
    "phone_prefix": "86",
    "languages": "zh-CN",
    "emoji_flag": "🇨🇳",
    "usage_type": "Broadband"
  }
}

In the file metadata, database_type is IP-City, languages are zh-CN and en, description contains the edition and data month, and build_epoch is the build time.

xdb format

xdb comes as two files, IPv4 and IPv6 (structure v3, vector index). Each range maps to a region text of 18 segments separated by |; segments without data are empty:

Example (42.203.32.1):

亚洲|中国|辽宁|鞍山|铁东|中国电信|122.990852|41.089748|210302|86||Asia/Shanghai|CNY|AS4134|Broadband|||CN

xdb contains Chinese names only; English names, the three-letter country code, languages, flag, AS name and AS domain are only in mmdb. The ASN has an AS prefix.

Code samples

The samples below are language-neutral pseudo-code; mmdb and xdb readers work the same way in every language: open the file, look up an IP, then read values by field path or segment number. Replace the file names with the edition you downloaded.

mmdb

Open the file with any mmdb reader. A lookup returns a nested map / object; read values by the mmdb paths in the table above. No record means an empty result.

db     = open_mmdb("ipdb-enterprise.mmdb")
record = db.lookup("42.203.32.1")

country  = record.country.names["zh-CN"]           // 中国
province = record.subdivisions[0].names["zh-CN"]   // 辽宁
city     = record.city.names["zh-CN"]              // 鞍山
district = record.extra.district["zh-CN"]          // 铁东
isp      = record.traits.isp                       // 中国电信
asn      = record.traits.autonomous_system_number  // 4134
lat, lon = record.location.latitude, record.location.longitude

xdb

Open the file for the IP version (-v6.xdb for IPv6) with an xdb library that supports structure v3. A lookup returns the region text; split it on | into 18 segments and read by index (0-based, i.e. the position in the table above minus 1).

db     = open_xdb("ipdb-enterprise-v4.xdb")
region = db.search("42.203.32.1")
// "亚洲|中国|辽宁|鞍山|铁东|中国电信|122.990852|41.089748|210302|86||Asia/Shanghai|CNY|AS4134|Broadband|||CN"

parts   = split(region, "|")
country = parts[1]    // 中国
city    = parts[3]    // 鞍山
isp     = parts[5]    // 中国电信
asn     = parts[13]   // AS4134

Download and updates

After buying a plan, download the files of your editions in the account center, or copy the curl command with your API key.

Download on a server (API key in the header, resumable):

/api/databases lists the files of your editions (size, SHA-256, build time) to verify downloads and detect new versions; see the API docs.

Data is updated on the 1st, so for example fetch the latest version at 04:00 on the 2nd of every month:

0 4 2 * * curl -sfL -o /opt/ipdb/ipdb-enterprise.mmdb.new -H "Authorization: Bearer ipk_xxx" https://bgp.cx/dl/ipdb-enterprise.mmdb && mv /opt/ipdb/ipdb-enterprise.mmdb.new /opt/ipdb/ipdb-enterprise.mmdb

Notes

• Fields without data are omitted from mmdb records and empty in xdb.
• Private and reserved addresses (e.g. 10.0.0.0/8, 192.168.0.0/16) are not in mmdb and return no result; xdb returns a record marked as reserved.
• Coordinates are the centre of the administrative area: fine for regional display, not for precise positioning.
• The data may only be used by the purchasing account within its license; reselling or public redistribution is not allowed.