# GetIPIntel

> GetIPIntel is a free, fast, and remarkably accurate IP intelligence to detect proxies, VPNs, hosting providers, TOR exit nodes, and bad IPs using machine learning and probability theory. Returns a score from `0` to `1` that tells you how suspicious an IP address is. The API is trivial to integrate and includes **residential proxy detection** (`oflags=r`). Use it to fight fraud, block abuse, stop fake sign-ups, protect content, and prevent automated attacks.

## Quick Facts

- **Pricing:** Completely free for up to 500 queries/day and 15 queries/minute. Custom paid plans are available if you need more.
- **Core Idea:** Given an IP address, the service returns a score `0` to `1`. A score of `1` means the IP is **explicitly banned** (web host, VPN, or TOR node). Scores between `0` and `1` are inferred through machine learning and dynamic checks.
- **Residential Proxy Detection:** Append `&oflags=r` to any request to include residential proxy intelligence from Layer3Intel. The JSON response will include a `ResidentialProxy` score (0-1). This feature is currently in beta and supports IPv4.
- **Scale:** The system serves millions of API requests per week and is used by gaming communities, e-commerce sites, universities, law enforcement, and large financial institutions.

## When to Use It

- **Prevent Fraud** - Block fraudulent transactions and protect payment gateways.
- **Stop Abuse** - Prevent promo code abuse, multiple sign-ups, affiliate fraud, and spam.
- **Protect Content** - Stop crawlers, scrapers, and content thieves.
- **Harden Security** - Block XSS, SQLi, brute force, and other automated attacks.
- **Eliminate Fake Activity** - Reduce fake clicks, views, and ad fraud.
- **Enforce Bans** - Stop trolls and users who try to bypass bans with proxies or VPNs.

## API Basics

| Element | Detail |
|---------|--------|
| **Endpoint** | `http://check.getipintel.net/check.php` |
| **Method** | `GET` (pass parameters as query string) |
| **Required params** | `ip` - the IP to check (IPv4 fully supported, IPv6 partial)<br>`contact` - your email address (no URL-encoding) |
| **Optional params** | `flags` - lookup mode (`m`, `b`, `f`, `n`)<br>`oflags` - extra output (`b`, `c`, `i`, `a`, `r`)<br>`format` - set to `json` for structured output |
| **Response** | Plain text: a number `0`-`1` (success) or a negative number (error)<br>JSON: object with `status`, `result`, and extra fields |

## Flag Reference

### Lookup Modes (`flags`)
| Flag | Description | Response time | Best for |
|------|-------------|---------------|----------|
| `flags=m` | Dynamic ban lists only (fastest, fewest false positives) | <60 ms | Starting point; only care about known proxies/VPNs |
| `flags=b` | Dynamic ban lists + dynamic checks + partial bad-IP check | <130 ms | Catching more proxies without the full bad-IP check |
| *(no flag)* | Default full check (background jobs may require a second query) | <130 ms | Balance of speed and completeness |
| `flags=f` | Force full lookup (waits for all checks) | up to 5 s | Non-real-time applications; most thorough |
| Append `n` | Exclude real-time block list (e.g., `flags=nm`) | - | When you want to skip the real-time list |

### Extra Output (`oflags`)
| Flag | What it adds | Output |
|------|--------------|--------|
| `oflags=b` | Bad IP flag | `0` or `1` (JSON: `"BadIP"`) |
| `oflags=c` | Country (ISO-3166 format) | `"US"`, `"DE"`, etc. (JSON: `"Country"`) |
| `oflags=i` | iCloud Relay / Google One VPN detection | JSON: `"iCloudRelayEgress"`, `"GoogleOneVPN"`, `"VPNType"` |
| `oflags=a` | ASN number(s) | JSON: `"ASN"` |
| `oflags=r` | Residential proxy detection | JSON: `"ResidentialProxy"` score 0-1 |

## Interpreting the Score

- **> 0.99** - Almost certainly a proxy/VPN. Automated blocking is usually safe.
- **0.95 - 0.99** - Very suspicious; manual review recommended.
- **0.90 - 0.95** - Possibly a proxy; investigate further.
- **< 0.90** - Low risk.

For most use-cases, only act on scores **> 0.99** or **> 0.995**. Always test with your own traffic first.

## Code Examples

### cURL (basic)
    curl "http://check.getipintel.net/check.php?ip=66.228.119.72&contact=you@example.com"
    # Returns a number, e.g.: 1

### cURL with JSON and flags
    curl "http://check.getipintel.net/check.php?ip=66.228.119.72&contact=you@example.com&flags=m&format=json"

Response:
    {
      "status": "success",
      "result": "1",
      "queryIP": "66.228.119.72",
      "queryFlags": "m",
      "queryFormat": "json",
      "contact": "you@example.com"
    }

*(Example from the official API docs)*

### cURL with Residential Proxy Detection
    curl "http://check.getipintel.net/check.php?ip=66.228.119.72&contact=you@example.com&oflags=r&format=json"

The JSON response will include `"ResidentialProxy"` with a score from `0` to `1`.

### PHP
    $ip = '66.228.119.72';
    $contact = 'you@example.com';
    $url = "http://check.getipintel.net/check.php?ip=$ip&contact=$contact&flags=m&format=json";
    $response = file_get_contents($url);
    $data = json_decode($response, true);
    if ($data['status'] === 'success' && (float)$data['result'] > 0.99) {
        // Block or flag the IP
    }

### Python
    import requests

    url = "http://check.getipintel.net/check.php"
    params = {
        "ip": "66.228.119.72",
        "contact": "you@example.com",
        "flags": "m",
        "format": "json"
    }
    resp = requests.get(url, params=params)
    data = resp.json()
    if data["status"] == "success" and float(data["result"]) > 0.99:
        # Take action
        pass

### JavaScript (Node.js)
    const http = require('http'); // or 'https'

    http.get('http://check.getipintel.net/check.php?ip=66.228.119.72&contact=you@example.com&flags=m&format=json', (res) => {
      let body = '';
      res.on('data', chunk => body += chunk);
      res.on('end', () => {
        const data = JSON.parse(body);
        if (data.status === 'success' && parseFloat(data.result) > 0.99) {
          // Block or flag the IP
        }
      });
    });

## Error Codes

| Code | Meaning |
|------|---------|
| `-1` | No input provided |
| `-2` | Invalid IP address |
| `-3` | Unroutable / private address |
| `-4` | Database unreachable (likely being updated) |
| `-5` | Your IP is banned or you lack permission |
| `-6` | Missing or invalid contact email |

When rate-limited, the server returns HTTP `429`. Always implement exception handling for timeouts, `429`, and the negative error codes.

## Rate Limits & Caching

- **Free tier:** 500 queries/day, 15 queries/minute. Burst protection is in place.
- **Caching:** You may cache results, but do not cache a score for more than **6 hours**—the internet changes quickly.
- **Custom plans:** If you need higher limits, contact `getipintel@gmail.com`. Custom packages are usually much cheaper than competing paid services.

## Important Rules

1. **Always include a valid, monitored email** in the `contact` parameter. Queries without accurate contact info are rejected or dropped by the firewall.
2. **Do not URL-encode** the `ip` or `contact` parameters.
3. **Do not look up random IPs** or scan incrementally—the database updates constantly, so stale data wastes resources.
4. **Do not sell** the service or its data without explicit permission.
5. **Attribute** GetIPIntel if you reuse its data.
6. **Start with `flags=m`** when you only need proxy/VPN detection. It's the fastest option with the fewest false positives.

## Why It's Better Than Simple Block-List Services

Many services only check IPs against static block-lists. If an IP isn't on the list, they assume it's safe—a logical fallacy. GetIPIntel uses **machine learning and probability theory** to infer whether an IP is suspicious, even if it has never been seen before. Billions of new records are parsed each month, and old records automatically expire.

---

*Generated from the official documentation at [getipintel.net](https://getipintel.net) and the [API page](https://getipintel.net/free-proxy-vpn-tor-detection-api).*