{"library":"geoip2","title":"MaxMind GeoIP2 Python API","description":"The geoip2 Python package provides an API for both MaxMind's GeoIP2 and GeoLite2 web services and local databases. It allows developers to perform IP geolocation lookups, retrieving information such as country, city, and ASN details. The library is actively maintained, with version 5.2.0 being the latest stable release, and follows semantic versioning with a regular release cadence.","status":"active","version":"5.2.0","language":"en","source_language":"en","source_url":"https://github.com/maxmind/GeoIP2-python","tags":["geolocation","geoip","maxmind","ip-lookup","database","web-service"],"install":[{"cmd":"pip install geoip2","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for reading local MaxMind DB files (often installed as a dependency of geoip2).","package":"maxminddb","optional":false},{"reason":"Used by the synchronous web service client.","package":"requests","optional":true},{"reason":"Used by the asynchronous web service client.","package":"aiohttp","optional":true}],"imports":[{"symbol":"Reader","correct":"from geoip2.database import Reader"},{"symbol":"Client","correct":"from geoip2.webservice import Client"},{"symbol":"AsyncClient","correct":"from geoip2.webservice import AsyncClient"},{"note":"Exceptions must be explicitly imported to be caught by name.","wrong":"try: ... except AddressNotFoundError: ... (without import)","symbol":"AddressNotFoundError","correct":"from geoip2.errors import AddressNotFoundError"}],"quickstart":{"code":"import os\nimport geoip2.database\nfrom geoip2.errors import AddressNotFoundError\n\n# --- Using a local GeoLite2 City database ---\n# 1. Download GeoLite2 City database from MaxMind (requires account):\n#    https://dev.maxmind.com/geoip/geolite2-free-geolocation-data\n# 2. Extract the .mmdb file (e.g., GeoLite2-City.mmdb) and place it in a known directory.\n\ndatabase_path = os.environ.get('GEOLITE2_CITY_DB_PATH', './GeoLite2-City.mmdb')\n\nif not os.path.exists(database_path):\n    print(f\"Error: GeoLite2 City database not found at {database_path}.\")\n    print(\"Please download it from MaxMind and update GEOLITE2_CITY_DB_PATH environment variable or file path.\")\nelse:\n    try:\n        # Reader objects are expensive to create and should be reused across lookups.\n        with geoip2.database.Reader(database_path) as reader:\n            ip_address = '8.8.8.8'\n            try:\n                response = reader.city(ip_address)\n                print(f\"IP: {ip_address}\")\n                print(f\"  Country: {response.country.name} ({response.country.iso_code})\")\n                print(f\"  City: {response.city.name}\")\n                print(f\"  Location: Latitude {response.location.latitude}, Longitude {response.location.longitude}\")\n            except AddressNotFoundError:\n                print(f\"IP address {ip_address} not found in the database.\")\n            except Exception as e:\n                print(f\"An error occurred during lookup for {ip_address}: {e}\")\n\n\n# --- Using the GeoIP2 Web Service (requires MaxMind Account ID and License Key) ---\n# MAXMIND_ACCOUNT_ID and MAXMIND_LICENSE_KEY should be set as environment variables\naccount_id = os.environ.get('MAXMIND_ACCOUNT_ID')\nlicense_key = os.environ.get('MAXMIND_LICENSE_KEY')\n\nif account_id and license_key:\n    print(\"\\n--- Web Service Lookup ---\")\n    try:\n        # Client objects are also expensive and should be reused.\n        with geoip2.webservice.Client(account_id, license_key) as client:\n            ip_address_ws = '1.1.1.1'\n            try:\n                response_ws = client.city(ip_address_ws)\n                print(f\"IP: {ip_address_ws}\")\n                print(f\"  Country: {response_ws.country.name} ({response_ws.country.iso_code})\")\n                print(f\"  City: {response_ws.city.name}\")\n                print(f\"  Location: Latitude {response_ws.location.latitude}, Longitude {response_ws.location.longitude}\")\n            except AddressNotFoundError:\n                print(f\"IP address {ip_address_ws} not found via web service.\")\n            except Exception as e:\n                print(f\"An error occurred during web service lookup for {ip_address_ws}: {e}\")\n    except Exception as e:\n        print(f\"Error initializing web service client: {e}\")\nelse:\n    print(\"\\nSkipping web service example: MAXMIND_ACCOUNT_ID and MAXMIND_LICENSE_KEY environment variables not set.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.10+ or pin `geoip2` to an earlier major version (e.g., `geoip2<5`) if using older Python.","message":"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).","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update code to use `.to_dict()` for dictionary representation and expect `ipaddress` objects for `ip_address` attributes.","message":"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.","severity":"breaking","affected_versions":">=4.5.0"},{"fix":"Avoid using `metro_code` or consider alternative geographic identifiers if possible.","message":"The `metro_code` on `geoip2.record.Location` is deprecated, as the code values are no longer maintained by MaxMind.","severity":"deprecated","affected_versions":">=4.5.0"},{"fix":"If using the Insights web service, refactor to use the `anonymizer` object for VPN and proxy information.","message":"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.","severity":"deprecated","affected_versions":">=4.5.0"},{"fix":"Always wrap IP lookup calls in a `try...except geoip2.errors.AddressNotFoundError:` block to gracefully handle unknown IP addresses.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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).","message":"The `geoip2.database.Reader` and `geoip2.webservice.Client` objects are expensive to create. Instantiating them repeatedly in a loop will severely impact performance.","severity":"gotcha","affected_versions":"All"},{"fix":"Rely on stable identifiers like `geoname_id`, `iso_code`, or other unique codes (e.g., `response.country.iso_code`, `response.city.geoname_id`).","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}