0
# Response Models
1
2
Structured data models representing geographic and network information returned by web services and database lookups. Models contain nested record classes for hierarchical geographic data, providing comprehensive access to location, network, and ISP information.
3
4
```python
5
import datetime
6
import ipaddress
7
from collections.abc import Sequence
8
from ipaddress import IPv4Address, IPv6Address
9
from typing import Optional, Union
10
11
import geoip2.records
12
from geoip2.types import IPAddress
13
```
14
15
## Capabilities
16
17
### Location Models
18
19
Models representing comprehensive geographic information from continent to city level, including location coordinates, postal codes, and administrative subdivisions.
20
21
#### City Model
22
23
The most comprehensive geographic model containing city-level data along with all country-level information.
24
25
```python { .api }
26
class City:
27
def __init__(self, locales: Optional[Sequence[str]], *, city: Optional[dict] = None,
28
continent: Optional[dict] = None, country: Optional[dict] = None,
29
location: Optional[dict] = None, ip_address: Optional[IPAddress] = None,
30
maxmind: Optional[dict] = None, postal: Optional[dict] = None,
31
prefix_len: Optional[int] = None, registered_country: Optional[dict] = None,
32
represented_country: Optional[dict] = None, subdivisions: Optional[list[dict]] = None,
33
traits: Optional[dict] = None, **_): ...
34
35
# Geographic records
36
continent: geoip2.records.Continent # Continent information
37
country: geoip2.records.Country # Country information
38
city: geoip2.records.City # City information
39
location: geoip2.records.Location # Coordinates and location data
40
postal: geoip2.records.Postal # Postal code information
41
subdivisions: geoip2.records.Subdivisions # State/province information
42
43
# Administrative records
44
registered_country: geoip2.records.Country # ISP registered country
45
represented_country: geoip2.records.RepresentedCountry # Military base country
46
47
# Network and account records
48
traits: geoip2.records.Traits # Network and IP characteristics
49
maxmind: geoip2.records.MaxMind # MaxMind account information
50
```
51
52
#### Country Model
53
54
Country-level geographic model containing continent and country information without city-specific details.
55
56
```python { .api }
57
class Country:
58
def __init__(self, locales: Optional[Sequence[str]], *, continent: Optional[dict] = None,
59
country: Optional[dict] = None, ip_address: Optional[IPAddress] = None,
60
maxmind: Optional[dict] = None, prefix_len: Optional[int] = None,
61
registered_country: Optional[dict] = None, represented_country: Optional[dict] = None,
62
traits: Optional[dict] = None, **_): ...
63
64
# Geographic records
65
continent: geoip2.records.Continent # Continent information
66
country: geoip2.records.Country # Country information
67
68
# Administrative records
69
registered_country: geoip2.records.Country # ISP registered country
70
represented_country: geoip2.records.RepresentedCountry # Military base country
71
72
# Network and account records
73
traits: geoip2.records.Traits # Network and IP characteristics
74
maxmind: geoip2.records.MaxMind # MaxMind account information
75
```
76
77
#### Enhanced Models
78
79
```python { .api }
80
class Insights(City):
81
"""
82
Model for GeoIP2 Insights web service.
83
Extends City with user behavior analytics and enhanced traits.
84
"""
85
86
class Enterprise(City):
87
"""
88
Model for GeoIP2 Enterprise database.
89
Extends City with confidence scores and enhanced data accuracy.
90
"""
91
```
92
93
### Network Models
94
95
Models representing network and ISP information with simplified structure focused on autonomous system and connectivity data.
96
97
#### Base Network Model
98
99
```python { .api }
100
class SimpleModel:
101
def __init__(self, ip_address: IPAddress, network: Optional[str], prefix_len: Optional[int]): ...
102
103
@property
104
def ip_address(self) -> Union[IPv4Address, IPv6Address]:
105
"""The IP address for the record."""
106
107
@property
108
def network(self) -> Optional[Union[ipaddress.IPv4Network, ipaddress.IPv6Network]]:
109
"""The network associated with the record."""
110
```
111
112
#### ASN Model
113
114
```python { .api }
115
class ASN(SimpleModel):
116
def __init__(self, ip_address: IPAddress, *, autonomous_system_number: Optional[int] = None,
117
autonomous_system_organization: Optional[str] = None, network: Optional[str] = None,
118
prefix_len: Optional[int] = None, **_): ...
119
120
autonomous_system_number: Optional[int] # ASN number
121
autonomous_system_organization: Optional[str] # ASN organization name
122
```
123
124
#### ISP Model
125
126
```python { .api }
127
class ISP(ASN):
128
def __init__(self, ip_address: IPAddress, *, autonomous_system_number: Optional[int] = None,
129
autonomous_system_organization: Optional[str] = None, isp: Optional[str] = None,
130
mobile_country_code: Optional[str] = None, mobile_network_code: Optional[str] = None,
131
organization: Optional[str] = None, network: Optional[str] = None,
132
prefix_len: Optional[int] = None, **_): ...
133
134
# Inherits ASN fields plus:
135
isp: Optional[str] # ISP name
136
mobile_country_code: Optional[str] # Mobile country code (MCC)
137
mobile_network_code: Optional[str] # Mobile network code (MNC)
138
organization: Optional[str] # Organization name
139
```
140
141
#### Connection Type Model
142
143
```python { .api }
144
class ConnectionType(SimpleModel):
145
def __init__(self, ip_address: IPAddress, *, connection_type: Optional[str] = None,
146
network: Optional[str] = None, prefix_len: Optional[int] = None, **_): ...
147
148
connection_type: Optional[str] # 'Dialup', 'Cable/DSL', 'Corporate', 'Cellular', 'Satellite'
149
```
150
151
#### Domain Model
152
153
```python { .api }
154
class Domain(SimpleModel):
155
def __init__(self, ip_address: IPAddress, *, domain: Optional[str] = None,
156
network: Optional[str] = None, prefix_len: Optional[int] = None, **_): ...
157
158
domain: Optional[str] # Domain associated with IP
159
```
160
161
### Anonymous IP Models
162
163
Models for detecting and classifying anonymous networks, VPNs, proxies, and other privacy-focused services.
164
165
#### Anonymous IP Model
166
167
```python { .api }
168
class AnonymousIP(SimpleModel):
169
def __init__(self, ip_address: IPAddress, *, is_anonymous: bool = False,
170
is_anonymous_vpn: bool = False, is_hosting_provider: bool = False,
171
is_public_proxy: bool = False, is_residential_proxy: bool = False,
172
is_tor_exit_node: bool = False, network: Optional[str] = None,
173
prefix_len: Optional[int] = None, **_): ...
174
175
is_anonymous: bool # Belongs to any anonymous network
176
is_anonymous_vpn: bool # Registered to anonymous VPN provider
177
is_hosting_provider: bool # Belongs to hosting or VPN provider
178
is_public_proxy: bool # Belongs to public proxy
179
is_residential_proxy: bool # Residential ISP anonymizing network
180
is_tor_exit_node: bool # Tor exit node
181
```
182
183
#### Anonymous Plus Model
184
185
```python { .api }
186
class AnonymousPlus(AnonymousIP):
187
def __init__(self, ip_address: IPAddress, *, anonymizer_confidence: Optional[int] = None,
188
is_anonymous: bool = False, is_anonymous_vpn: bool = False,
189
is_hosting_provider: bool = False, is_public_proxy: bool = False,
190
is_residential_proxy: bool = False, is_tor_exit_node: bool = False,
191
network: Optional[str] = None, network_last_seen: Optional[str] = None,
192
prefix_len: Optional[int] = None, provider_name: Optional[str] = None, **_): ...
193
194
# Inherits AnonymousIP fields plus:
195
anonymizer_confidence: Optional[int] # Confidence score 1-99 for active VPN service
196
network_last_seen: Optional[datetime.date] # Last day network was seen in analysis
197
provider_name: Optional[str] # VPN provider name (e.g., 'NordVPN')
198
```
199
200
## Record Classes
201
202
Detailed record classes containing the actual data within model objects, organized hierarchically from continent to city level.
203
204
### Geographic Records
205
206
```python { .api }
207
class Continent:
208
def __init__(self, locales: Optional[Sequence[str]], *, code: Optional[str] = None,
209
geoname_id: Optional[int] = None, names: Optional[dict[str, str]] = None, **_): ...
210
211
code: Optional[str] # Two-character continent code ('NA', 'EU', etc.)
212
geoname_id: Optional[int] # GeoNames database ID
213
names: dict[str, str] # Localized names by language code
214
name: Optional[str] # Name in preferred locale
215
216
class Country:
217
def __init__(self, locales: Optional[Sequence[str]], *, confidence: Optional[int] = None,
218
geoname_id: Optional[int] = None, is_in_european_union: bool = False,
219
iso_code: Optional[str] = None, names: Optional[dict[str, str]] = None, **_): ...
220
221
confidence: Optional[int] # Confidence 0-100 (Insights/Enterprise only)
222
geoname_id: Optional[int] # GeoNames database ID
223
is_in_european_union: bool # EU membership status
224
iso_code: Optional[str] # ISO 3166-1 alpha-2 country code
225
names: dict[str, str] # Localized names by language code
226
name: Optional[str] # Name in preferred locale
227
228
class City:
229
def __init__(self, locales: Optional[Sequence[str]], *, confidence: Optional[int] = None,
230
geoname_id: Optional[int] = None, names: Optional[dict[str, str]] = None, **_): ...
231
232
confidence: Optional[int] # Confidence 0-100 (Insights/Enterprise only)
233
geoname_id: Optional[int] # GeoNames database ID
234
names: dict[str, str] # Localized names by language code
235
name: Optional[str] # Name in preferred locale
236
237
class Subdivision:
238
def __init__(self, locales: Optional[Sequence[str]], *, confidence: Optional[int] = None,
239
geoname_id: Optional[int] = None, iso_code: Optional[str] = None,
240
names: Optional[dict[str, str]] = None, **_): ...
241
242
confidence: Optional[int] # Confidence 0-100 (Insights/Enterprise only)
243
geoname_id: Optional[int] # GeoNames database ID
244
iso_code: Optional[str] # ISO 3166-2 subdivision code
245
names: dict[str, str] # Localized names by language code
246
name: Optional[str] # Name in preferred locale
247
248
class Subdivisions(tuple):
249
"""
250
Tuple-like collection of subdivisions from largest to smallest.
251
For UK address, England would be first, Oxfordshire second.
252
"""
253
254
@property
255
def most_specific(self) -> Subdivision:
256
"""The most specific (smallest) subdivision available."""
257
```
258
259
### Location and Infrastructure Records
260
261
```python { .api }
262
class Location:
263
def __init__(self, *, average_income: Optional[int] = None, accuracy_radius: Optional[int] = None,
264
latitude: Optional[float] = None, longitude: Optional[float] = None,
265
metro_code: Optional[int] = None, population_density: Optional[int] = None,
266
time_zone: Optional[str] = None, **_): ...
267
268
average_income: Optional[int] # Average income in USD (Insights only)
269
accuracy_radius: Optional[int] # Accuracy radius in kilometers
270
latitude: Optional[float] # Approximate latitude
271
longitude: Optional[float] # Approximate longitude
272
metro_code: Optional[int] # Metro code (deprecated)
273
population_density: Optional[int] # Population per sq km (Insights only)
274
time_zone: Optional[str] # IANA time zone
275
276
class Postal:
277
def __init__(self, *, code: Optional[str] = None, confidence: Optional[int] = None, **_): ...
278
279
code: Optional[str] # Postal code
280
confidence: Optional[int] # Confidence 0-100 (Insights/Enterprise only)
281
282
class MaxMind:
283
def __init__(self, *, queries_remaining: Optional[int] = None, **_): ...
284
285
queries_remaining: Optional[int] # Remaining queries for account
286
```
287
288
### Network Traits Record
289
290
Comprehensive network characteristics and user behavior data.
291
292
```python { .api }
293
class Traits:
294
def __init__(self, *, autonomous_system_number: Optional[int] = None,
295
autonomous_system_organization: Optional[str] = None, connection_type: Optional[str] = None,
296
domain: Optional[str] = None, is_anonymous: bool = False, is_anonymous_proxy: bool = False,
297
is_anonymous_vpn: bool = False, is_hosting_provider: bool = False,
298
is_legitimate_proxy: bool = False, is_public_proxy: bool = False,
299
is_residential_proxy: bool = False, is_satellite_provider: bool = False,
300
is_tor_exit_node: bool = False, isp: Optional[str] = None,
301
ip_address: Optional[str] = None, network: Optional[str] = None,
302
organization: Optional[str] = None, prefix_len: Optional[int] = None,
303
static_ip_score: Optional[float] = None, user_count: Optional[int] = None,
304
user_type: Optional[str] = None, mobile_country_code: Optional[str] = None,
305
mobile_network_code: Optional[str] = None, is_anycast: bool = False, **_): ...
306
307
# Network identification
308
autonomous_system_number: Optional[int] # ASN number
309
autonomous_system_organization: Optional[str] # ASN organization
310
connection_type: Optional[str] # Connection type
311
domain: Optional[str] # Associated domain
312
isp: Optional[str] # ISP name
313
organization: Optional[str] # Organization name
314
315
# Anonymity flags
316
is_anonymous: bool # Any anonymous network
317
is_anonymous_proxy: bool # Anonymous proxy (deprecated)
318
is_anonymous_vpn: bool # Anonymous VPN provider
319
is_anycast: bool # Anycast network
320
is_hosting_provider: bool # Hosting/VPN provider
321
is_legitimate_proxy: bool # Corporate VPN/proxy
322
is_public_proxy: bool # Public proxy
323
is_residential_proxy: bool # Residential anonymizing network
324
is_satellite_provider: bool # Satellite provider (deprecated)
325
is_tor_exit_node: bool # Tor exit node
326
327
# Mobile network
328
mobile_country_code: Optional[str] # Mobile country code (MCC)
329
mobile_network_code: Optional[str] # Mobile network code (MNC)
330
331
# User behavior (Insights only)
332
static_ip_score: Optional[float] # Static IP score 0-99.99
333
user_count: Optional[int] # Estimated users sharing IP (24hr)
334
user_type: Optional[str] # User classification
335
336
# Network properties
337
@property
338
def ip_address(self) -> Optional[Union[IPv4Address, IPv6Address]]:
339
"""The IP address that the data is for."""
340
341
@property
342
def network(self) -> Optional[Union[ipaddress.IPv4Network, ipaddress.IPv6Network]]:
343
"""The network associated with the record."""
344
```
345
346
## Usage Examples
347
348
### Accessing Geographic Data
349
350
```python
351
response = client.city('203.0.113.0')
352
353
# Continent information
354
print(f"Continent: {response.continent.name} ({response.continent.code})")
355
356
# Country information
357
print(f"Country: {response.country.name} ({response.country.iso_code})")
358
print(f"EU Member: {response.country.is_in_european_union}")
359
360
# Subdivision (state/province) information
361
most_specific = response.subdivisions.most_specific
362
print(f"Subdivision: {most_specific.name} ({most_specific.iso_code})")
363
364
# City information
365
print(f"City: {response.city.name}")
366
367
# Location coordinates
368
print(f"Lat/Lon: {response.location.latitude}, {response.location.longitude}")
369
print(f"Time Zone: {response.location.time_zone}")
370
371
# Postal code
372
print(f"Postal: {response.postal.code}")
373
```
374
375
### Accessing Network Information
376
377
```python
378
# From City/Country response traits
379
print(f"ASN: {response.traits.autonomous_system_number}")
380
print(f"ISP: {response.traits.isp}")
381
print(f"Connection: {response.traits.connection_type}")
382
print(f"Network: {response.traits.network}")
383
384
# From dedicated ASN lookup
385
asn_response = reader.asn('203.0.113.0')
386
print(f"ASN: {asn_response.autonomous_system_number}")
387
print(f"Org: {asn_response.autonomous_system_organization}")
388
```
389
390
### Accessing Anonymity Information
391
392
```python
393
anon_response = reader.anonymous_ip('203.0.113.0')
394
395
print(f"Anonymous: {anon_response.is_anonymous}")
396
print(f"VPN: {anon_response.is_anonymous_vpn}")
397
print(f"Tor: {anon_response.is_tor_exit_node}")
398
print(f"Hosting: {anon_response.is_hosting_provider}")
399
```
400
401
### Working with Localized Names
402
403
```python
404
# Using multiple locales
405
with Client(42, 'key', locales=['es', 'en']) as client:
406
response = client.country('203.0.113.0')
407
408
# All available names
409
print(response.country.names) # {'en': 'United States', 'es': 'Estados Unidos', ...}
410
411
# Name in preferred locale (Spanish first, English fallback)
412
print(response.country.name) # 'Estados Unidos'
413
```
414
415
## Types
416
417
```python { .api }
418
IPAddress = Union[str, IPv6Address, IPv4Address]
419
```