Getting Started

This is a Python client and command line interface (CLI) for the ipdata.co IP Geolocation API. ipdata offers a fast, highly-available API to enrich IP Addresses with Location, Company, Threat Intelligence and numerous other data attributes.

Note you need an API Key to access the API. To get a key on the 1500 requests a day free tier, Sign up here . If you need higher volume then Sign up for a paid plan.

Visit our Documentation for more examples and tutorials.

Installation

pip install ipdata

Library Usage

Looking Up the Calling IP Address

from ipdata import ipdata
from pprint import pprint
# Create an instance of an ipdata object. Replace `test` with your API Key
ipdata = ipdata.IPData('test')
response = ipdata.lookup()
pprint(response)

Looking Up any IP Address

from ipdata import ipdata
from pprint import pprint
# Create an instance of an ipdata object. Replace `test` with your API Key
ipdata = ipdata.IPData('test')
response = ipdata.lookup('69.78.70.144')
pprint(response)

Sample Response

{'asn': 'AS6167',
 'calling_code': '1',
 'carrier': {'mcc': '310', 'mnc': '004', 'name': 'Verizon'},
 'city': 'Farmersville',
 'continent_code': 'NA',
 'continent_name': 'North America',
 'count': '1506',
 'country_code': 'US',
 'country_name': 'United States',
 'currency': {'code': 'USD',
              'name': 'US Dollar',
              'native': '$',
              'plural': 'US dollars',
              'symbol': '$'},
 'emoji_flag': '🇺🇸',
 'emoji_unicode': 'U+1F1FA U+1F1F8',
 'flag': 'https://ipdata.co/flags/us.png',
 'ip': '69.78.70.144',
 'is_eu': False,
 'languages': [{'name': 'English', 'native': 'English'}],
 'latitude': 33.1659,
 'longitude': -96.3686,
 'organisation': 'Cellco Partnership DBA Verizon Wireless',
 'postal': '75442',
 'region': 'Texas',
 'region_code': 'TX',
 'status': 200,
 'threat': {'is_anonymous': False,
            'is_bogon': False,
            'is_known_abuser': False,
            'is_known_attacker': False,
            'is_proxy': False,
            'is_threat': False,
            'is_tor': False},
 'time_zone': {'abbr': 'CDT',
               'current_time': '2019-04-28T17:56:59.246755-05:00',
               'is_dst': True,
               'name': 'America/Chicago',
               'offset': '-0500'}}

Getting only one field

from ipdata import ipdata
from pprint import pprint
# Create an instance of an ipdata object. Replace `test` with your API Key
ipdata = ipdata.IPData('test')
response = ipdata.lookup('8.8.8.8', select_field='organisation')
pprint(response)

Response

{'organisation': 'Google LLC', 'status': 200}

Getting a number of specific fields

from ipdata import ipdata
from pprint import pprint
# Create an instance of an ipdata object. Replace `test` with your API Key
ipdata = ipdata.IPData('test')
response = ipdata.lookup('8.8.8.8',fields=['ip','organisation','country_name'])
pprint(response)

Response

{'country_name': 'United States',
 'ip': '8.8.8.8',
 'organisation': 'Google LLC',
 'status': 200}

Bulk Lookups

from ipdata import ipdata
from pprint import pprint
# Create an instance of an ipdata object. Replace `test` with your API Key
ipdata = ipdata.IPData('test')
response = ipdata.bulk_lookup(['8.8.8.8','1.1.1.1'])
pprint(response)

Sample Response

{'responses': [{'asn': 'AS15169',
               'calling_code': '1',
               'city': None,
               'continent_code': 'NA',
               'continent_name': 'North America',
               'count': '1506',
               'country_code': 'US',
               'country_name': 'United States',
               'currency': {'code': 'USD',
                            'name': 'US Dollar',
                            'native': '$',
                            'plural': 'US dollars',
                            'symbol': '$'},
               'emoji_flag': '🇺🇸',
               'emoji_unicode': 'U+1F1FA U+1F1F8',
               'flag': 'https://ipdata.co/flags/us.png',
               'ip': '8.8.8.8',
               'is_eu': False,
               'languages': [{'name': 'English', 'native': 'English'}],
               'latitude': 37.751,
               'longitude': -97.822,
               'organisation': 'Google LLC',
               'postal': None,
               'region': None,
               'region_code': None,
               'threat': {'is_anonymous': False,
                          'is_bogon': False,
                          'is_known_abuser': False,
                          'is_known_attacker': False,
                          'is_proxy': False,
                          'is_threat': False,
                          'is_tor': False},
               'time_zone': {'abbr': 'CDT',
                             'current_time': '2019-04-28T18:02:48.035425-05:00',
                             'is_dst': True,
                             'name': 'America/Chicago',
                             'offset': '-0500'}},
              {'asn': 'AS13335',
               'calling_code': '61',
               'city': None,
               'continent_code': 'OC',
               'continent_name': 'Oceania',
               'count': '1506',
               'country_code': 'AU',
               'country_name': 'Australia',
               'currency': {'code': 'AUD',
                            'name': 'Australian Dollar',
                            'native': '$',
                            'plural': 'Australian dollars',
                            'symbol': 'AU$'},
               'emoji_flag': '🇦🇺',
               'emoji_unicode': 'U+1F1E6 U+1F1FA',
               'flag': 'https://ipdata.co/flags/au.png',
               'ip': '1.1.1.1',
               'is_eu': False,
               'languages': [{'name': 'English', 'native': 'English'}],
               'latitude': -33.494,
               'longitude': 143.2104,
               'organisation': 'Cloudflare, Inc.',
               'postal': None,
               'region': None,
               'region_code': None,
               'threat': {'is_anonymous': False,
                          'is_bogon': False,
                          'is_known_abuser': False,
                          'is_known_attacker': False,
                          'is_proxy': False,
                          'is_threat': False,
                          'is_tor': False},
               'time_zone': {'abbr': 'AEST',
                             'current_time': '2019-04-29T09:02:48.036287+10:00',
                             'is_dst': False,
                             'name': 'Australia/Sydney',
                             'offset': '+1000'}}],
 'status': 200}

Using the ipdata CLI

Usage: ipdata [OPTIONS] COMMAND [ARGS]...

Options: --api-key TEXT IPData API Key

Commands: batch info init me

Initialize the cli with your API Key

ipdata init <API Key>

You may also pass the --api-key <API Key> parameter to any command to specify a different API Key.

Lookup your own IP address

ipdata

ipdata me

Look up an arbitrary IP address

ipdata 8.8.8.8

Filter result by specifying coma separated list of fields

ipdata 8.8.8.8 --fields ip,country_code

You can also use jq to filter the responses

ipdata me | jq .country_name

Batch lookup

ipdata my_ip_backlog.csv --output geolocation_results.json

Batch lookup with output to CSV file

ipdata my_ip_backlog.csv --output <file to output> --output-format CSV --fields ip,country_code

--fields option is required in case of CSV output.

Available Fields

A list of all the fields returned by the API is maintained at Response Fields

Errors

A list of possible errors is available at Status Codes

Tests

To run all tests

python -m unittest

Metadata

Release files for ipdata 3.3.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ipdata 3.3.6
File	Size	Uploaded
ipdata-3.3.6.tar.gz	10.6 kB	Nov 8, 2020	Details

Built distribution (wheel)

Table of built distributions (wheels) for ipdata 3.3.6
File	Interpreter	ABI	Platform	Reset
ipdata-3.3.6-py3-none-any.whl 8.8 kB Nov 8, 2020	Python 3	none	any	Details

Total release size: 19.4 kB

Release files / ipdata-3.3.6.tar.gz

Download URL	ipdata-3.3.6.tar.gz
Size	10.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`9f68c321c4e56c46436890cf2b914578477f677ab9ef489de01da8bb491d19c0`
BLAKE2b-256 checksum How to use checksums	`e617a9f6e83c633639193550bfd784f4d2c5949aae7bc4e8e8c976368c0ef742`
Upload date	Nov 8, 2020
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/50.3.2 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6`

Release files / ipdata-3.3.6-py3-none-any.whl

Download URL	ipdata-3.3.6-py3-none-any.whl
Size	8.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1629d8b5532f7c210a43089e203e048d0568c434072a77e4077a6d5a6fb2e77e`
BLAKE2b-256 checksum How to use checksums	`6f0f70f19394419f2ed07ea7a8481dd122a1fe4b167b2afe5c6163cb495bafae`
Upload date	Nov 8, 2020
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/50.3.2 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6`