ipdatainfo 0.1.0__py3-none-any.whl

ipdatainfo/__init__.py

@@ -0,0 +1,36 @@
+"""Official Python client for the ipdata.info IP geolocation, ASN, and
+threat-intelligence API. See https://ipdata.info.
+"""
+
+from .client import DEFAULT_BASE_URL, PRO_BASE_URL, Client, __version__
+from .errors import IpDataError
+from .models import (
+    ASNBrief,
+    Connection,
+    Currency,
+    Flag,
+    GeoInfo,
+    IPInfo,
+    Network,
+    Security,
+    ThreatMatch,
+    TimeZone,
+)
+
+__all__ = [
+    "Client",
+    "IpDataError",
+    "DEFAULT_BASE_URL",
+    "PRO_BASE_URL",
+    "__version__",
+    "IPInfo",
+    "GeoInfo",
+    "ASNBrief",
+    "ThreatMatch",
+    "Network",
+    "Flag",
+    "Connection",
+    "TimeZone",
+    "Currency",
+    "Security",
+]

ipdatainfo/client.py

@@ -0,0 +1,161 @@
+"""HTTP client for the ipdata.info API.
+
+Uses only the standard library (``urllib.request``/``json``) so the package
+has zero required runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from .errors import IpDataError
+from .models import ASNBrief, GeoInfo, IPInfo, ThreatMatch
+
+#: Free tier host (50 req/min, no key).
+DEFAULT_BASE_URL = "https://ipdata.info"
+#: Paid tier host, used automatically once an API key is set (unless the
+#: caller overrides ``base_url`` explicitly).
+PRO_BASE_URL = "https://pro.ipdata.info"
+
+__version__ = "0.1.0"
+_USER_AGENT = f"ipdatainfo-python/{__version__}"
+
+
+class Client:
+    """ipdata.info API client.
+
+    Args:
+        api_key: Optional API key, sent as the ``X-Api-Key`` header. When
+            set and ``base_url`` is not overridden, the client targets the
+            pro tier host automatically.
+        base_url: API host, no trailing slash. Defaults to the free tier
+            (``https://ipdata.info``), or the pro tier when ``api_key`` is
+            set.
+        timeout: Request timeout in seconds. Defaults to 10.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self.api_key = api_key
+        if base_url is not None:
+            self.base_url = base_url.rstrip("/")
+        elif api_key:
+            self.base_url = PRO_BASE_URL
+        else:
+            self.base_url = DEFAULT_BASE_URL
+        self.timeout = timeout
+
+    # -- lookup family -----------------------------------------------------
+
+    def lookup(self, ip: str = "") -> IPInfo:
+        """Return the full record for ``ip``. Empty string = caller's own IP."""
+        data = self._get(f"/json/{urllib.parse.quote(ip, safe='')}")
+        return IPInfo.from_dict(data)
+
+    def geo(self, ip: str) -> GeoInfo:
+        """Return the compact geo subset for ``ip``."""
+        data = self._get(f"/api/v1/{urllib.parse.quote(ip, safe='')}/geo")
+        return GeoInfo.from_dict(data)
+
+    def asn(self, ip: str) -> ASNBrief:
+        """Return the compact ASN subset for ``ip``."""
+        data = self._get(f"/api/v1/{urllib.parse.quote(ip, safe='')}/asn")
+        return ASNBrief.from_dict(data)
+
+    def batch(self, ips: list[str]) -> list[IPInfo]:
+        """Look up many IPs at once. Requires an API key (paid tier)."""
+        data = self._post("/api/v1/batch", ips)
+        if not isinstance(data, list):
+            raise IpDataError(status=200, message="unexpected batch response shape")
+        return [IPInfo.from_dict(item) for item in data]
+
+    # -- ASN metadata --------------------------------------------------
+
+    def asn_detail(self, number: int) -> dict[str, Any]:
+        """Return the detailed ASN record (prefixes, peering) as raw JSON."""
+        return self._get(f"/api/v1/asn/{number}")
+
+    def asn_whois_history(self, number: int) -> dict[str, Any]:
+        """Return the ASN whois history as raw JSON."""
+        return self._get(f"/api/v1/asn/{number}/whois-history")
+
+    def asn_changes(self) -> Any:
+        """Return the ASN change feed as raw JSON."""
+        return self._get("/api/v1/asn-changes")
+
+    # -- threat intel --------------------------------------------------
+
+    def threat_domain(self, domain: str) -> ThreatMatch:
+        """Look up a domain in the threat-intel store."""
+        data = self._get(f"/api/v1/threat/domain/{urllib.parse.quote(domain, safe='')}")
+        return ThreatMatch.from_dict(data)
+
+    def threat_hash(self, hash: str) -> ThreatMatch:
+        """Look up a file hash (md5/sha1/sha256)."""
+        data = self._get(f"/api/v1/threat/hash/{urllib.parse.quote(hash, safe='')}")
+        return ThreatMatch.from_dict(data)
+
+    def threat_url(self, url: str) -> ThreatMatch:
+        """Look up a URL (server falls back to its domain on a miss)."""
+        query = urllib.parse.urlencode({"u": url})
+        data = self._get(f"/api/v1/threat/url?{query}")
+        return ThreatMatch.from_dict(data)
+
+    # -- internals -----------------------------------------------------
+
+    def _get(self, path: str) -> Any:
+        return self._request("GET", path, body=None)
+
+    def _post(self, path: str, payload: Any) -> Any:
+        body = json.dumps(payload).encode("utf-8")
+        return self._request("POST", path, body=body)
+
+    def _request(self, method: str, path: str, body: bytes | None) -> Any:
+        url = self.base_url + path
+        headers = {
+            "User-Agent": _USER_AGENT,
+            "Accept": "application/json",
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if self.api_key:
+            headers["X-Api-Key"] = self.api_key
+
+        req = urllib.request.Request(url, data=body, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read()
+                status = resp.status
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            raise IpDataError(status=exc.code, message=_error_message(raw)) from exc
+        except urllib.error.URLError as exc:
+            raise IpDataError(status=0, message=str(exc.reason)) from exc
+
+        if status < 200 or status >= 300:
+            raise IpDataError(status=status, message=_error_message(raw))
+
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise IpDataError(status=status, message=f"decode response: {exc}") from exc
+
+
+def _error_message(raw: bytes) -> str:
+    try:
+        parsed = json.loads(raw)
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return raw.decode("utf-8", errors="replace")
+    if isinstance(parsed, dict) and parsed.get("error"):
+        return str(parsed["error"])
+    return raw.decode("utf-8", errors="replace")

ipdatainfo/errors.py

@@ -0,0 +1,18 @@
+"""Error types for the ipdatainfo client."""
+
+from __future__ import annotations
+
+
+class IpDataError(Exception):
+    """Raised for any non-2xx response from the ipdata.info API.
+
+    Attributes:
+        status: HTTP status code of the response.
+        message: Error message parsed from the ``{"error": "..."}`` body,
+            or the raw response body when that shape is absent.
+    """
+
+    def __init__(self, status: int, message: str) -> None:
+        self.status = status
+        self.message = message
+        super().__init__(f"ipdatainfo: HTTP {status}: {message}")

ipdatainfo/models.py

@@ -0,0 +1,286 @@
+"""Response models for the ipdatainfo client.
+
+All dataclasses tolerate missing and unknown JSON fields: the API omits
+null/empty fields from responses, and future API additions should not break
+older SDK versions. Each model exposes a ``from_dict`` classmethod that reads
+known keys and ignores everything else.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _get(data: dict[str, Any], key: str, default: Any = None) -> Any:
+    value = data.get(key, default)
+    return value if value is not None else default
+
+
+@dataclass
+class Network:
+    asn: int = 0
+    as_name: str = ""
+    route: str = ""
+    registry_country: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Network | None":
+        if not data:
+            return None
+        return cls(
+            asn=_get(data, "asn", 0),
+            as_name=_get(data, "as_name", ""),
+            route=_get(data, "route", ""),
+            registry_country=_get(data, "registry_country", ""),
+        )
+
+
+@dataclass
+class Flag:
+    img: str = ""
+    emoji: str = ""
+    emoji_unicode: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Flag | None":
+        if not data:
+            return None
+        return cls(
+            img=_get(data, "img", ""),
+            emoji=_get(data, "emoji", ""),
+            emoji_unicode=_get(data, "emoji_unicode", ""),
+        )
+
+
+@dataclass
+class Connection:
+    asn: int = 0
+    org: str = ""
+    isp: str = ""
+    domain: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Connection | None":
+        if not data:
+            return None
+        return cls(
+            asn=_get(data, "asn", 0),
+            org=_get(data, "org", ""),
+            isp=_get(data, "isp", ""),
+            domain=_get(data, "domain", ""),
+        )
+
+
+@dataclass
+class TimeZone:
+    id: str = ""
+    abbr: str = ""
+    is_dst: bool = False
+    offset: int = 0
+    utc: str = ""
+    current_time: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "TimeZone | None":
+        if not data:
+            return None
+        return cls(
+            id=_get(data, "id", ""),
+            abbr=_get(data, "abbr", ""),
+            is_dst=_get(data, "is_dst", False),
+            offset=_get(data, "offset", 0),
+            utc=_get(data, "utc", ""),
+            current_time=_get(data, "current_time", ""),
+        )
+
+
+@dataclass
+class Currency:
+    name: str = ""
+    code: str = ""
+    symbol: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Currency | None":
+        if not data:
+            return None
+        return cls(
+            name=_get(data, "name", ""),
+            code=_get(data, "code", ""),
+            symbol=_get(data, "symbol", ""),
+        )
+
+
+@dataclass
+class Security:
+    anonymous: bool = False
+    proxy: bool = False
+    vpn: bool = False
+    tor: bool = False
+    hosting: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Security | None":
+        if not data:
+            return None
+        return cls(
+            anonymous=_get(data, "anonymous", False),
+            proxy=_get(data, "proxy", False),
+            vpn=_get(data, "vpn", False),
+            tor=_get(data, "tor", False),
+            hosting=_get(data, "hosting", False),
+        )
+
+
+@dataclass
+class IPInfo:
+    """Full geolocation record returned by ``lookup``.
+
+    The API omits null/empty fields, so most fields default to a falsy value
+    (empty string, 0, False) when absent.
+    """
+
+    ip: str = ""
+    success: bool = False
+    type: str = ""
+    continent: str = ""
+    continent_code: str = ""
+    country: str = ""
+    country_code: str = ""
+    region: str = ""
+    city: str = ""
+    latitude: float = 0.0
+    longitude: float = 0.0
+    is_eu: bool = False
+    timezone: str = ""
+    zip: str = ""
+    postal: str = ""
+    calling_code: str = ""
+    capital: str = ""
+    borders: str = ""
+    asn: int = 0
+    asn_org: str = ""
+    isp: str = ""
+    registry: str = ""
+    is_proxy: bool = False
+    is_hosting: bool = False
+    network: Network | None = None
+    flag: Flag | None = None
+    connection: Connection | None = None
+    time_zone: TimeZone | None = None
+    currency: Currency | None = None
+    security: Security | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "IPInfo":
+        return cls(
+            ip=_get(data, "ip", ""),
+            success=_get(data, "success", False),
+            type=_get(data, "type", ""),
+            continent=_get(data, "continent", ""),
+            continent_code=_get(data, "continent_code", ""),
+            country=_get(data, "country", ""),
+            country_code=_get(data, "country_code", ""),
+            region=_get(data, "region", ""),
+            city=_get(data, "city", ""),
+            latitude=_get(data, "latitude", 0.0),
+            longitude=_get(data, "longitude", 0.0),
+            is_eu=_get(data, "is_eu", False),
+            timezone=_get(data, "timezone", ""),
+            zip=_get(data, "zip", ""),
+            postal=_get(data, "postal", ""),
+            calling_code=_get(data, "calling_code", ""),
+            capital=_get(data, "capital", ""),
+            borders=_get(data, "borders", ""),
+            asn=_get(data, "asn", 0),
+            asn_org=_get(data, "asn_org", ""),
+            isp=_get(data, "isp", ""),
+            registry=_get(data, "registry", ""),
+            is_proxy=_get(data, "is_proxy", False),
+            is_hosting=_get(data, "is_hosting", False),
+            network=Network.from_dict(data.get("network")),
+            flag=Flag.from_dict(data.get("flag")),
+            connection=Connection.from_dict(data.get("connection")),
+            time_zone=TimeZone.from_dict(data.get("time_zone")),
+            currency=Currency.from_dict(data.get("currency")),
+            security=Security.from_dict(data.get("security")),
+        )
+
+
+@dataclass
+class GeoInfo:
+    """Compact geo subset returned by ``geo``."""
+
+    ip: str = ""
+    city: str = ""
+    region: str = ""
+    country: str = ""
+    country_code: str = ""
+    latitude: float = 0.0
+    longitude: float = 0.0
+    timezone: str = ""
+    zip: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GeoInfo":
+        return cls(
+            ip=_get(data, "ip", ""),
+            city=_get(data, "city", ""),
+            region=_get(data, "region", ""),
+            country=_get(data, "country", ""),
+            country_code=_get(data, "country_code", ""),
+            latitude=_get(data, "latitude", 0.0),
+            longitude=_get(data, "longitude", 0.0),
+            timezone=_get(data, "timezone", ""),
+            zip=_get(data, "zip", ""),
+        )
+
+
+@dataclass
+class ASNBrief:
+    """Compact ASN subset returned by ``asn``."""
+
+    ip: str = ""
+    asn: int = 0
+    asn_org: str = ""
+    isp: str = ""
+    registry: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ASNBrief":
+        return cls(
+            ip=_get(data, "ip", ""),
+            asn=_get(data, "asn", 0),
+            asn_org=_get(data, "asn_org", ""),
+            isp=_get(data, "isp", ""),
+            registry=_get(data, "registry", ""),
+        )
+
+
+@dataclass
+class ThreatMatch:
+    """Result of a threat-intel lookup. When ``listed`` is False the
+    remaining fields default to empty."""
+
+    value: str = ""
+    ioc_type: str = ""
+    listed: bool = False
+    threat_type: str = ""
+    sources: list[str] = field(default_factory=list)
+    confidence: int = 0
+    first_seen: str = ""
+    last_seen: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ThreatMatch":
+        return cls(
+            value=_get(data, "value", ""),
+            ioc_type=_get(data, "ioc_type", ""),
+            listed=_get(data, "listed", False),
+            threat_type=_get(data, "threat_type", ""),
+            sources=_get(data, "sources", []) or [],
+            confidence=_get(data, "confidence", 0),
+            first_seen=_get(data, "first_seen", ""),
+            last_seen=_get(data, "last_seen", ""),
+        )

ipdatainfo-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: ipdatainfo
+Version: 0.1.0
+Summary: Official Python client for the ipdata.info IP geolocation, ASN, and threat-intelligence API
+Project-URL: Homepage, https://ipdata.info
+Project-URL: Repository, https://github.com/IPDataInfo/ipdata-python
+Project-URL: Documentation, https://ipdata.info/docs/sdks
+Project-URL: Changelog, https://github.com/IPDataInfo/ipdata-python/blob/main/CHANGELOG.md
+Author: ipdata.info
+License-Expression: MIT
+License-File: LICENSE
+Keywords: geoip,ip-api,ip-geolocation,ip-lookup,ipdata,threat-intelligence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# IPData.info Python SDK — Free IP Geolocation & Threat Intelligence API
+
+[![PyPI](https://img.shields.io/pypi/v/ipdatainfo.svg)](https://pypi.org/project/ipdatainfo/) [![CI](../../actions/workflows/ci.yml/badge.svg)](../../actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+Official Python client for [**ipdata.info**](https://ipdata.info) — a free,
+fast IP geolocation, ASN, and threat-intelligence API. Look up country, city,
+ASN, timezone, currency, and security flags (proxy/VPN/Tor/hosting) for any IPv4
+or IPv6 address. Powered by [ipdata.info](https://ipdata.info).
+
+## Get a free API key
+
+The public endpoint is **free — 50 requests/min, no signup, no key**. For higher
+rate limits and batch lookups, [**create a free API key at
+ipdata.info/register**](https://ipdata.info/register) and manage it in your
+[dashboard](https://ipdata.info/dashboard).
+
+## Install
+
+```
+pip install ipdatainfo
+```
+
+## Quickstart
+
+```python
+from ipdatainfo import Client
+
+# Free tier — no API key needed. For higher limits + batch, get a free key
+# at https://ipdata.info/register and use Client(api_key="...").
+client = Client()
+
+info = client.lookup("8.8.8.8")
+print(info.city, info.country, info.asn_org)  # Mountain View United States Google LLC
+```
+
+## Methods
+
+| Method | What it returns |
+|--------|-----------------|
+| `lookup(ip="")` | Full geolocation record (own IP if omitted) |
+| `geo(ip)` | Geo subset (city/region/country/lat/lon/tz) |
+| `asn(ip)` | ASN + ISP/registry for an IP |
+| `batch(ips)` | Many IPs at once (**requires an API key**) |
+| `asn_detail(n)` | ASN detail incl. prefixes |
+| `asn_whois_history(n)` | ASN whois history |
+| `asn_changes()` | ASN change feed |
+| `threat_domain/threat_hash/threat_url(x)` | Threat-intel lookup (domain / file hash / URL) |
+
+Full response schema: [ipdata.info API docs](https://ipdata.info/docs) ·
+[SDK contract](https://ipdata.info/docs/sdks).
+
+## Configuration
+
+```python
+from ipdatainfo import Client
+
+client = Client(
+    api_key="KEY",                        # sent as X-Api-Key; switches to pro.ipdata.info
+    base_url="https://ipdata.info",       # override the host
+    timeout=10.0,                          # seconds
+)
+```
+
+Errors from non-2xx responses are raised as `ipdatainfo.IpDataError` with
+`.status` and `.message`.
+
+## Rate limits
+
+- Free (`ipdata.info`): 50 req/min, no key.
+- Paid (`pro.ipdata.info`): higher limits + `batch`, with an
+  [API key](https://ipdata.info/register).
+
+## Other SDKs
+
+12 official SDKs — see the full list at
+[**ipdata.info/docs/sdks**](https://ipdata.info/docs/sdks): Python, Node.js, Go,
+PHP, Java, Rust, .NET, Kotlin, Swift, Dart, Bash, Objective-C.
+
+## License
+
+MIT © [ipdata.info](https://ipdata.info)

ipdatainfo-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ipdatainfo/__init__.py,sha256=TKYTl_GJl3193DfOumE84wOuBfAqZysbrQhWB9hW8GE,659
+ipdatainfo/client.py,sha256=c-PyHM5L-dGZjtHBbiWKBEitoDnZ0R4MZOfbbfZi348,6011
+ipdatainfo/errors.py,sha256=tnooj169bJUXFyGjTum8Cnxt9gLF2Hyma9tmhbIWVy8,577
+ipdatainfo/models.py,sha256=omGzeQDPeweBwrowkODjumPVAytpl5Sf-RV6taCeBMU,8180
+ipdatainfo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ipdatainfo-0.1.0.dist-info/METADATA,sha256=TNCXnozgcQUYgrjXAW9i4U_PGmj944oxlaKnqMF1QBE,4072
+ipdatainfo-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ipdatainfo-0.1.0.dist-info/licenses/LICENSE,sha256=gcy7wMqpZTLOLq72UJJIFZlChntabKWKYAE21GrjM1Y,1068
+ipdatainfo-0.1.0.dist-info/RECORD,,

ipdatainfo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ipdatainfo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ipdata.info
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.