{"id":7312,"library":"ipinfo","title":"IPinfo Python Library","description":"The official Python client library for the IPinfo API, providing comprehensive IP address details like geolocation, ASN, company, privacy detection, and more. It offers both synchronous and asynchronous interfaces. As of version 5.5.0, it supports new IPinfo Core and Plus API features. The library maintains an active development status with regular, feature-driven releases.","status":"active","version":"5.5.0","language":"en","source_language":"en","source_url":"https://github.com/ipinfo/python","tags":["IP address","geolocation","network","API client","geocoding"],"install":[{"cmd":"pip install ipinfo","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The Handler class is located in the `ipinfo.handler` submodule, not directly under `ipinfo`.","wrong":"import ipinfo; client = ipinfo.Handler(...)","symbol":"Handler","correct":"from ipinfo.handler import Handler"},{"note":"The asynchronous client is in a separate submodule, `ipinfo.handler_async`, distinct from the synchronous `ipinfo.handler`.","wrong":"from ipinfo.handler import AsyncHandler","symbol":"AsyncHandler","correct":"from ipinfo.handler_async import AsyncHandler"},{"note":"The Details object, representing API response data, resides in the `ipinfo.details` submodule.","wrong":"from ipinfo import Details","symbol":"Details","correct":"from ipinfo.details import Details"}],"quickstart":{"code":"import os\nfrom ipinfo.handler import Handler\n\n# Get your IPinfo access token from environment variable or replace with your token\naccess_token = os.environ.get('IPINFO_TOKEN', 'YOUR_IPINFO_TOKEN') \n\nif not access_token or access_token == 'YOUR_IPINFO_TOKEN':\n    print(\"Warning: Please set the IPINFO_TOKEN environment variable or replace 'YOUR_IPINFO_TOKEN' with your actual token.\")\nelse:\n    client = Handler(access_token)\n    \n    # Lookup your own IP address\n    my_ip_details = client.getDetails()\n    print(f\"My IP: {my_ip_details.ip}\")\n    print(f\"My city: {my_ip_details.city}, {my_ip_details.country_name}\")\n    \n    # Lookup a specific IP address\n    google_dns_ip = '8.8.8.8'\n    google_details = client.getDetails(google_dns_ip)\n    print(f\"\\nGoogle DNS IP: {google_details.ip}\")\n    print(f\"Google DNS ISP: {google_details.org}\")","lang":"python","description":"This quickstart demonstrates how to initialize the synchronous IPinfo client and perform lookups for your own IP address and a specific IP address. Ensure your IPinfo access token is provided either via an environment variable or directly in the code."},"warnings":[{"fix":"For asynchronous operations, ensure you import `AsyncHandler` from `ipinfo.handler_async` and use `await` with its methods. Do not mix sync and async clients/methods.","message":"Version 4.0.0 introduced separate synchronous (`Handler`) and asynchronous (`AsyncHandler`) clients. Code written for older versions using an `async` approach might need to be updated to explicitly use `AsyncHandler` and `await` calls.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review the documentation for `getBatchDetails` and adjust existing batch processing logic to leverage the new options for optimal performance and error handling, especially for large lists of IPs.","message":"Batch operation behavior changed significantly in version 4.1.0. `getBatchDetails` now internally chunks large lists of IP addresses and has new options for `batch_size`, `timeout_per_batch`, `timeout_total`, and `raise_on_fail`.","severity":"gotcha","affected_versions":">=4.1.0"},{"fix":"Consider custom cache implementation (e.g., Redis, disk-based) for production environments or configure the existing cache `ttl` and `maxsize` parameters when initializing the client.","message":"The default cache is in-memory and has a finite TTL. For long-running applications or applications requiring persistent caching, implement a custom cache handler using `ipinfo.cache.CacheInterface` or configure the existing cache appropriately to avoid excessive API calls and rate limits.","severity":"gotcha","affected_versions":"all"},{"fix":"Always gracefully handle potentially missing or new fields in the `Details` object, especially when accessing new features or migrating to a higher API tier. Refer to the official IPinfo API documentation for the latest data structures.","message":"Version 5.3.0 added support for IPinfo Core and Plus API features. While this is an enhancement, users relying on specific data structures or field availability from previous API versions might encounter new or slightly altered fields in the `Details` object.","severity":"gotcha","affected_versions":">=5.3.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you are using the correct client type for your desired operation. For async operations, use `AsyncHandler` and `await client.getDetails_async()`. For sync, use `Handler` and `client.getDetails()`.","cause":"Attempting to call a synchronous method (`getDetails`) on an `AsyncHandler` instance, or vice-versa.","error":"AttributeError: 'AsyncHandler' object has no attribute 'getDetails'"},{"fix":"Pass your IPinfo API access token as the first argument when creating a client instance: `client = Handler('YOUR_ACCESS_TOKEN')` or ensure the `IPINFO_TOKEN` environment variable is set.","cause":"The `Handler` or `AsyncHandler` client was initialized without providing the required `access_token`.","error":"TypeError: __init__() missing 1 required positional argument: 'access_token'"},{"fix":"Verify that your IPinfo access token is correct, has not expired, and has the necessary permissions. Regenerate if necessary from your IPinfo dashboard.","cause":"The provided access token is invalid or expired, leading to an API authentication failure.","error":"ipinfo.exceptions.APIError: Bad token"},{"fix":"You `await` the *methods* of the `AsyncHandler` instance, not the instance itself. For example: `details = await client.getDetails()`.","cause":"Trying to `await` the `AsyncHandler` class itself instead of an awaited method call, or calling an async method without `await`.","error":"TypeError: object AsyncHandler can't be used in 'await' expression"}]}