ipregistry / ipregistry-python

Official Python client for Ipregistry (IP geolocation and other IP intelligence data).

Ipregistry Python Client Library

This is the official Python client library for the Ipregistry IP geolocation and threat data API, allowing you to lookup your own IP address or specified ones. Responses return multiple data points including carrier, company, currency, location, timezone, threat information, and more.

Starting version 3 of the library, support for Python 2 has been dropped and the library requires Python 3.6+.

Getting Started

You'll need an Ipregistry API key, which you can get along with 100,000 free lookups by signing up for a free account at https://ipregistry.co.

Installation

pip install ipregistry

Quick Start

Single IP Lookup

from ipregistry import IpregistryClient

client = IpregistryClient("YOUR_API_KEY")
response = client.lookup_ip("54.85.132.205")

# Printing whole response
print(response)

# Retrieving a specific field
country_code = response.data.location.country.code

# Getting number of credits consumed or remaining
credits_consumed = response.credits.consumed
credits_remaining = response.credits.remaining

Single ASN Lookup

from ipregistry import IpregistryClient

client = IpregistryClient("YOUR_API_KEY")
response = client.lookup_asn(42)
print(response.credits.consumed)
print(response.data.prefixes)
print(response.data.relationships)

Batch IP Lookup

from ipregistry import IpregistryClient

client = IpregistryClient("YOUR_API_KEY")
response = client.batch_lookup_ips(["54.85.132.205", "8.8.8.8", "2001:67c:2e8:22::c100:68b"])
for ip_info in response.data:
    print(ip_info)

Origin IP Lookup

from ipregistry import IpregistryClient

client = IpregistryClient("YOUR_API_KEY")
response = client.origin_lookup_ip()
print(response.data)

User-Agent Parsing

from ipregistry import IpregistryClient

client = IpregistryClient("YOUR_API_KEY")
response = client.parse_user_agent('Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36')
print(response.data)

More advanced examples are available in the samples folder.

Caching

This Ipregistry client library has built-in support for in-memory caching. By default caching is disabled. Below are examples to enable and configure a caching strategy. Once enabled, default cache strategy is to memoize up to 2048 lookups for at most 10min. You can change preferences as follows:

Enabling caching

Enable caching by passing an instance of InMemoryCache:

from ipregistry import InMemoryCache, IpregistryClient

client = IpregistryClient("YOUR_API_KEY", cache=InMemoryCache(maxsize=2048, ttl=600))

Disabling caching

Disable caching by passing an instance of NoCache:

from ipregistry import IpregistryClient, NoCache

client = IpregistryClient("YOUR_API_KEY", cache=NoCache())

European Union Base URL

Using the EU base URL, your requests are handled by the closest cluster of nodes in the European Union:

from ipregistry import IpregistryClient, NoCache

client = IpregistryClient(IpregistryConfig("YOUR_API_KEY").with_eu_base_url())

Errors

All Ipregistry exceptions inherit IpregistryError class.

Main subtypes are ApiError and ClientError.

Errors of type ApiError include a code field that maps to the one described in the Ipregistry documentation.

Filtering bots

You might want to prevent Ipregistry API requests for crawlers or bots browsing your pages.

A manner to proceed is to identify bots using the User-Agent header. To ease this process, the library includes a utility method:

from ipregistry import UserAgents

is_bot = UserAgents.is_bot('YOUR_USER_AGENT_HEADER_VALUE_HERE')

Other Libraries

There are official Ipregistry client libraries available for many languages including Java, Javascript, and more.

Are you looking for an official client with a programming language or framework we do not support yet? let us know.

ipregistry-python's Issues

Failed installation: setup.py import assumes deps already installed

When installing ipregistry 2.0.0 in our CI server we get the following errors:

#8 7.073 Collecting ipregistry==2.0.0
#8 7.144   Downloading ipregistry-2.0.0.tar.gz (5.8 kB)
#8 7.338     ERROR: Command errored out with exit status 1:
#8 7.338      command: /var/lang/bin/python3.8 -c 'import io, os, sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-s1_fc88h/ipregistry_0f83ab2a0e3d4d13bdf0bb70c6d21a9e/setup.py'"'"'; __file__='"'"'/tmp/pip-install-s1_fc88h/ipregistry_0f83ab2a0e3d4d13bdf0bb70c6d21a9e/setup.py'"'"';f = getattr(tokenize, '"'"'open'"'"', open)(__file__) if os.path.exists(__file__) else io.StringIO('"'"'from setuptools import setup; setup()'"'"');code = f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /tmp/pip-pip-egg-info-paikyw6j
#8 7.338          cwd: /tmp/pip-install-s1_fc88h/ipregistry_0f83ab2a0e3d4d13bdf0bb70c6d21a9e/
#8 7.338     Complete output (9 lines):
#8 7.338     Traceback (most recent call last):
#8 7.338       File "<string>", line 1, in <module>
#8 7.338       File "/tmp/pip-install-s1_fc88h/ipregistry_0f83ab2a0e3d4d13bdf0bb70c6d21a9e/setup.py", line 3, in <module>
#8 7.338         from ipregistry import __version__
#8 7.338       File "/tmp/pip-install-s1_fc88h/ipregistry_0f83ab2a0e3d4d13bdf0bb70c6d21a9e/ipregistry/__init__.py", line 5, in <module>
#8 7.338         from .cache import *
#8 7.338       File "/tmp/pip-install-s1_fc88h/ipregistry_0f83ab2a0e3d4d13bdf0bb70c6d21a9e/ipregistry/cache.py", line 17, in <module>
#8 7.338         import abc, six
#8 7.338     ModuleNotFoundError: No module named 'six'
#8 7.338     ----------------------------------------
#8 7.342 WARNING: Discarding https://files.pythonhosted.org/packages/aa/eb/791256c45052d3fde4fe7e6d10b489f025b943ce56cfde691cff46dd1090/ipregistry-2.0.0.tar.gz#sha256=f07a5f9b8b791b83f648f47475e53d600a91cc52d8f7658486d946a87bb9bad0 (from https://pypi.org/simple/ipregistry/). Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.
#8 7.342 ERROR: Could not find a version that satisfies the requirement ipregistry==2.0.0 (from versions: 1.0.0, 1.1.0, 2.0.0, 2.0.1, 3.0.0, 3.1.0)
#8 7.342 ERROR: No matching distribution found for ipregistry==2.0.0
#8 7.463 WARNING: You are using pip version 21.1.1; however, version 21.3.1 is available.
#8 7.463 You should consider upgrading via the '/var/lang/bin/python3.8 -m pip install --upgrade pip' command.
#8 ERROR: process "/bin/sh -c pip install --no-cache-dir -r /tmp/requirements.txt" did not complete successfully: exit code: 1
------
 > [4/7] RUN pip install --no-cache-dir -r /tmp/requirements.txt:
#8 7.338         from .cache import *
#8 7.338       File "/tmp/pip-install-s1_fc88h/ipregistry_0f83ab2a0e3d4d13bdf0bb70c6d21a9e/ipregistry/cache.py", line 17, in <module>
#8 7.338         import abc, six
#8 7.338     ModuleNotFoundError: No module named 'six'
#8 7.338     ----------------------------------------
#8 7.342 WARNING: Discarding https://files.pythonhosted.org/packages/aa/eb/791256c45052d3fde4fe7e6d10b489f025b943ce56cfde691cff46dd1090/ipregistry-2.0.0.tar.gz#sha256=f07a5f9b8b791b83f648f47475e53d600a91cc52d8f7658486d946a87bb9bad0 (from https://pypi.org/simple/ipregistry/). Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.
#8 7.342 ERROR: Could not find a version that satisfies the requirement ipregistry==2.0.0 (from versions: 1.0.0, 1.1.0, 2.0.0, 2.0.1, 3.0.0, 3.1.0)
#8 7.342 ERROR: No matching distribution found for ipregistry==2.0.0

The reason seems to be that setup.py imports from the module (from ipregistry import __version__). This import in turn causes __init__.py to run several other imports, basically trying to import all of its dependencies, like that import abc, six you see above. Because the deps are not yet installed, the whole process fails. This all happens before the installation begins.

In our case, this was solved by manually installing ALL dependencies in our CI server before beginning the build process (and in our local dev environment for development). This is not only quite inconvenient, but could cause dependency problems in monorepo-style projects.

A suggestion for a simple and quick fix would be to store the __version__ variable in a separate version.py. This way __init__.py would import from it and setup.py would not require importing all dependencies of the (yet to install) package.

Additionally, the reason we are using version ipregistry 2.0.0 is that requirements are very strict (all are ==), which means that our dependency management tool (poetry) won't be able to find a compatible combination of dependency versions with the other packages we're using. Seeing as this package is seldomly updated and its dependencies are a few, fairly stable packages like requests, I'd suggest relaxing those requirements to allow for patches or even minor version upgrades (e.g. requests>=2.22.0,<3).

Return credits and throttling data with lookup methods

As part of a new major version, the IpregistryClient API should be reworked to return a response that includes information about remaining credits and throttling when enabled, in addition to lookup data.

We should mimic what we did with the official TypeScript library:

https://github.com/ipregistry/ipregistry-javascript/blob/0f7120b647e33cf822e042955951f8beaf65709d/src/request.ts#L24

How to use the dedicated EU base URL

We have seen in a recent update that you are introducing a dedicated EU base URL. Will you modify the library to be able to use this endpoint?

Make Poetry read version from version.py

There is a plugin for this but it requires version 1.2+ of Poetry that is still alpha:

https://pythonrepo.com/repo/tiangolo-poetry-version-plugin-python-package-dependency-management

We should consider it once a stable version of Poetry 1.2 is available.