GitHub Workflow Status

Official Python client library and CLI for the ipdata API

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 that you need an API Key to use this package. You can get a free one with a 1,500 daily request limit by Signing up here.

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.

Look up your own IP address

ipdata

ipdata me

Look up an arbitrary IP address

ipdata 8.8.8.8

Filter results by specifying comma 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.9

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.9
File	Size	Uploaded
ipdata-3.3.9.tar.gz	10.9 kB	Nov 8, 2020	Details

Built distribution (wheel)

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

Total release size: 19.9 kB

Release files / ipdata-3.3.9.tar.gz

Download URL	ipdata-3.3.9.tar.gz
Size	10.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`e895a23718b5c94d425d84f8274b7d2febb226aa41cb67ffe87e2a7862679a1b`
BLAKE2b-256 checksum How to use checksums	`4ffd5ca22a0fab46c12cea43434474a13720a3a09d7b1f59b00a43c0bf8f211a`
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.9-py3-none-any.whl

Download URL	ipdata-3.3.9-py3-none-any.whl
Size	9.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`268c4877055f3da77d14435aed21207c9e3793d34cea66ff9f4fd91960469026`
BLAKE2b-256 checksum How to use checksums	`6a55980f099b7cb2d546b384ba83a3f9ebb9e5b356709c1b988e071d6d4c2dfd`
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`