MaxMind GeoIP2 Python API

Warnings

• breaking Version 5.0.0 and above require Python 3.10 or greater. Earlier Python versions should use an older `geoip2` release (e.g., v4.x.x for Python 3.9).
  Fix: Upgrade Python to 3.10+ or pin `geoip2` to an earlier major version (e.g., `geoip2<5`) if using older Python.
• breaking The `raw` attribute on model classes has been replaced by a `to_dict()` method. Also, `ip_address` properties on models now consistently return `ipaddress.IPv4Address` or `ipaddress.IPv6Address` objects.
  Fix: Update code to use `.to_dict()` for dictionary representation and expect `ipaddress` objects for `ip_address` attributes.
• deprecated The `metro_code` on `geoip2.record.Location` is deprecated, as the code values are no longer maintained by MaxMind.
  Fix: Avoid using `metro_code` or consider alternative geographic identifiers if possible.
• deprecated Several boolean properties (e.g., `is_anonymous`, `is_anonymous_vpn`) on `geoip2.records.Traits` have been deprecated in favor of a new `anonymizer` object within the `Insights` model.
  Fix: If using the Insights web service, refactor to use the `anonymizer` object for VPN and proxy information.
• gotcha Failure to handle `geoip2.errors.AddressNotFoundError` when an IP address is not found in the database or by the web service can lead to unhandled exceptions.
  Fix: Always wrap IP lookup calls in a `try...except geoip2.errors.AddressNotFoundError:` block to gracefully handle unknown IP addresses.
• gotcha The `geoip2.database.Reader` and `geoip2.webservice.Client` objects are expensive to create. Instantiating them repeatedly in a loop will severely impact performance.
  Fix: Create `Reader` or `Client` objects once and reuse them for multiple lookups. Use `with` statements to ensure proper resource management (e.g., database file closure).
• gotcha Using values from `names` properties (e.g., `response.country.name`) as keys in databases or dictionaries is discouraged, as these names may change between MaxMind releases. Instead, use stable identifiers.
  Fix: Rely on stable identifiers like `geoname_id`, `iso_code`, or other unique codes (e.g., `response.country.iso_code`, `response.city.geoname_id`).

Install

• pip install geoip2 Install with pip

Imports

• Reader

  from geoip2.database import Reader

• Client

  from geoip2.webservice import Client

• AsyncClient

  from geoip2.webservice import AsyncClient

• AddressNotFoundError

  from geoip2.errors import AddressNotFoundError

  Exceptions must be explicitly imported to be caught by name.

Quickstart

This example demonstrates how to perform a geolocation lookup using a local GeoLite2 City database. It also includes an optional section for using the GeoIP2 Web Service, which requires a MaxMind account ID and license key. Remember to download a MaxMind database (e.g., GeoLite2-City.mmdb) and specify its path for the local database example. Reader and Client objects should be initialized once and reused for performance.

import os
import geoip2.database
from geoip2.errors import AddressNotFoundError

# --- Using a local GeoLite2 City database ---
# 1. Download GeoLite2 City database from MaxMind (requires account):
#    https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
# 2. Extract the .mmdb file (e.g., GeoLite2-City.mmdb) and place it in a known directory.

database_path = os.environ.get('GEOLITE2_CITY_DB_PATH', './GeoLite2-City.mmdb')

if not os.path.exists(database_path):
    print(f"Error: GeoLite2 City database not found at {database_path}.")
    print("Please download it from MaxMind and update GEOLITE2_CITY_DB_PATH environment variable or file path.")
else:
    try:
        # Reader objects are expensive to create and should be reused across lookups.
        with geoip2.database.Reader(database_path) as reader:
            ip_address = '8.8.8.8'
            try:
                response = reader.city(ip_address)
                print(f"IP: {ip_address}")
                print(f"  Country: {response.country.name} ({response.country.iso_code})")
                print(f"  City: {response.city.name}")
                print(f"  Location: Latitude {response.location.latitude}, Longitude {response.location.longitude}")
            except AddressNotFoundError:
                print(f"IP address {ip_address} not found in the database.")
            except Exception as e:
                print(f"An error occurred during lookup for {ip_address}: {e}")


# --- Using the GeoIP2 Web Service (requires MaxMind Account ID and License Key) ---
# MAXMIND_ACCOUNT_ID and MAXMIND_LICENSE_KEY should be set as environment variables
account_id = os.environ.get('MAXMIND_ACCOUNT_ID')
license_key = os.environ.get('MAXMIND_LICENSE_KEY')

if account_id and license_key:
    print("\n--- Web Service Lookup ---")
    try:
        # Client objects are also expensive and should be reused.
        with geoip2.webservice.Client(account_id, license_key) as client:
            ip_address_ws = '1.1.1.1'
            try:
                response_ws = client.city(ip_address_ws)
                print(f"IP: {ip_address_ws}")
                print(f"  Country: {response_ws.country.name} ({response_ws.country.iso_code})")
                print(f"  City: {response_ws.city.name}")
                print(f"  Location: Latitude {response_ws.location.latitude}, Longitude {response_ws.location.longitude}")
            except AddressNotFoundError:
                print(f"IP address {ip_address_ws} not found via web service.")
            except Exception as e:
                print(f"An error occurred during web service lookup for {ip_address_ws}: {e}")
    except Exception as e:
        print(f"Error initializing web service client: {e}")
else:
    print("\nSkipping web service example: MAXMIND_ACCOUNT_ID and MAXMIND_LICENSE_KEY environment variables not set.")