IPinfo Python Library

5.5.0 · active · verified Thu Apr 16

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.

Common errors

```
AttributeError: 'AsyncHandler' object has no attribute 'getDetails'
```
cause Attempting to call a synchronous method (`getDetails`) on an `AsyncHandler` instance, or vice-versa.

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()`.
```
TypeError: __init__() missing 1 required positional argument: 'access_token'
```
cause The `Handler` or `AsyncHandler` client was initialized without providing the required `access_token`.

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.
```
ipinfo.exceptions.APIError: Bad token
```
cause The provided access token is invalid or expired, leading to an API authentication failure.

fix Verify that your IPinfo access token is correct, has not expired, and has the necessary permissions. Regenerate if necessary from your IPinfo dashboard.
```
TypeError: object AsyncHandler can't be used in 'await' expression
```
cause Trying to `await` the `AsyncHandler` class itself instead of an awaited method call, or calling an async method without `await`.

fix You `await` the *methods* of the `AsyncHandler` instance, not the instance itself. For example: `details = await client.getDetails()`.

Warnings

breaking 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.
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.
gotcha 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`.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install ipinfo Install stable version

Imports

Handler
wrong:
```
import ipinfo; client = ipinfo.Handler(...)
```
correct:
```
from ipinfo.handler import Handler
```
The Handler class is located in the `ipinfo.handler` submodule, not directly under `ipinfo`.
AsyncHandler
wrong:
```
from ipinfo.handler import AsyncHandler
```
correct:
```
from ipinfo.handler_async import AsyncHandler
```
The asynchronous client is in a separate submodule, `ipinfo.handler_async`, distinct from the synchronous `ipinfo.handler`.
Details
wrong:
```
from ipinfo import Details
```
correct:
```
from ipinfo.details import Details
```
The Details object, representing API response data, resides in the `ipinfo.details` submodule.

Quickstart

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.

import os
from ipinfo.handler import Handler

# Get your IPinfo access token from environment variable or replace with your token
access_token = os.environ.get('IPINFO_TOKEN', 'YOUR_IPINFO_TOKEN') 

if not access_token or access_token == 'YOUR_IPINFO_TOKEN':
    print("Warning: Please set the IPINFO_TOKEN environment variable or replace 'YOUR_IPINFO_TOKEN' with your actual token.")
else:
    client = Handler(access_token)
    
    # Lookup your own IP address
    my_ip_details = client.getDetails()
    print(f"My IP: {my_ip_details.ip}")
    print(f"My city: {my_ip_details.city}, {my_ip_details.country_name}")
    
    # Lookup a specific IP address
    google_dns_ip = '8.8.8.8'
    google_details = client.getDetails(google_dns_ip)
    print(f"\nGoogle DNS IP: {google_details.ip}")
    print(f"Google DNS ISP: {google_details.org}")

view raw JSON →