IP2Location Python Library

Warnings

• breaking The library relies on a separate IP2Location BIN database file, which must be downloaded and kept updated by the user. It does not work out-of-the-box without this file.
  Fix: Download the appropriate BIN database from IP2Location (e.g., https://lite.ip2location.com/ip2location-lite for free LITE data) and provide its path during `IP2Location.IP2Location()` initialization.
• gotcha There are two distinct Python packages: `ip2location` (this library, for local BIN databases) and `ip2location-io` (for the IP2Location.io web API service). Using `ip2locationio` will require an API key and make web requests, not read local BIN files.
  Fix: Ensure you are importing `IP2Location` if you intend to use local BIN files. If you need the web API, install and use `ip2location-io` as per its documentation.
• gotcha Using the `SHARED_MEMORY` file mode for database loading can significantly speed up lookups but consumes substantial RAM. Ensure your system has sufficient memory to cache the entire database to avoid performance issues or out-of-memory errors.
  Fix: Monitor memory usage when using `SHARED_MEMORY`. If memory is a concern, use the default `FILE_IO` mode, or consider using a smaller database. For large databases, ensure ample RAM is available.
• gotcha While the underlying C++ library is stated to be thread-safe, the Python wrapper's thread-safety when sharing a single `IP2Location` object across multiple threads for `FILE_IO` operations is not explicitly documented. For concurrent access, creating a separate `IP2Location` instance per thread or using appropriate locking mechanisms is generally safer.
  Fix: For applications with multiple threads accessing the database concurrently, consider initializing a new `IP2Location` object for each thread or process to prevent potential resource conflicts or race conditions. If a single instance is shared, implement explicit synchronization (e.g., `threading.Lock`).

Install

• pip install IP2Location Install from PyPI

Imports

• IP2Location

  import IP2Location

  The `ip2locationio` package is for the IP2Location.io web API, not the local BIN database library.

Quickstart

This quickstart demonstrates how to load an IP2Location BIN database file and query geolocation information for an IP address. You must download a database file separately and provide its path.

import IP2Location
import os

# NOTE: You must download an IP2Location BIN database file separately.
# For a free LITE database: https://lite.ip2location.com/ip2location-lite
# Place the .BIN file in a 'data' directory or specify its full path.
DB_PATH = os.path.join("data", "IP2LOCATION-LITE-DB1.BIN") # Replace with your actual database file

# Ensure the database file exists
if not os.path.exists(DB_PATH):
    print(f"Error: IP2Location BIN database not found at {DB_PATH}")
    print("Please download a database from https://lite.ip2location.com/ip2location-lite")
else:
    try:
        # Initialize the IP2Location object with the database file
        # Use 'FILE_IO' (default) or 'SHARED_MEMORY' if your system has enough RAM (IP2Location.IP2LOCATION_SHARED_MEMORY)
        database = IP2Location.IP2Location(DB_PATH)
        
        # Lookup an IP address
        ip_address = "8.8.8.8" # Google Public DNS
        rec = database.get_all(ip_address)

        if rec:
            print(f"IP Address: {ip_address}")
            print(f"Country Code: {rec.country_short}")
            print(f"Country Name: {rec.country_long}")
            print(f"Region Name: {rec.region}")
            print(f"City Name: {rec.city}")
            print(f"Latitude: {rec.latitude}")
            print(f"Longitude: {rec.longitude}")
            print(f"ISP: {rec.isp}")
            # Access other fields like rec.zipcode, rec.timezone, etc.
        else:
            print(f"No data found for IP: {ip_address}")
            print("This might mean your database does not contain this IP range or is outdated.")
    except Exception as e:
        print(f"An error occurred: {e}")
        print("Ensure your BIN database is compatible with the library version and not corrupted.")