# 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: IP Lookup

```
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.resolution` | string | Essential, Plus, Premium | Precision of the location data: `city`, `state`, or `country`. A `country` resolution means the city and state fields may be empty. |
| `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": {
    "resolution": "city",
    "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"
  }
}
```

## Database Downloads

Databases are also published as downloadable files, for customers whose plan includes database
downloads. Downloading is a two-step process: request a signed link, then fetch it. Downloads do
not count towards your monthly API request quota.

### Endpoint: GET /database

Lists the databases available for download, the formats they are published in, their file sizes,
and when each was last updated. All databases are listed regardless of your plan; the `entitled`
field indicates which ones you can download.

```
GET https://api.iptrust.co/database
```

#### Example request (cURL)

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

#### Example request (Python)

```python
import requests

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

#### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `databases[].type` | string | Database identifier: `asn`, `company`, `geolocation`, `abusecontact`, `knownbots`, `hosting`, `anonymization`. |
| `databases[].entitled` | boolean | Whether your plan includes downloads of this database. |
| `databases[].updated_at` | string | ISO 8601 timestamp (UTC) of the most recently refreshed file for this database. |
| `databases[].formats[].format` | string | `mmdb` (MaxMind DB, readable by any standard MMDB library) or `csv` (gzipped CSV export). |
| `databases[].formats[].size_bytes` | integer | File size in bytes as published. For `csv` this is the compressed size. |
| `databases[].formats[].updated_at` | string | ISO 8601 timestamp (UTC) when this file was published. |

#### Example response

```json
{
  "databases": [
    {
      "type": "geolocation",
      "entitled": true,
      "updated_at": "2026-08-24T03:12:44Z",
      "formats": [
        {
          "format": "mmdb",
          "size_bytes": 91234567,
          "updated_at": "2026-08-24T03:12:44Z"
        },
        {
          "format": "csv",
          "size_bytes": 41234567,
          "updated_at": "2026-08-24T03:12:44Z"
        }
      ]
    },
    {
      "type": "anonymization",
      "entitled": false,
      "updated_at": "2026-08-24T03:14:02Z",
      "formats": [
        {
          "format": "mmdb",
          "size_bytes": 12345678,
          "updated_at": "2026-08-24T03:14:02Z"
        }
      ]
    }
  ]
}
```

#### Response codes

| Code | Description |
|------|-------------|
| 200  | Successful. Response body contains the list of available databases. |
| 401  | Unauthorized. The API key is missing or invalid. |
| 500  | Internal server error. Please retry or contact support. |

### Endpoint: POST /database/download

Generates a temporary signed URL for downloading a single database file. The signed URL requires no
API key of its own, so it can be passed straight to `curl`, `wget`, or other download tooling.

```
POST https://api.iptrust.co/database/download
```

#### Request body

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Required. The database to download, as returned by `GET /database` (e.g. `geolocation`). |
| `format` | string | Required. Either `mmdb` or `csv`. |

#### Example request (cURL)

```bash
curl -s -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "geolocation", "format": "mmdb"}' \
  "https://api.iptrust.co/database/download" | jq .
```

#### Example request (Python)

```python
import requests

response = requests.post(
    "https://api.iptrust.co/database/download",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "geolocation", "format": "mmdb"}
)
download = response.json()

# Fetch the file itself from the signed URL - no API key required.
with requests.get(download["url"], stream=True) as file_response:
    with open(download["filename"], "wb") as output:
        for chunk in file_response.iter_content(chunk_size=1024 * 1024):
            output.write(chunk)
```

#### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | The database the link is for. |
| `format` | string | The format the link is for. |
| `filename` | string | Suggested filename for the downloaded file. |
| `url` | string | Signed download URL. Fetch this directly to download the file. |
| `size_bytes` | integer | File size in bytes. |
| `updated_at` | string | ISO 8601 timestamp (UTC) when the file was published. |
| `expires_at` | string | ISO 8601 timestamp (UTC) after which the signed URL stops working. |

#### Example response

```json
{
  "type": "geolocation",
  "format": "mmdb",
  "filename": "iptrust-geolocation.mmdb",
  "url": "https://files.iptrust.co/latest/iptrust-geolocation.mmdb?X-Amz-Algorithm=...",
  "size_bytes": 91234567,
  "updated_at": "2026-08-24T03:12:44Z",
  "expires_at": "2026-08-24T11:41:09Z"
}
```

#### Downloading the file

```bash
curl -L -o iptrust-geolocation.mmdb "<url from the response>"
```

#### Link lifetime

Signed URLs are valid for one hour from the moment they are issued, as given by `expires_at`.
Requesting the same database and format again within roughly half that window returns the link
already in flight rather than minting a new one, so treat `expires_at` as authoritative and begin
the download promptly. Anyone holding the link can download the file until it expires, so treat it
as a credential. Once it expires, request a new one.

Databases are refreshed regularly, and the signed URL always resolves to the newest published file
for that database and format.

#### Response codes

| Code | Description |
|------|-------------|
| 200  | Successful. Response body contains the signed download URL. |
| 400  | Bad request. The body is malformed, or `type` or `format` is missing or unrecognised. |
| 401  | Unauthorized. The API key is missing or invalid. |
| 403  | Forbidden. Your plan does not include downloads of this database. |
| 404  | Not found. The requested database is not currently published in that format. |
| 500  | Internal server error. Please retry or contact support. |

## 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/)