ipregistry 5.0.0

Official Python library for Ipregistry

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. Version 5 and above require Python 3.10+.

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)

Asynchronous Client

An asyncio-based client with the same feature set is available when the library is installed with the async extra (pip install ipregistry[async]):

from ipregistry import AsyncIpregistryClient

async def main():
    async with AsyncIpregistryClient("YOUR_API_KEY") as client:
        response = await client.lookup_ip("54.85.132.205")
        print(response.data.location.country.code)

More advanced examples are available in the samples folder.

Configuration

Timeouts, retries and the User-Agent header are configurable through IpregistryConfig:

from ipregistry import IpregistryClient, IpregistryConfig

config = IpregistryConfig(
    "YOUR_API_KEY",
    timeout=15,                        # seconds; a (connect, read) tuple is also accepted
    retry_max_attempts=3,              # attempts per request, including the initial one
    retry_interval=1,                  # base delay in seconds, doubled on each retry
    retry_on_server_error=True,        # retry 5xx responses
    retry_on_too_many_requests=False,  # retry 429 responses, honoring Retry-After
    user_agent=None                    # custom User-Agent header value
)
client = IpregistryClient(config)

Transient network errors are always retried up to retry_max_attempts.

The client reuses pooled HTTP connections through a requests.Session. You may pass your own session with IpregistryClient("YOUR_API_KEY", session=my_session) for proxy or TLS control, and release resources with client.close() or by using the client as a context manager.

Batch lookups larger than the API limit of 1024 items are automatically split into concurrent chunks. Tune this with IpregistryClient("YOUR_API_KEY", max_batch_size=1024, batch_concurrency=4).

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. Failed entries in batch responses are instances of IpregistryLookupError (also available under the legacy alias LookupError).

Errors of type ApiError include a code field that maps to the one described in the Ipregistry documentation, along with a typed error_code enum value (ErrorCode) that is None for unrecognized codes.

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.