# IP Trust API

> IP intelligence API for IPv4 and IPv6 addresses. Returns geolocation, ASN, company, hosting detection, bot detection, VPN/proxy/Tor detection, and risk scoring.

## Authentication

Pass your API key in the `X-API-Key` request header. Get your key from the [IP Trust Dashboard](https://dashboard.iptrust.co/).

## Endpoint

```
GET https://api.iptrust.co/ip/{ip_address}
```

`{ip_address}` is a valid IPv4 or IPv6 address.

### Example request (cURL)

```bash
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.iptrust.co/ip/9.9.9.9" | jq .
```

### Example request (Python)

```python
import requests

response = requests.get(
    "https://api.iptrust.co/ip/9.9.9.9",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())
```

## Response Codes

| Code | Description |
|------|-------------|
| 200  | Successful lookup. Response body contains the IP intelligence JSON object. |
| 400  | Bad request. The IP address is missing or not a valid IPv4/IPv6 address. |
| 401  | Unauthorized. The API key is missing or invalid. |
| 403  | Forbidden. Your API key does not have access to this resource. |
| 429  | Rate limited. You have exceeded your plan's request quota or rate limit. |
| 500  | Internal server error. Please retry or contact support. |

## Response Body

A successful `200` response returns a JSON object. The fields you receive depend on your plan (Essential, Plus, or Premium). Higher-tier plans include all fields from lower tiers.

### Top-level fields

| Field | Type | Plans | Description |
|-------|------|-------|-------------|
| `ip` | string | Essential, Plus, Premium | The queried IP address, echoed back. |
| `is_bogon` | boolean | Essential, Plus, Premium | Whether the IP belongs to a bogon (unroutable/reserved) range. |

### `asn` object

| Field | Type | Plans | Description |
|-------|------|-------|-------------|
| `asn.number` | string | Essential, Plus, Premium | The Autonomous System Number (e.g. "AS8075"). |
| `asn.name` | string | Essential, Plus, Premium | Registered name of the AS as listed by the RIR. |
| `asn.company` | string | Essential, Plus, Premium | Legal organisation name that owns the AS. |
| `asn.country` | string | Essential, Plus, Premium | ISO 3166-1 alpha-2 country code where the AS is registered. |
| `asn.route` | string | Essential, Plus, Premium | Most-specific BGP route prefix containing this IP. |
| `asn.rir` | string | Essential, Plus, Premium | Regional Internet Registry (e.g. ARIN, RIPE, APNIC). |
| `asn.domain` | string (optional) | Essential, Plus, Premium | Primary domain associated with the AS owner. |
| `asn.type` | string (optional) | Plus, Premium | AS classification: `isp`, `hosting`, `business`, `government`, or `education`. |
| `asn.description` | string (optional) | Plus, Premium | Human-readable description of the AS owner organisation. |
| `asn.risk` | number (optional) | Premium | Risk score from 0.0 (very low) to 1.0 (very high), based on Friendly Captcha threat signals. |
| `asn.risk_label` | string (optional) | Premium | Risk level: `very_low`, `low`, `moderate`, `high`, or `very_high`. |
| `asn.risk_types` | array of strings (optional) | Premium | Risk signal categories: `confirmed_bot`, `suspected_bot`, `traffic_volume`, `repeated_abuse`, `targeted_abuse`. |

### `location` object

| Field | Type | Plans | Description |
|-------|------|-------|-------------|
| `location.city` | string | Essential, Plus, Premium | City-level location. |
| `location.state` | string | Essential, Plus, Premium | State, province, or top-level administrative region. |
| `location.country` | string | Essential, Plus, Premium | Full country name. |
| `location.latitude` | number | Essential, Plus, Premium | Approximate latitude (WGS84). |
| `location.longitude` | number | Essential, Plus, Premium | Approximate longitude (WGS84). |

### `location.meta` object

| Field | Type | Plans | Description |
|-------|------|-------|-------------|
| `location.meta.country_iso2` | string | Essential, Plus, Premium | ISO 3166-1 alpha-2 code. |
| `location.meta.country_iso3` | string | Essential, Plus, Premium | ISO 3166-1 alpha-3 code. |
| `location.meta.country_numeric_code` | string | Essential, Plus, Premium | ISO 3166-1 numeric code. |
| `location.meta.country_phone_code` | string | Essential, Plus, Premium | International dialling code. |
| `location.meta.country_capital` | string | Essential, Plus, Premium | Capital city. |
| `location.meta.country_currency` | string | Essential, Plus, Premium | ISO 4217 currency code. |
| `location.meta.country_currency_name` | string | Essential, Plus, Premium | Full currency name. |
| `location.meta.country_native` | string | Essential, Plus, Premium | Country name in local language. |
| `location.meta.country_region` | string | Essential, Plus, Premium | UN geographic macro-region. |
| `location.meta.country_subregion` | string | Essential, Plus, Premium | UN geographic sub-region. |
| `location.meta.country_emoji` | string | Essential, Plus, Premium | Country flag emoji. |
| `location.meta.country_emoji_u` | string | Essential, Plus, Premium | Country flag as Unicode code points. |

### `company` object (Plus, Premium)

| Field | Type | Description |
|-------|------|-------------|
| `company.name` | string | Legal name of the company operating at this IP. |
| `company.type` | string (optional) | Classification: `isp`, `business`, `hosting`, `government`, or `education`. |
| `company.domain` | string (optional) | Primary website domain. |
| `company.description` | string (optional) | Brief description of the company. |

### `known_bot` object (Plus, Premium)

| Field | Type | Description |
|-------|------|-------------|
| `known_bot.detected` | boolean | Whether a known bot or crawler was detected. |
| `known_bot.bot_type` | string (optional) | Category: `crawler`, `ai`, or `other`. |
| `known_bot.name` | string (optional) | Bot identifier. See list below. |

Known bot names: `ahrefs_bot`, `amazon_bot`, `amazon_user_bot`, `anthropic`, `apple_bot`, `bing_bot`, `chatgpt_user`, `common_crawl_bot`, `duckduck_bot`, `google_bot`, `google_special_crawlers`, `google_user_fetch`, `google_user_fetch_google`, `gpt_bot`, `kagi_bot`, `openai_search_bot`, `perplexity_crawler`, `perplexity_user`, `pingdom_ipv4`, `pingdom_ipv6`, `yandex`.

### `hosting` object (Plus, Premium)

| Field | Type | Description |
|-------|------|-------------|
| `hosting.detected` | boolean | Whether the IP belongs to a known hosting/cloud provider. |
| `hosting.domain` | string (optional) | Website domain of the hosting provider. |
| `hosting.name` | string (optional) | Name of the hosting or cloud provider. |

### `abuse_contact` object (Premium)

| Field | Type | Description |
|-------|------|-------------|
| `abuse_contact.address` | string (optional) | Physical mailing address for abuse contact. |
| `abuse_contact.email` | string (optional) | Email for reporting abuse from this network. |
| `abuse_contact.name` | string (optional) | Name of the abuse contact person or team. |

### `tor_exit_node` object (Premium)

| Field | Type | Description |
|-------|------|-------------|
| `tor_exit_node.detected` | boolean | Whether this IP is a known Tor exit node. |

### `privacy_relay` object (Premium)

| Field | Type | Description |
|-------|------|-------------|
| `privacy_relay.detected` | boolean | Whether the IP is part of a commercial privacy relay service. |
| `privacy_relay.provider` | string (optional) | Provider identifier (e.g. `icloud_private_relay`). |

### `proxy` object (Premium)

| Field | Type | Description |
|-------|------|-------------|
| `proxy.detected` | boolean | Whether this IP is a detected proxy server. |
| `proxy.type` | string (optional) | Proxy type: `residential` or `open`. |
| `proxy.last_detected` | string (optional) | ISO 8601 date when proxy activity was last observed. |

### `vpn` object (Premium)

| Field | Type | Description |
|-------|------|-------------|
| `vpn.detected` | boolean | Whether this IP is part of a VPN service. |
| `vpn.provider` | string (optional) | VPN provider identifier (e.g. `nord_vpn`). |
| `vpn.last_detected` | string (optional) | ISO 8601 date when VPN activity was last observed. |

## Example Response

```json
{
  "ip": "74.148.39.34",
  "is_bogon": false,
  "asn": {
    "number": "AS8075",
    "name": "MICROSOFT-CORP-MSN-AS-BLOCK",
    "company": "Microsoft Corporation",
    "country": "US",
    "route": "74.144.0.0/12",
    "rir": "ARIN",
    "domain": "www.microsoft.com",
    "type": "hosting",
    "description": "Provides consumer and enterprise software...",
    "risk": 0.9,
    "risk_label": "very_high",
    "risk_types": ["request_frequency", "repeated_abuse"]
  },
  "location": {
    "city": "Barcelona",
    "state": "Barcelona",
    "country": "Spain",
    "latitude": 41.389,
    "longitude": 2.159,
    "meta": {
      "country_iso2": "ES",
      "country_iso3": "ESP",
      "country_numeric_code": "724",
      "country_phone_code": "34",
      "country_capital": "Madrid",
      "country_currency": "EUR",
      "country_currency_name": "Euro",
      "country_native": "Espana",
      "country_region": "Europe",
      "country_subregion": "Southern Europe",
      "country_emoji": "🇪🇸",
      "country_emoji_u": "U+1F1EA U+1F1F8"
    }
  },
  "company": {
    "name": "mawa-solutions GmbH",
    "type": "business",
    "domain": "www.mawa-solutions.com",
    "description": "Provides SAP-based time-tracking..."
  },
  "known_bot": {
    "detected": true,
    "bot_type": "ai",
    "name": "chatgpt_user"
  },
  "hosting": {
    "detected": true,
    "domain": "www.microsoft.com",
    "name": "Microsoft Limited"
  },
  "abuse_contact": {
    "address": "One Microsoft Way, Redmond, WA 98052",
    "email": "abuse@microsoft.com",
    "name": "Microsoft Abuse Contact"
  },
  "tor_exit_node": {
    "detected": true
  },
  "privacy_relay": {
    "detected": true,
    "provider": "icloud_private_relay"
  },
  "proxy": {
    "detected": true,
    "type": "residential",
    "last_detected": "2025-11-15"
  },
  "vpn": {
    "detected": true,
    "provider": "nord_vpn",
    "last_detected": "2025-11-15"
  }
}
```

## Plans

- **Essential** - Core IP data: geolocation, ASN, bogon detection, country metadata.
- **Plus** - Adds company info, AS type, hosting detection, known bot detection.
- **Premium** - Adds risk scoring, abuse contact, Tor exit node, privacy relay, proxy, and VPN detection.

## Links

- [Dashboard](https://dashboard.iptrust.co/)
- [Full HTML Documentation](https://iptrust.co/docs/)
- [Website](https://iptrust.co/)