You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is the official Python client library for the [IPinfo.io](https://ipinfo.io) IP address API, allowing you to lookup your own IP address, or get any of the following details for an IP:
4
-
- IP geolocation (city, region, country, postal code, latitude and longitude)
5
-
- ASN details (ISP or network operator, associated domain name, and type, such as business, hosting or company)
6
-
- Company details (the name and domain of the business that uses the IP address)
7
-
- Carrier details (the name of the mobile carrier and MNC and MCC for that carrier if the IP is used exclusively for mobile traffic)
8
4
5
+
- IP geolocation (city, region, country, postal code, latitude and longitude)
6
+
- ASN details (ISP or network operator, associated domain name, and type, such as business, hosting or company)
7
+
- Company details (the name and domain of the business that uses the IP address)
8
+
- Carrier details (the name of the mobile carrier and MNC and MCC for that carrier if the IP is used exclusively for mobile traffic)
9
9
10
-
###Getting Started
10
+
## Getting Started
11
11
12
12
You'll need an IPinfo API access token, which you can get by singing up for a free account at [https://ipinfo.io/signup](https://ipinfo.io/signup?ref=lib-Python).
13
13
14
14
The free plan is limited to 1,000 requests a day, and doesn't include some of the data fields such as IP type and company data. To enable all the data fields and additional request volumes see [https://ipinfo.io/pricing](https://ipinfo.io/pricing?ref=lib-Python)
The `Handler.getDetails()` method accepts an IP address as an optional, positional argument. If no IP address is specified, the API will return data for the IP address from which it receives the request.
36
39
37
40
```python
38
-
import ipinfo
39
-
40
-
access_token ='123456789abc'
41
-
handler = ipinfo.getHandler(access_token)
42
-
details = handler.getDetails()
43
-
print(details.city) # Emeryville
44
-
print(details.loc) # 37.8342,-122.2900
41
+
>>>import ipinfo
42
+
>>> access_token ='123456789abc'
43
+
>>> handler = ipinfo.getHandler(access_token)
44
+
>>> details = handler.getDetails()
45
+
>>> details.city
46
+
Emeryville
47
+
>>> details.loc
48
+
37.8342,-122.2900
45
49
```
46
50
47
-
####Authentication
51
+
### Authentication
48
52
49
53
The IPinfo library can be authenticated with your IPinfo API token, which is passed in as a positional argument. It also works without an authentication token, but in a more limited capacity.
`handler.getDetails()` will return a `Details` object that contains all fields listed in the [IPinfo developer docs](https://ipinfo.io/developers/responses#full-response) with a few minor additions. Properties can be accessed directly.
60
63
61
-
```
64
+
```python
62
65
>>> details.hostname
63
66
cpe-104-175-221-247.socal.res.rr.com
64
67
```
65
68
66
-
##### Country Name
67
-
69
+
#### Country Name
68
70
69
71
`details.country_name` will return the country name, as supplied by the `countries.json` file. See below for instructions on changing that file for use with non-English languages. `details.country` will still return country code.
70
72
71
-
```
73
+
```python
72
74
>>> details.country
73
75
US
74
76
>>> details.country_name
75
77
United States
76
78
```
77
79
78
-
#### IP Address
79
-
80
+
### IP Address
80
81
81
82
`details.ip_address` will return the an `ipaddress` object from the [Python Standard Library](https://docs.python.org/3/library/ipaddress.html). `details.ip` will still return a string.
82
83
83
-
```
84
+
```python
84
85
>>> details.ip
85
86
104.175.221.247
86
87
>>>type(details.ip)
@@ -91,12 +92,11 @@ United States
91
92
<class'ipaddress.IPv4Address'>
92
93
```
93
94
94
-
##### Longitude and Latitude
95
-
95
+
#### Longitude and Latitude
96
96
97
97
`details.latitude` and `details.longitude` will return latitude and longitude, respectively, as strings. `details.loc` will still return a composite string of both values.
98
98
99
-
```
99
+
```python
100
100
>>> details.loc
101
101
34.0293,-118.3570
102
102
>>> details.latitude
@@ -105,11 +105,11 @@ United States
105
105
-118.3570
106
106
```
107
107
108
-
#####Accessing all properties
108
+
#### Accessing all properties
109
109
110
110
`details.all` will return all details data as a dictionary.
111
111
112
-
```
112
+
```python
113
113
>>> details.all
114
114
{
115
115
'asn': { 'asn': 'AS20001',
@@ -135,24 +135,23 @@ United States
135
135
}
136
136
```
137
137
138
-
####Caching
138
+
### Caching
139
139
140
140
In-memory caching of `details` data is provided by default via the [cachetools](https://cachetools.readthedocs.io/en/latest/) library. This uses an LRU (least recently used) cache with a TTL (time to live) by default. This means that values will be cached for the specified duration; if the cache's max size is reached, cache values will be invalidated as necessary, starting with the oldest cached value.
141
141
142
-
#####Modifying cache options
142
+
#### Modifying cache options
143
143
144
144
Cache behavior can be modified by setting the `cache_options` keyword argument. `cache_options` is a dictionary in which the keys are keyword arguments specified in the `cachetools` library. The nesting of keyword arguments is to prevent name collisions between this library and its dependencies.
145
145
146
-
* Default maximum cache size: 4096 (multiples of 2 are recommended to increase efficiency)
147
-
* Default TTL: 24 hours (in seconds)
146
+
- Default maximum cache size: 4096 (multiples of 2 are recommended to increase efficiency)
It's possible to use a custom cache by creating a child class of the [CacheInterface](https://github.com/ipinfo/python/blob/master/ipinfo/cache/interface.py) class and passing this into the handler object with the `cache` keyword argument. FYI this is known as [the Strategy Pattern](https://sourcemaking.com/design_patterns/strategy).
158
157
@@ -166,18 +165,17 @@ class MyCustomCache(CacheInterface):
Request behavior can be modified by setting the `request_options` keyword argument. `request_options` is a dictionary in which the keys are keyword arguments specified in the `requests` library. The nesting of keyword arguments is to prevent name collisions between this library and its dependencies.
When looking up an IP address, the response object includes a `details.country_name` attribute which includes the country name based on American English. It is possible to return the country name in other languages by setting the `countries_file` keyword argument when creating the `IPinfo` object.
183
181
@@ -193,11 +191,11 @@ The file must be a `.json` file with the following structure:
193
191
}
194
192
```
195
193
196
-
###Other Libraries
194
+
## Other Libraries
197
195
198
196
There are official IPinfo client libraries available for many languages including PHP, Go, Java, Ruby, and many popular frameworks such as Django, Rails and Laravel. There are also many third party libraries and integrations available for our API.
199
197
200
-
###About IPinfo
198
+
## About IPinfo
201
199
202
200
Founded in 2013, IPinfo prides itself on being the most reliable, accurate, and in-depth source of IP address data available anywhere. We process terabytes of data to produce our custom IP geolocation, company, carrier and IP type data sets. Our API handles over 12 billion requests a month for 100,000 businesses and developers.
0 commit comments