0
# IPInfo Python Client Library
1
2
A comprehensive Python client library for the IPinfo.io IP address API, enabling developers to perform IP geolocation lookups and retrieve detailed information about IP addresses including geographic location, ASN details, firmographics data, and carrier information.
3
4
## Package Information
5
6
- **Package Name**: ipinfo
7
- **Language**: Python
8
- **Installation**: `pip install ipinfo`
9
10
## Core Imports
11
12
```python
13
import ipinfo
14
```
15
16
For direct class access:
17
18
```python
19
from ipinfo import Handler, HandlerLite, AsyncHandler, AsyncHandlerLite
20
from ipinfo.details import Details
21
from ipinfo.exceptions import RequestQuotaExceededError, TimeoutExceededError
22
from ipinfo.error import APIError
23
```
24
25
## Basic Usage
26
27
```python
28
import ipinfo
29
30
# Initialize handler with API token
31
access_token = '123456789abc'
32
handler = ipinfo.getHandler(access_token)
33
34
# Get details for specific IP
35
ip_address = '216.239.36.21'
36
details = handler.getDetails(ip_address)
37
38
# Access individual fields
39
print(details.city) # 'Mountain View'
40
print(details.country) # 'US'
41
print(details.loc) # '37.3861,-122.0840'
42
print(details.latitude) # '37.3861'
43
print(details.longitude) # '-122.0840'
44
45
# Get all details as dictionary
46
print(details.all)
47
48
# Get details for current IP (omit ip_address parameter)
49
my_details = handler.getDetails()
50
```
51
52
## Architecture
53
54
The library provides four main handler classes organized by API type and synchronization model:
55
56
- **Handler/HandlerLite**: Synchronous clients for Core API and Lite API respectively
57
- **AsyncHandler/AsyncHandlerLite**: Asynchronous clients for Core API and Lite API respectively
58
- **Details**: Response object providing attribute-based access to IP information
59
- **Cache System**: Pluggable caching interface with default LRU implementation
60
- **Utilities**: Helper functions for formatting, validation, and configuration
61
62
All handlers support comprehensive configuration including custom caching, timeouts, headers, and internationalization options.
63
64
## Capabilities
65
66
### Synchronous Handlers
67
68
Primary synchronous API clients for IP lookups supporting both Core API and Lite API endpoints with comprehensive caching, batch operations, and extensive configuration options.
69
70
```python { .api }
71
def getHandler(access_token=None, **kwargs): ...
72
def getHandlerLite(access_token=None, **kwargs): ...
73
74
class Handler:
75
def __init__(self, access_token=None, **kwargs): ...
76
def getDetails(self, ip_address=None, timeout=None): ...
77
def getBatchDetails(self, ip_addresses, batch_size=None, timeout_per_batch=5, timeout_total=None, raise_on_fail=True): ...
78
def getBatchDetailsIter(self, ip_addresses, batch_size=None, raise_on_fail=True): ...
79
def getMap(self, ips): ...
80
81
class HandlerLite:
82
def __init__(self, access_token=None, **kwargs): ...
83
def getDetails(self, ip_address=None, timeout=None): ...
84
```
85
86
[Synchronous Handlers](./sync-handlers.md)
87
88
### Asynchronous Handlers
89
90
Asynchronous API clients providing concurrent IP lookups with aiohttp-based implementation, supporting both Core API and Lite API endpoints with advanced timeout controls and batch processing.
91
92
```python { .api }
93
def getHandlerAsync(access_token=None, **kwargs): ...
94
def getHandlerAsyncLite(access_token=None, **kwargs): ...
95
96
class AsyncHandler:
97
def __init__(self, access_token=None, **kwargs): ...
98
async def init(self): ...
99
async def deinit(self): ...
100
async def getDetails(self, ip_address=None, timeout=None): ...
101
async def getBatchDetails(self, ip_addresses, batch_size=None, timeout_per_batch=5, timeout_total=None, raise_on_fail=True): ...
102
async def getBatchDetailsIter(self, ip_addresses, batch_size=None, raise_on_fail=True): ...
103
104
class AsyncHandlerLite:
105
def __init__(self, access_token=None, **kwargs): ...
106
async def init(self): ...
107
async def deinit(self): ...
108
async def getDetails(self, ip_address=None, timeout=None): ...
109
```
110
111
[Asynchronous Handlers](./async-handlers.md)
112
113
### Data Structures and Utilities
114
115
Response objects, caching system, exception handling, and utility functions for data formatting, validation, and configuration management.
116
117
```python { .api }
118
class Details:
119
def __init__(self, details): ...
120
def __getattr__(self, attr): ...
121
@property
122
def all(self): ...
123
124
class RequestQuotaExceededError(Exception): ...
125
class TimeoutExceededError(Exception): ...
126
class APIError(Exception):
127
def __init__(self, error_code, error_json): ...
128
129
from ipinfo.cache.interface import CacheInterface
130
from ipinfo.cache.default import DefaultCache
131
```
132
133
[Data Structures and Utilities](./data-utilities.md)
134
135
## Types
136
137
```python { .api }
138
# Configuration options for handlers
139
HandlerKwargs = {
140
'countries': dict, # Custom country name mappings
141
'eu_countries': list, # Custom EU country list
142
'countries_flags': dict, # Custom country flag mappings
143
'countries_currencies': dict, # Custom currency mappings
144
'continent': dict, # Custom continent mappings
145
'request_options': dict, # HTTP request configuration
146
'cache_options': dict, # Cache configuration
147
'cache': CacheInterface, # Custom cache implementation
148
'headers': dict # Custom HTTP headers
149
}
150
151
# Response data structure
152
IPDetails = {
153
'ip': str,
154
'hostname': str,
155
'city': str,
156
'region': str,
157
'country': str,
158
'loc': str, # "latitude,longitude"
159
'org': str,
160
'postal': str,
161
'timezone': str,
162
'country_name': str, # Added by library
163
'latitude': str, # Added by library
164
'longitude': str, # Added by library
165
'isEU': bool, # Added by library
166
'country_flag': dict, # Added by library
167
'country_currency': dict, # Added by library
168
'continent': dict # Added by library
169
}
170
```