Skip to content

Commit 6ff16b2

Browse files
ipapi-coipapi-co
authored
Update README.md
1 parent 4589629 commit 6ff16b2

File tree

1 file changed

+252
-56
lines changed

1 file changed

+252
-56
lines changed

‎README.md‎

Lines changed: 252 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,295 @@
11

2-
# Python bindings for ipapi (IP address location API)
2+
3+
# [ipapi](https://ipapi.co/) Python Library
4+
## IP Address Location | IP Lookup | IP Geolocation API
5+
### by Kloudend, Inc.
6+
7+
The ipapi Python library provides convenient access to the IP address location service from applications written in the Python language. It makes it easy to harness the potential of the IP geolocation API.
8+
9+
The service is powered by https://ipapi.co/ and owned by Kloudend, Inc.
10+
11+
## Documentation
12+
See the [ipapi API docs]([https://ipapi.co/api/?python#location-of-clients-ip](https://ipapi.co/api/?python#location-of-clients-ip))
313

414
## Installation
515

616
```
7-
pip install ipapi
17+
pip install --upgrade ipapi
818
```
919
or
10-
20+
Install from source with:
1121
```
1222
python setup.py install
1323
```
24+
### Requirements
1425

15-
## Usage
26+
Python 2.7+ or Python 3.4+ (PyPy supported)
1627

17-
### From your Python code
28+
## QuickStart
29+
```python
30+
>>> import ipapi
1831

32+
>>> ipapi.location()
33+
{
34+
"ip": "8.8.8.8",
35+
"city": "Mountain View",
36+
"country": "US",
37+
"timezone": "America/Los_Angeles",
38+
...
39+
}
1940
```
41+
42+
## Usage : As an IP Location library
43+
44+
```python
2045
import ipapi
21-
ipapi.location(ip=None, key=None, field=None)
46+
47+
ipapi.location(ip, key, output)
2248
```
49+
|Argument|Description |
50+
|--|--|
51+
|`ip`| IP Address that you wish to locate.<br>If omitted, it defaults to the your machine's IP |
52+
|`key`| API key (for paid plans).<br>Omit it or set key=`None` for usage under [free IP Location]([https://ipapi.co/free/](https://ipapi.co/free/)) tier. |
53+
|`output`| The desired output from the API. <br>For complete IP location object, valid values are `json`, `csv`, `xml`, `yaml`.<br>To retrieve a specific field (e.g. city, country etc. as text), valid values are [1].<br>If omitted or `None`, gets the entire location data as `json` |
2354

24-
- `ip` : use specified IP address. If omitted or `None`, use your machine's IP address
25-
- `key` : For paid plans
26-
- `field` : get specified field (ip, city, country, timezone etc.) as text. If omitted or `None`, get entire location data as `JSON`
55+
[1] Fields supported by the API : `ip`, `city`, `region`, `region_code`, `country`, `country_code`, `country_code_iso3`, `country_capital`, `country_tld`, `country_name`, `continent_code`, `in_eu`, `postal`, `latitude`, `longitude`, `timezone`, `utc_offset`, `country_calling_code`, `currency`, `currency_name`, `languages`, `country_area`, `country_population`, `latlong`, `asn`, `org`
2756

2857
#### Examples
2958

59+
1. Find the **location of your IP address** (suppose your IP is '50.1.2.3')
60+
```python
61+
>>> ipapi.location()
62+
```
63+
The output would be a `JSON` object like this :
64+
```json
65+
{
66+
"ip": "50.1.2.3",
67+
"city": "Sacramento",
68+
"region": "California",
69+
"region_code": "CA",
70+
"country": "US",
71+
"country_code": "US",
72+
"country_code_iso3": "USA",
73+
"country_capital": "Washington",
74+
"country_tld": ".us",
75+
"country_name": "United States",
76+
"continent_code": "NA",
77+
"in_eu": false,
78+
"postal": "95817",
79+
"latitude": 38.548,
80+
"longitude": -121.4597,
81+
"timezone": "America/Los_Angeles",
82+
"utc_offset": "-0700",
83+
"country_calling_code": "+1",
84+
"currency": "USD",
85+
"currency_name": "Dollar",
86+
"languages": "en-US,es-US,haw,fr",
87+
"country_area": 9629091.0,
88+
"country_population": 310232863.0,
89+
"asn": "AS7065",
90+
"org": "SONOMA"
91+
}
3092
```
31-
ipapi.location()
32-
# Gets complete location for your IP address
33-
{u'city': u'Wilton', u'ip': u'50.1.2.3', u'region': u'California', u'longitude': -121.2429, u'country': u'US', u'latitude': 38.3926, u'timezone': u'America/Los_Angeles', u'postal': u'95693'}
3493

35-
ipapi.location(None, None, 'ip')
36-
# Gets my external IP address
37-
u'50.1.2.3'
94+
2. Find the **location of an IP address**
95+
```python
96+
>>> ipapi.location(ip='8.8.8.8')
97+
```
98+
```json
99+
{
100+
"ip": "8.8.8.8",
101+
"city": "Mountain View",
102+
"region": "California",
103+
...
104+
}
105+
```
106+
You can also use an IPv6 address e.g.
107+
```python
108+
>>> ipapi.location(ip='2001:4860:1::1')
109+
```
38110

39-
ipapi.location(None, None, 'city')
40-
# Gets your city name
41-
u'Wilton'
111+
3. Find the **location of an IP address** in `xml`format (other formats :`json`, `csv`,`yaml`)
112+
```python
113+
>>> ipapi.location(ip='8.8.8.8', output='xml')
114+
```
115+
```xml
116+
'<?xml version="1.0" encoding="utf-8"?>
117+
<root>
118+
<ip>8.8.8.8</ip>
119+
<city>Mountain View</city>
120+
...
121+
</root>'
122+
```
42123

43-
ipapi.location(None, None, 'country')
44-
# Gets your country
45-
u'US'
124+
4. Find **your external IP address**
125+
```python
126+
>>> ipapi.location(output='ip')
127+
```
128+
```
129+
'50.1.2.3'
130+
```
46131

47-
ipapi.location('8.8.8.8')
48-
# Gets complete location for IP address 8.8.8.8
49-
{u'city': u'Mountain View', u'ip': u'8.8.8.8', u'region': u'California', u'longitude': -122.0838, u'country': u'US', u'latitude': 37.386, u'timezone': u'America/Los_Angeles', u'postal': u'94035'}
132+
5. Find the **city from an IP address**
133+
```python
134+
>>> ipapi.location(ip='8.8.8.8', output='city')
135+
```
136+
```
137+
'Mountain View'
138+
```
139+
6. Find the **country code from an IP address**
140+
```python
141+
>>> ipapi.location(ip='8.8.8.8', output='country_code')
142+
```
143+
```
144+
'US'
145+
```
146+
7. Find the **region of an IP address**
147+
```python
148+
>>> ipapi.location(ip='8.8.8.8', output='region_code')
149+
```
150+
```
151+
'CA'
152+
```
153+
8. Find if **IP address is located in European Union**
154+
```python
155+
>>> ipapi.location(ip='8.8.8.8', output='in_eu')
156+
```
157+
```
158+
'False'
159+
```
160+
9. Find the **latitude and longitude of an IP address**
161+
```python
162+
>>> ipapi.location(ip='1.2.3.4', output='latlong')
163+
```
164+
```
165+
'-27.473101,153.014046'
166+
```
167+
10. Find the **postal code of an IP address**
168+
```python
169+
>>> ipapi.location(ip='1.2.3.4', output='postal')
170+
```
171+
```
172+
'4101'
173+
```
174+
11. Find the **timezone of an IP address**
175+
```python
176+
>>> ipapi.location(ip='1.2.3.4', output='timezone')
177+
```
178+
```
179+
'Australia/Brisbane'
180+
```
181+
12. Find the **currency of an IP address**
182+
```python
183+
>>> ipapi.location(ip='1.2.3.4', output='currency')
184+
```
185+
```
186+
'AUD'
187+
```
188+
13. Find the **ASN of an IP address**
189+
```python
190+
>>> ipapi.location(ip='1.1.1.1', output='asn')
191+
```
192+
```
193+
'AS13335'
194+
```
195+
14. Find the **Organization of an IP address**
196+
```python
197+
>>> ipapi.location(ip='8.8.8.8', output='org')
198+
```
199+
```
200+
'GOOGLE'
201+
```
50202

51-
ipapi.location('8.8.8.8', None, 'city')
52-
# Gets city name for IP address 8.8.8.8
53-
u'Mountain View'
54203

55-
ipapi.location('8.8.8.8', None, 'country')
56-
# Gets country for IP address 8.8.8.8
57-
u'US'
58-
```
59204

205+
## Usage : As an IP Location command line utility
60206

61-
### From command line
62-
```
63-
$ python ipapi.py -i <IP address> -f <field> -k <API KEY>
207+
```bash
208+
$ python ipapi -i <IP Address> -k <API KEY> -o <Output Format>
64209
```
210+
where the options are defined above.
65211

66212
#### Examples
67213

68-
```
69-
$ python ipapi.py
70-
{u'city': u'Wilton', u'ip': u'50.1.2.3', u'region': u'California', u'longitude': -121.2429, u'country': u'US', u'latitude': 38.3926, u'timezone': u'America/Los_Angeles', u'postal': u'95693'}
214+
1. Get your IP Geolocation
215+
```bash
216+
$ python ipapi
71217

72-
$ python ipapi.py -f ip
73-
50.1.2.3
218+
```
219+
The output would be a `JSON` object like this (assuming your IP is `50.1.2.3`) :
220+
```json
221+
{
222+
"ip": "50.1.2.3",
223+
"city": "Sacramento",
224+
"region": "California",
225+
"region_code": "CA",
226+
"country": "US",
227+
"country_code": "US",
228+
"country_code_iso3": "USA",
229+
"country_capital": "Washington",
230+
"country_tld": ".us",
231+
"country_name": "United States",
232+
"continent_code": "NA",
233+
"in_eu": false,
234+
"postal": "95817",
235+
"latitude": 38.548,
236+
"longitude": -121.4597,
237+
"timezone": "America/Los_Angeles",
238+
"utc_offset": "-0700",
239+
"country_calling_code": "+1",
240+
"currency": "USD",
241+
"currency_name": "Dollar",
242+
"languages": "en-US,es-US,haw,fr",
243+
"country_area": 9629091.0,
244+
"country_population": 310232863.0,
245+
"asn": "AS7065",
246+
"org": "SONOMA"
247+
}
248+
```
249+
2. Get the geolocation of an IP address
250+
```bash
251+
$ python ipapi -i '8.8.8.8'
252+
```
253+
```json
254+
{
255+
"ip": "8.8.8.8",
256+
"city": "Mountain View",
257+
"region": "California",
258+
...
259+
}
260+
```
74261

75-
$ python ipapi.py -f city
76-
Wilton
262+
3. Get the location of an IP in `xml` format (other formats : `json`, `csv`, `yaml`)
263+
```bash
264+
$ python ipapi -i '8.8.8.8' -o xml
265+
```
77266

78-
$ python ipapi.py -i 8.8.8.8
79-
{u'city': u'Mountain View', u'ip': u'8.8.8.8', u'region': u'California', u'longitude': -122.0838, u'country': u'US', u'latitude': 37.386, u'timezone': u'America/Los_Angeles', u'postal': u'94035'}
267+
```xml
268+
'<?xml version="1.0" encoding="utf-8"?>
269+
<root>
270+
<ip>8.8.8.8</ip>
271+
<city>Mountain View</city>
272+
...
273+
</root>'
274+
```
80275

81-
$ python ipapi.py -i 8.8.8.8 -f city
82-
Mountain View
276+
4. Get your external IP address
277+
```bash
278+
$ python ipapi -o ip
279+
```
280+
```
281+
'50.1.2.3'
282+
```
83283

84-
$ python ipapi.py -i 8.8.8.8 -f country
85-
US
284+
5. Get the city of an IP address
285+
```bash
286+
$ python ipapi -i '8.8.8.8' -o city
86287
```
288+
```
289+
'Mountain View'
290+
```
291+
87292

88-
### With API Key
89293

90-
API key can be specified in the following ways :
91294

92-
1. Inside `ipapi.py` by setting `API_KEY` variable
93-
2. Via command line with the `-k` option
94-
3. As a function argument e.g. `ipapi.location(ip='8.8.8.8', key='secret-key')` or `ipapi.location(ip='8.8.8.8', key='secret-key', field='city')`
95295

96-
### Notes
97-
- All function arguments (`ip`, `key`, `field`) are optional . To skip an argument, use `None` or an empty string `''`.
98-
`ipapi.location(ip='8.8.8.8', key=None, field='city')`
99-
`ipapi.location(ip='8.8.8.8', key='', field='city')`

0 commit comments

Comments
 (0)