IPGeolocation MMDB Reader

A fast, minimal, pure‑Python reader for MMDB files.

• Zero dependencies
• Supports both IPv4 and IPv6 lookups

Requirements

• Python 3.9+ (older versions are not supported)

Installation

pip install ipgeolocation-mmdb-reader

Getting a Database

To use this module, you must have an MMDB file. You can build your own MMDB file, or download ready-made databases samples from ipgeolocation.io. Downloaded files are in zip format and must be uncompressed using unzip.

Quick Start (Python)

After you have obtained a database and imported the module, call IPGeolocationMMDBReader with a path to the database as the first argument. The IPGeolocationMMDBReader function returns a Reader object. To look up an IP address, use the lookup method on this object. The method will return the corresponding values for the IP address from the database. If the database does not contain a record for that IP address, the method will return None.

If you wish to retrieve the metadata of that MMDB file, you can use the get_metadata method. This will return a tuple containing the metadata of that mmdb file.

import json # for pretty print results
from ipgeo_mmdb_reader.reader import IPGeolocationMMDBReader

with IPGeolocationMMDBReader("db-ip-city-company-asn.mmdb") as r:
    metadata = r.get_metadata()
    result = r.lookup("1.1.1.1")
    if result is None:
        print("No match")
    else:
        print(json.dumps(metadata, indent=4, ensure_ascii=False))
        print(json.dumps(result, indent=4, ensure_ascii=False))

• lookup(ip: str) -> dict | None Returns a dictionary of values for the IP address, or None if the IP is not present in the database.

• get_metadata() -> dict Returns a dictionary containing the MMDB file’s metadata.

Response

• Metadata

{
    "binary_format_major_version": 2,
    "binary_format_minor_version": 0,
    "build_epoch": 1754992987,
    "database_type": "ipgeolocation.io Database",
    "description": {
        "en": "MAX-IP-GEO Database from ipgeolocation.io."
    },
    "ip_version": 6,
    "languages": [
        "en",
        "de",
        "ru",
        "ko",
        "pt",
        "ja",
        "fa",
        "fr",
        "zh-CN",
        "es",
        "cs",
        "it"
    ],
    "node_count": 108458689,
    "record_size": 32
}

• IP Lookup

{
  "asn": {
    "as_number": "13335",
    "country_code": "US",
    "domain": "cloudflare.com",
    "organization": "Cloudflare, Inc.",
    "type": "BUSINESS"
  },
  "company": {
    "domain": "",
    "name": {
      "en": "APNIC Research and Development"
    },
    "type": ""
  },
  "connection_type": "",
  "location": {
    "accuracy_radius": "18.654",
    "city": {
      "name": {
        "cs": "Jižní Brisbane",
        "de": "South Brisbane",
        "en": "South Brisbane",
        "es": "Brisbane Sur",
        "fa": "بریزبن جنوبی",
        "fr": "Brisbane Sud",
        "it": "Brisbane Meridionale",
        "ja": "サウスブリスベン",
        "ko": "사우스브리즈번",
        "pt": "Brisbane Sul",
        "ru": "Южный Брисбен",
        "zh": "南布里斯班"
      }
    },
    "confidence": "medium",
    "coordinates": {
      "latitude": "-27.47306",
      "longitude": "153.01421"
    },
    "country": {
      "capital": {
        "cs": "Canberra",
        "de": "Canberra",
        "en": "Canberra",
        "es": "Canberra",
        "fa": "کانبرا",
        "fr": "Canberra",
        "it": "Canberra",
        "ja": "キャンベラ",
        "ko": "캔버라",
        "pt": "Camberra",
        "ru": "Канберра",
        "zh": "堪培拉"
      },
      "code2": "AU",
      "code3": "AUS",
      "code_ioc": "AUS",
      "continent": {
        "code": "OC",
        "name": {
          "cs": "Oceánie",
          "de": "Ozeanien",
          "en": "Oceania",
          "es": "Oceanía",
          "fa": "اقیانوسیه",
          "fr": "Océanie",
          "it": "Oceania",
          "ja": "オセアニア",
          "ko": "오세아니아",
          "pt": "Oceania",
          "ru": "Океания",
          "zh": "大洋洲"
        }
      },
      "currency": {
        "code": "AUD",
        "name": {
          "cs": "Australský dolar",
          "de": "Australischer Dollar",
          "en": "Australian Dollar",
          "es": "Dólar australiano",
          "fa": "دلار استرالیا",
          "fr": "Dollar australien",
          "it": "Dollaro australiano",
          "ja": "オーストラリア・ドル",
          "ko": "호주 달러",
          "pt": "Dólar australiano",
          "ru": "Австралийский доллар",
          "zh": "澳大利亚元"
        },
        "symbol": "A$"
      },
      "metadata": {
        "calling_code": "+61",
        "languages": "en-AU",
        "tld": ".au"
      },
      "name": {
        "cs": "Austrálie",
        "de": "Australien",
        "en": "Australia",
        "es": "Australia",
        "fa": "استرالیا",
        "fr": "Australie",
        "it": "Australia",
        "ja": "オーストラリア",
        "ko": "호주",
        "pt": "Austrália",
        "ru": "Австралия",
        "zh": "澳大利亚"
      },
      "name_official": {
        "cs": "Australské společenství",
        "de": "Commonwealth of Australia",
        "en": "Commonwealth of Australia",
        "es": "Mancomunidad de Australia",
        "fa": "قلمرو همسود استرالیا",
        "fr": "Commonwealth d’Australie",
        "it": "Commonwealth dell’Australia",
        "ja": "オーストラリア連邦",
        "ko": "오스트레일리아 연방",
        "pt": "Comunidade da Austrália",
        "ru": "Содружество Австралии",
        "zh": "澳大利亚联邦"
      }
    },
    "district": {
      "name": {
        "cs": "Brisbane",
        "de": "Brisbane",
        "en": "Brisbane",
        "es": "Brisbane",
        "fa": "بریزبن",
        "fr": "Brisbane",
        "it": "Brisbane",
        "ja": "ブリスベン",
        "ko": "브리즈번",
        "pt": "Brisbane",
        "ru": "Брисбен",
        "zh": "布里斯班"
      }
    },
    "dma_code": "",
    "geoname_id": "10113228",
    "state": {
      "code": "AU-QLD",
      "name": {
        "cs": "Queensland",
        "de": "Queensland",
        "en": "Queensland",
        "es": "Queensland",
        "fa": "کوئینزلند",
        "fr": "Queensland",
        "it": "Queensland",
        "ja": "クイーンズランド",
        "ko": "퀸즐랜드",
        "pt": "Queensland",
        "ru": "Квинсленд",
        "zh": "昆士兰"
      }
    },
    "zipcode": "4101"
  },
  "time_zone": "Australia/Brisbane"
}

Exceptions

These custom exceptions may be raised:

• CorruptDatabaseError – The database is corrupt or invalid.
• MMDBError – Invalid IP address format, or an IPv6 address queried against an IPv4-only database.
• MetadataError – Metadata is invalid or not a dictionary.
• UnsupportedRecordSizeError – Record size is not one of 24, 28, or 32 bits.

Versioning

This project follows semantic versioning.

Support

Please report all issues with this code using the GitHub issue tracker