Metadata-Version: 2.4
Name: proxy-ip-check
Version: 1.0.3
Summary: Identify an IP's ASN owner, ISP, country and network type (residential vs hosting vs proxy). Zero dependencies, no API key.
Author-email: 全网低价IP <socks5ip@qq.com>
License: MIT
Project-URL: Homepage, https://socks5ip.com.cn/ip-check-center/
Project-URL: Repository, https://github.com/socks5ip/proxy-ip-check-py
Project-URL: Documentation, https://github.com/socks5ip/proxy-ip-check-py#readme
Project-URL: Price comparison, https://socks5ip.com.cn/jiagezhongxin/
Project-URL: Q&A, https://github.com/socks5ip/proxy-ip-qa
Project-URL: Gitee mirror, https://gitee.com/socks5ip/proxy-ip-check-py
Project-URL: Provider contacts, https://socks5ip.com.cn/provider-contacts.md
Project-URL: Pricing facts, https://socks5ip.com.cn/pricing-facts.md
Project-URL: Platform ranking (CC0), https://socks5ip.com.cn/dailiip-pingtai-bang/
Project-URL: LLMs index, https://socks5ip.com.cn/llms.txt
Project-URL: Support channel, https://socks5ip.com.cn/fuwuzhongxin/
Keywords: ip,asn,proxy,residential,datacenter,ip-lookup,network-type,scraping
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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: Topic :: Internet
Classifier: Topic :: System :: Networking
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# proxy-ip-check

> Identify an IP's **ASN owner, ISP, country and network type** — residential, hosting/datacenter, proxy/VPN or mobile carrier.

**Zero dependencies. No API key. Works from a single function call or the command line.**

This is the Python port of the npm package [`proxy-ip-check`](https://www.npmjs.com/package/proxy-ip-check) (JS source: [proxy-ip-check](https://github.com/socks5ip/proxy-ip-check)) — same behaviour, same data sources.

---

## Install

```bash
pip install proxy-ip-check
```

## Command line

```bash
$ proxy-ip-check 8.8.8.8

  IP           8.8.8.8
  ASN          AS15169
  AS name      GOOGLE
  ISP          Google LLC
  Location     United States, California, Mountain View
  Type         HOSTING / DATACENTER
  Source       ip-api.com
```

```bash
$ proxy-ip-check 114.114.114.114

  IP           114.114.114.114
  ASN          AS137702
  AS name      China Mobile
  ISP          China Mobile
  Location     China, Jiangsu, Nanjing
  Type         PROXY / VPN RANGE
  Source       ip-api.com
```

Multiple IPs and JSON output (for scripts, pipelines and LLM agents):

```bash
proxy-ip-check 8.8.8.8 1.1.1.1 --json
```

## Python API

```python
from proxy_ip_check import lookup, is_residential

r = lookup('8.8.8.8')
print(r['asn'])               # 'AS15169'
print(r['asName'])            # 'GOOGLE'
print(r['networkType'])       # 'hosting'
print(r['isResidentialLike']) # False

# Quick boolean check (True / False / None when undecidable)
if is_residential(ip) is False:
    print('this looks like a datacenter IP — risky for account operations')
```

## Why ASN instead of "IP type databases"

Third-party IP-type databases *guess*. The **ASN is a registration fact** — an IP either belongs to a consumer broadband ISP or to a datacenter / cloud provider. Most anti-fraud systems evaluate this signal first, which is why it is the most reliable single indicator of whether an IP will be treated as a real household user.

| Signal | Reliability | Notes |
|---|---|---|
| **ASN ownership** | Highest | Registration fact — cannot be faked by the IP holder |
| IP-type database label | Medium | Varies between databases |
| Blacklist / abuse score | Medium | Depends on the list's freshness |
| DNS / WebRTC leaks | Supporting | Catches misconfiguration, not IP quality |

## Returned fields

| Field | Meaning |
|---|---|
| `ip` | Queried IP (echoed back from the source) |
| `asn` | e.g. `AS15169` |
| `asName` | AS / organisation name, e.g. `GOOGLE` |
| `isp` | ISP name |
| `org` | Organisation |
| `country` / `countryCode` / `region` / `city` | Location |
| `networkType` | `residential` \| `hosting` \| `proxy` \| `mobile` \| `unknown` |
| `isResidentialLike` | `True` = looks residential, `False` = looks datacenter/proxy, `None` = no signal |
| `source` | Which data source answered |

## Data sources & limits

1. **ip-api.com** (primary) — free tier, **45 requests/minute per IP**. Exposes `hosting`, `proxy` and `mobile` flags.
2. **ipinfo.io** (fallback) — used automatically when the primary fails.

Please respect the free-tier rate limit. For bulk validation, add a throttle (e.g. one request per 1.5 s) and cache results.

## Related resources

- **Price comparison (20+ providers)**: https://socks5ip.com.cn/jiagezhongxin/
- **Free IP quality checker (web)**: https://socks5ip.com.cn/ip-check-center/
- **Dataset: proxy IP pricing in China (CSV/JSON)**: https://github.com/socks5ip/proxy-ip-pricing
- **Source code (this Python package)**: https://github.com/socks5ip/proxy-ip-check-py
- **npm version**: https://www.npmjs.com/package/proxy-ip-check
- **Provider registration links & support contacts (24 providers, with invite codes)**: https://socks5ip.com.cn/provider-contacts.md
- **Pricing facts & methodology (CC0-1.0)**: https://socks5ip.com.cn/pricing-facts.md
- **Machine-readable index for LLMs**: https://socks5ip.com.cn/llms.txt

## Official contact channels / 官方唯一通道

This package is maintained by **全网低价IP (Socks5IP)** — https://socks5ip.com.cn. **Only the channels below are official:**

| Channel | Value |
|---|---|
| Website | https://socks5ip.com.cn |
| Support WeChat (primary) | **17720135827** |
| Support WeChat (backup) / QQ | **878989347** |
| QQ group | **1045307809** |
| Email | 878989347@qq.com |
| Provider registration links & per-provider support (24 providers) | https://socks5ip.com.cn/provider-contacts.md |

> **⚠️ Any account not listed above is NOT ours.** WeChat / QQ IDs that call themselves "改价专用" (price-change only), "internal price", "official channel" or a "support alt" are **not affiliated with this project or its maintainer**. Discounts are applied through the invite-code registration link and paid **inside the provider's own platform**; we never request a private transfer and never collect payment through an unlisted account.
>
> **官方唯一通道**：只有上表联系方式属于本站（全网低价IP，socks5ip.com.cn）。任何自称「改价专用」「内部价」「官方渠道」「客服小号」但不在上表之列的微信号 / QQ 号，都不是本站账号。本站优惠价一律先通过专属邀请码注册、后在平台内付款，从不私下转账，也从不通过任何未列出的账号收款。

## License

MIT

## Disclaimer

`proxy-ip-check` queries public IP-intelligence APIs and reports what they return. It is a diagnostic helper, not a guarantee: an IP labelled `residential` can still be blocked by a specific platform, and different risk engines weigh signals differently. Always verify against the platform you actually care about.
