Python SDK

Overview

The IPFly Python SDK wraps the IPFly API in a single dependency-free module. It relies only on the standard library (urllib, threading, ipaddress, json) and handles the operational details — caching, retries, rate limiting, and thread-safe request de-duplication — so your integration code can stay focused on what to do with the response.

Where This SDK Belongs

If you need geolocation results in a browser-facing app, put this SDK behind your own backend endpoint and call that endpoint from the client (see the Flask proxy example below), or use the IPFly JavaScript SDK with a domain-restricted token for prototyping.

Installation

No PyPI package is published — copy ipfly_sdk.py into your project, or host it internally and pull it in your build step.

# Drop ipfly_sdk.py directly into your source tree, e.g.:
cp ipfly_sdk.py my_project/vendor/ipfly_sdk.py

curl -O https://ipfly.world/libs/python-sdk/ipfly_sdk.py
# or
wget https://ipfly.world/libs/python-sdk/ipfly_sdk.py

from ipfly_sdk import IPFlyClient, IPFlyError, is_valid_ip

client = IPFlyClient(token="YOUR_TOKEN")

Quick Start

Create a client once, then call lookup() wherever you need geolocation data.

from ipfly_sdk import IPFlyClient, IPFlyError

client = IPFlyClient(
    token="YOUR_TOKEN",
    include="security",  # optional: request the security/ASN field set on every call
)

# Look up a specific IP
data = client.lookup("8.8.8.8")
print(data["city"], data["country_name"], data["security"]["is_vpn"])

# Look up the caller's own IP (omit the ip argument)
me = client.lookup_self()
print("You appear to be in", me["city"])

# Handle errors explicitly
try:
    client.lookup("not-an-ip")
except IPFlyError as err:
    print(err.code, err.message)

# Use as a context manager to clean up cache/state automatically
with IPFlyClient(token="YOUR_TOKEN") as c:
    print(c.lookup("1.1.1.1")["country_name"])

Client Parameters

All parameters are passed to IPFlyClient(...).

Cache Options

Passed as the cache dict, e.g. IPFlyClient(token=..., cache={"storage": "file", "ttl": 3600}).

.lookup() & .lookup_self()

client.lookup(ip=None, include=None, skip_cache=False, timeout=None) looks up a single IP. Omit ip (or pass None) to geolocate the caller — or use the client.lookup_self(**kwargs) shorthand.

client.lookup(
    "1.1.1.1",
    include="security",  # overrides the client-level `include` for this call only
    skip_cache=True,       # force a fresh network request, bypassing the cache
    timeout=3.0,            # override the client's default timeout for this call
)

Returns the parsed JSON response as a dict (see Response Shape). Raises IPFlyError on failure (see Error Handling).

.batch_lookup()

client.batch_lookup(ips, concurrency=None, **kwargs) looks up a list of IPs using a bounded ThreadPoolExecutor (concurrency overrides the client default). This call never raises for an individual IP failure — it returns a list of BatchResult in the same order as ips.

from ipfly_sdk import BatchResult

results = client.batch_lookup(["8.8.8.8", "1.1.1.1", "not-an-ip"])
for r in results:
    if r.ok:
        print(r.ip, "->", r.data["city"])
    else:
        print(r.ip, "failed:", r.error.code)

BatchResult is a small dataclass: ip: str, ok: bool, data: Optional[dict], error: Optional[IPFlyError].

Cache Controls

is_valid_ip()

A module-level helper that validates an IPv4 or IPv6 string without making a request.

from ipfly_sdk import is_valid_ip

is_valid_ip("8.8.8.8")               # True
is_valid_ip("2001:4860:4860::8888")  # True
is_valid_ip("not-an-ip")             # False

Response Shape

Successful lookups return the same JSON structure the IPFly API returns, unchanged, as a Python dict — see the full field reference in the API docs. Shape depends on your plan and the include value requested.

{
    "ip": "8.8.8.8",
    "hostname": "dns.google",
    "country_name": "United States",
    "city": "Mountain View",
    "latitude": "37.4056",
    "longitude": "-122.0775",
    "time_zone": {"name": "America/New_York", "...": "..."},
    "asn": {"asn": "AS15169", "name": "Google LLC", "...": "..."},
    "security": {"is_vpn": False, "is_tor": False, "...": "..."},
}

Error Handling

All failures raise IPFlyError, a plain Exception subclass carrying message, status, code, and cause attributes.

from ipfly_sdk import IPFlyClient, IPFlyError

client = IPFlyClient(token="YOUR_TOKEN")

try:
    client.lookup("8.8.8.8")
except IPFlyError as err:
    if err.code == "TIMEOUT":
        ...  # retry later, log, fall back to a default
    elif err.status == 401:
        ...  # token is invalid — surface a config error, don't retry
    print(err.message)

Performance Notes

Examples

Two common integration patterns: enriching a CSV of visitor IPs in bulk, and proxying instead of embedding your token in a client-facing app.

import csv
from ipfly_sdk import IPFlyClient

client = IPFlyClient(token="YOUR_TOKEN", cache={"storage": "file", "path": "geo_cache.json"})

with open("visitors.csv") as infile:
    reader = csv.DictReader(infile)
    ips = [row["ip"] for row in reader]

for result in client.batch_lookup(ips, concurrency=8):
    if result.ok:
        print(result.ip, "->", result.data["country_name"])
    else:
        print(result.ip, "-> error:", result.error.code)

from flask import Flask, request, jsonify
from ipfly_sdk import IPFlyClient, IPFlyError
import os

app = Flask(__name__)
client = IPFlyClient(token=os.environ["IPFLY_TOKEN"])

@app.get("/api/geo")
def geo():
    ip = request.args.get("ip") or request.remote_addr
    try:
        return jsonify(client.lookup(ip, include="security"))
    except IPFlyError as err:
        return jsonify({"error": err.code, "message": err.message}), err.status or 502

Command-Line Usage

The module ships a tiny CLI for quick checks.

export IPFLY_TOKEN=your_token_here
python -m ipfly_sdk 8.8.8.8
python -m ipfly_sdk                     # looks up your own IP
python -m ipfly_sdk 8.8.8.8 --include security

Python Version Support

Requires Python 3.7+ (uses dataclasses and from __future__ import annotations). No third-party packages — works anywhere the standard library is available, including minimal containers and locked-down environments.

License

MIT — use it, fork it, ship it.