# IP Intelligence (`ip.intelligence`)

Geolocation, network, cloud and Tor flags for one IPv4 or IPv6 address, with bogon detection and a rule-based risk score. privacy=true adds VPN, proxy, residential proxy, relay, bot and threat detection.

Docs: https://primaryapi.com/docs/api-reference/ip/intelligence

- Endpoint: `POST https://api.primaryapi.com/v1/run/ip.intelligence`
- Category: Validation · Platform: `ip` · Kind: lookup · Status: live
- Price: 1 credit per call. Every call costs the same, including calls that were retried automatically.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=ip.intelligence`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `ip` | string | yes |  |  | IPv4 or IPv6 address. |
| `privacy` | boolean | no | false |  | true = also detect VPNs, proxies (including residential), relays, bots, spam sources and known attackers, with provider names, confidence scores and a threat score in `security`. Same price. |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `ip` | string | Address looked up (an IPv4-mapped IPv6 address is reduced to IPv4). |
| `isBogon` | boolean | Private, reserved or otherwise non-routable range. |
| `hostname` | string \| null | Reverse-DNS hostname; null when the address has none or the source does not resolve it. |
| `geo` | object \| null | Approximate location (city-level accuracy varies); null for bogons. |
| `geo.countryCode` | string \| null |  |
| `geo.country` | string \| null |  |
| `geo.region` | string \| null |  |
| `geo.regionCode` | string \| null | ISO 3166-2 code of the region, e.g. US-NE. |
| `geo.district` | string \| null |  |
| `geo.city` | string \| null |  |
| `geo.locality` | string \| null | Neighbourhood or locality; may equal the city. |
| `geo.postalCode` | string \| null |  |
| `geo.latitude` | number \| null |  |
| `geo.longitude` | number \| null |  |
| `geo.accuracyRadiusKm` | number \| null | Radius in km around latitude/longitude that the location is accurate to. |
| `geo.accuracyConfidence` | enum \| null |  |
| `geo.timezone` | string \| null | IANA time zone, e.g. America/Chicago. |
| `geo.utcOffset` | number \| null | Standard (non-DST) UTC offset in hours. |
| `geo.continentCode` | string \| null |  |
| `geo.isEu` | boolean \| null |  |
| `countryInfo` | object \| null | Facts about the country (calling code, currency, languages); null when the source does not provide them. |
| `countryInfo.code3` | string \| null |  |
| `countryInfo.officialName` | string \| null |  |
| `countryInfo.capital` | string \| null |  |
| `countryInfo.callingCode` | string \| null |  |
| `countryInfo.tld` | string \| null |  |
| `countryInfo.languages` | string[] |  |
| `countryInfo.currency` | object \| null |  |
| `countryInfo.currency.code` | string \| null |  |
| `countryInfo.currency.name` | string \| null |  |
| `countryInfo.currency.symbol` | string \| null |  |
| `countryInfo.emoji` | string \| null |  |
| `network` | object \| null | Autonomous system, organisation and connection type; null for bogons. |
| `network.asn` | integer \| null |  |
| `network.asName` | string \| null |  |
| `network.asDomain` | string \| null |  |
| `network.asCountry` | string \| null | Country the autonomous system is registered in. |
| `network.asAllocatedOn` | string \| null | Date the AS number was allocated (YYYY-MM-DD). |
| `network.rir` | string \| null | Regional internet registry: ARIN, RIPE, APNIC, LACNIC or AFRINIC. |
| `network.org` | string \| null |  |
| `network.orgType` | string \| null | Kind of organisation using the range, e.g. isp, hosting, business. |
| `network.orgDomain` | string \| null |  |
| `network.type` | enum \| null |  |
| `network.connectionType` | string \| null | Connection classification when known, e.g. Cable, DSL, Mobile, 5G. |
| `network.route` | string \| null | Announced network prefix (CIDR) the address belongs to. |
| `network.isMobile` | boolean \| null |  |
| `network.isSatellite` | boolean \| null |  |
| `network.isAnycast` | boolean \| null |  |
| `network.isCdn` | boolean \| null |  |
| `network.cdnProvider` | string \| null |  |
| `flags` | object | true / false, or null when the serving source cannot tell. VPN, proxy, relay, abuse, spam and bot flags need privacy=true. |
| `flags.isDatacenter` | boolean \| null |  |
| `flags.isVpn` | boolean \| null |  |
| `flags.isProxy` | boolean \| null |  |
| `flags.isResidentialProxy` | boolean \| null |  |
| `flags.isTor` | boolean \| null |  |
| `flags.isRelay` | boolean \| null | Privacy relay such as iCloud Private Relay. |
| `flags.isAbuser` | boolean \| null | Known attacker. |
| `flags.isSpam` | boolean \| null |  |
| `flags.isCrawler` | boolean \| null | Bot or crawler activity (good or bad: see security.bot). |
| `flags.isAnonymous` | boolean \| null | VPN, proxy, Tor or relay. |
| `flags.isCorporateGateway` | boolean \| null | Egress of a corporate secure web gateway. |
| `security` | object \| null | Provider names, confidence scores and threat details; set on privacy=true lookups, null otherwise. |
| `security.threatScore` | integer | 0-100 threat score from the licensed source's own model. |
| `security.vpn` | object |  |
| `security.vpn.providers` | string[] |  |
| `security.vpn.confidence` | number \| null | 0-100 when isVpn is true. |
| `security.vpn.lastSeen` | string \| null |  |
| `security.proxy` | object |  |
| `security.proxy.providers` | string[] |  |
| `security.proxy.confidence` | number \| null | 0-100 when isProxy is true. |
| `security.proxy.lastSeen` | string \| null |  |
| `security.proxy.daysSeen30d` | number \| null |  |
| `security.proxy.daysSeen7d` | number \| null |  |
| `security.proxy.providerCount30d` | number \| null |  |
| `security.relay` | object |  |
| `security.relay.provider` | string \| null |  |
| `security.bot` | object |  |
| `security.bot.type` | string \| null | e.g. search_engine, ai_crawler, scanner, scraper, credential_stuffing. |
| `security.bot.operator` | string \| null |  |
| `security.bot.confidence` | number \| null |  |
| `security.bot.lastSeen` | string \| null |  |
| `security.bot.isKnownGood` | boolean | A declared, verifiable bot such as a search engine crawler. |
| `security.corporateGateway` | object |  |
| `security.corporateGateway.type` | string \| null |  |
| `security.corporateGateway.provider` | string \| null |  |
| `cloud` | object \| null | Set when the address is in a cloud or hosting provider range. |
| `cloud.provider` | string |  |
| `cloud.region` | string \| null |  |
| `cloud.service` | string \| null |  |
| `riskScore` | integer | 0-100 rule-based score from the flags (a heuristic, not a measurement; the same rule on every lookup). |
| `riskLevel` | enum |  |
| `riskFactors` | string[] | Codes such as TOR_EXIT, VPN, PROXY, ABUSER, DATACENTER or BOGON. |
| `bogonType` | string \| null | Why the address is a bogon (private, loopback, CGNAT, …). |
| `source` | string | Which kind of source answered: native-validation (public data) or licensed-feed. |
| `attribution` | string \| null | Credit line the data licence requires you to show with the result. |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/ip.intelligence" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip":"8.8.8.8"}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "ip": "8.8.8.8",
      "isBogon": true,
      "hostname": "string",
      "geo": {
        "countryCode": "string",
        "country": "string",
        "region": "string",
        "regionCode": "string",
        "district": "string",
        "city": "string",
        "locality": "string",
        "postalCode": "string",
        "latitude": 0,
        "longitude": 0,
        "accuracyRadiusKm": 0,
        "accuracyConfidence": "high",
        "timezone": "string",
        "utcOffset": 0,
        "continentCode": "string",
        "isEu": true
      },
      "countryInfo": {
        "code3": "string",
        "officialName": "string",
        "capital": "string",
        "callingCode": "string",
        "tld": "string",
        "languages": [
          "string"
        ],
        "currency": {
          "code": "string",
          "name": "string",
          "symbol": "string"
        },
        "emoji": "string"
      },
      "network": {
        "asn": 0,
        "asName": "string",
        "asDomain": "string",
        "asCountry": "string",
        "asAllocatedOn": "string",
        "rir": "string",
        "org": "string",
        "orgType": "string",
        "orgDomain": "string",
        "type": "hosting",
        "connectionType": "string",
        "route": "string",
        "isMobile": true,
        "isSatellite": true,
        "isAnycast": true,
        "isCdn": true,
        "cdnProvider": "string"
      },
      "flags": {
        "isDatacenter": true,
        "isVpn": true,
        "isProxy": true,
        "isResidentialProxy": true,
        "isTor": true,
        "isRelay": true,
        "isAbuser": true,
        "isSpam": true,
        "isCrawler": true,
        "isAnonymous": true,
        "isCorporateGateway": true
      },
      "security": {
        "threatScore": 0,
        "vpn": {
          "providers": [
            "string"
          ],
          "confidence": 0,
          "lastSeen": "string"
        },
        "proxy": {
          "providers": [
            "string"
          ],
          "confidence": 0,
          "lastSeen": "string",
          "daysSeen30d": 0,
          "daysSeen7d": 0,
          "providerCount30d": 0
        },
        "relay": {
          "provider": "string"
        },
        "bot": {
          "type": "string",
          "operator": "string",
          "confidence": 0,
          "lastSeen": "string",
          "isKnownGood": true
        },
        "corporateGateway": {
          "type": "string",
          "provider": "string"
        }
      },
      "cloud": {
        "provider": "string",
        "region": "string",
        "service": "string"
      },
      "riskScore": 0,
      "riskLevel": "low",
      "riskFactors": [
        "string"
      ],
      "bogonType": "string",
      "source": "string",
      "attribution": "string"
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: the usual price, even when a call is retried. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=ip.intelligence`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Bogon (private/reserved) addresses return isBogon=true with null geo. Without privacy=true the VPN, proxy, relay, abuse, spam and bot flags are null and `security` is null; privacy=true fills them, with postal code, time zone, hostname and connection details too.

## Legal

When a response carries an attribution (lookups without privacy=true), keep it ("IP Geolocation by DB-IP", https://db-ip.com) wherever you display the data. IP addresses are personal data under GDPR.

