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.
- Price per call
- 1 credit
- per successful call
- Price ceiling
- 1 credit
- every call, same price
- Failed calls
- Free
- retried automatically
- Billed
- Per call
- only on success
Endpoint
api.primaryapi.com/ v1/ run/ ip. intelligenceAuth: API key with run or full access, or a dashboard session
Send the input below as a JSON body. The call is routed to a healthy upstream; if an attempt fails, it is retried automatically inside the same request and you pay only for the answer you get. To check an input and see the exact price without running anything, call POST /v1/quote/ip.intelligence with the same body (free).
Example request
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"}'const res = await fetch('https://api.primaryapi.com/v1/run/ip.intelligence', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMARYAPI_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
ip: '8.8.8.8',
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.error}`);
// found:false is a successful answer ("does not exist"), not an error
console.log(body.output.found ? body.output.data : body.output.reason, body.credits);import os
import requests
res = requests.post(
"https://api.primaryapi.com/v1/run/ip.intelligence",
headers={"Authorization": f"Bearer {os.environ['PRIMARYAPI_API_KEY']}"},
json={
"ip": "8.8.8.8",
},
timeout=60,
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['code']}: {body['error']}")
# found=False is a successful answer ("does not exist"), not an error
print(body["output"]["data"] if body["output"]["found"] else body["output"]["reason"], body["credits"]){
"name": "run_api",
"arguments": {
"sku": "ip.intelligence",
"input": {
"ip": "8.8.8.8"
}
}
}Price this exact input first (free)
curl -sS -X POST "https://api.primaryapi.com/v1/quote/ip.intelligence" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ip":"8.8.8.8"}'Returns credits (what the call is expected to cost) and maxCredits (the most it can cost, which is set aside while it runs). Invalid input fails here the same way it would on run.
Input
JSON body fields. Unknown fields are rejected with 400 invalid_input (never silently ignored). You may add the routing controls preferLatencyUnderMs and maxCredits to the same object.
ipstringrequired- IPv4 or IPv6 address.
privacybooleandefaultfalse- 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.
Output
When output.found is true, output.data has these fields.
ipstring- Address looked up (an IPv4-mapped IPv6 address is reduced to IPv4).
isBogonboolean- Private, reserved or otherwise non-routable range.
hostnamestring | null- Reverse-DNS hostname; null when the address has none or the source does not resolve it.
geoobject | null- Approximate location (city-level accuracy varies); null for bogons.
geo.countryCodestring | nullgeo.countrystring | nullgeo.regionstring | nullgeo.regionCodestring | null- ISO 3166-2 code of the region, e.g. US-NE.
geo.districtstring | nullgeo.citystring | nullgeo.localitystring | null- Neighbourhood or locality; may equal the city.
geo.postalCodestring | nullgeo.latitudenumber | nullgeo.longitudenumber | nullgeo.accuracyRadiusKmnumber | null- Radius in km around latitude/longitude that the location is accurate to.
geo.accuracyConfidenceenum | null- one of: high, medium, low
geo.timezonestring | null- IANA time zone, e.g. America/Chicago.
geo.utcOffsetnumber | null- Standard (non-DST) UTC offset in hours.
geo.continentCodestring | nullgeo.isEuboolean | nullcountryInfoobject | null- Facts about the country (calling code, currency, languages); null when the source does not provide them.
countryInfo.code3string | nullcountryInfo.officialNamestring | nullcountryInfo.capitalstring | nullcountryInfo.callingCodestring | nullcountryInfo.tldstring | nullcountryInfo.languagesstring[]countryInfo.currencyobject | nullcountryInfo.currency.codestring | nullcountryInfo.currency.namestring | nullcountryInfo.currency.symbolstring | nullcountryInfo.emojistring | nullnetworkobject | null- Autonomous system, organisation and connection type; null for bogons.
network.asninteger | nullnetwork.asNamestring | nullnetwork.asDomainstring | nullnetwork.asCountrystring | null- Country the autonomous system is registered in.
network.asAllocatedOnstring | null- Date the AS number was allocated (YYYY-MM-DD).
network.rirstring | null- Regional internet registry: ARIN, RIPE, APNIC, LACNIC or AFRINIC.
network.orgstring | nullnetwork.orgTypestring | null- Kind of organisation using the range, e.g. isp, hosting, business.
network.orgDomainstring | nullnetwork.typeenum | null- one of: hosting, isp, business, education, government
network.connectionTypestring | null- Connection classification when known, e.g. Cable, DSL, Mobile, 5G.
network.routestring | null- Announced network prefix (CIDR) the address belongs to.
network.isMobileboolean | nullnetwork.isSatelliteboolean | nullnetwork.isAnycastboolean | nullnetwork.isCdnboolean | nullnetwork.cdnProviderstring | nullflagsobject- true / false, or null when the serving source cannot tell. VPN, proxy, relay, abuse, spam and bot flags need privacy=true.
flags.isDatacenterboolean | nullflags.isVpnboolean | nullflags.isProxyboolean | nullflags.isResidentialProxyboolean | nullflags.isTorboolean | nullflags.isRelayboolean | null- Privacy relay such as iCloud Private Relay.
flags.isAbuserboolean | null- Known attacker.
flags.isSpamboolean | nullflags.isCrawlerboolean | null- Bot or crawler activity (good or bad: see security.bot).
flags.isAnonymousboolean | null- VPN, proxy, Tor or relay.
flags.isCorporateGatewayboolean | null- Egress of a corporate secure web gateway.
securityobject | null- Provider names, confidence scores and threat details; set on privacy=true lookups, null otherwise.
security.threatScoreinteger- 0-100 threat score from the licensed source's own model.0–100
security.vpnobjectsecurity.vpn.providersstring[]security.vpn.confidencenumber | null- 0-100 when isVpn is true.
security.vpn.lastSeenstring | nullsecurity.proxyobjectsecurity.proxy.providersstring[]security.proxy.confidencenumber | null- 0-100 when isProxy is true.
security.proxy.lastSeenstring | nullsecurity.proxy.daysSeen30dnumber | nullsecurity.proxy.daysSeen7dnumber | nullsecurity.proxy.providerCount30dnumber | nullsecurity.relayobjectsecurity.relay.providerstring | nullsecurity.botobjectsecurity.bot.typestring | null- e.g. search_engine, ai_crawler, scanner, scraper, credential_stuffing.
security.bot.operatorstring | nullsecurity.bot.confidencenumber | nullsecurity.bot.lastSeenstring | nullsecurity.bot.isKnownGoodboolean- A declared, verifiable bot such as a search engine crawler.
security.corporateGatewayobjectsecurity.corporateGateway.typestring | nullsecurity.corporateGateway.providerstring | nullcloudobject | null- Set when the address is in a cloud or hosting provider range.
cloud.providerstringcloud.regionstring | nullcloud.servicestring | nullriskScoreinteger- 0-100 rule-based score from the flags (a heuristic, not a measurement; the same rule on every lookup).0–100
riskLevelenum- one of: low, medium, high, critical
riskFactorsstring[]- Codes such as TOR_EXIT, VPN, PROXY, ABUSER, DATACENTER or BOGON.
bogonTypestring | null- Why the address is a bogon (private, loopback, CGNAT, …).
sourcestring- Which kind of source answered: native-validation (public data) or licensed-feed.
attributionstring | null- Credit line the data licence requires you to show with the result.
TypeScript type
/** output.data when output.found is true */
type IpIntelligence = {
/** Address looked up (an IPv4-mapped IPv6 address is reduced to IPv4). */
ip: string;
/** Private, reserved or otherwise non-routable range. */
isBogon: boolean;
/** Reverse-DNS hostname; null when the address has none or the source does not resolve it. */
hostname: string | null;
/** Approximate location (city-level accuracy varies); null for bogons. */
geo: {
countryCode: string | null;
country: string | null;
region: string | null;
/** ISO 3166-2 code of the region, e.g. US-NE. */
regionCode: string | null;
district: string | null;
city: string | null;
/** Neighbourhood or locality; may equal the city. */
locality: string | null;
postalCode: string | null;
latitude: number | null;
longitude: number | null;
/** Radius in km around latitude/longitude that the location is accurate to. */
accuracyRadiusKm: number | null;
accuracyConfidence: "high" | "medium" | "low" | null;
/** IANA time zone, e.g. America/Chicago. */
timezone: string | null;
/** Standard (non-DST) UTC offset in hours. */
utcOffset: number | null;
continentCode: string | null;
isEu: boolean | null;
} | null;
/** Facts about the country (calling code, currency, languages); null when the source does not provide them. */
countryInfo: {
code3: string | null;
officialName: string | null;
capital: string | null;
callingCode: string | null;
tld: string | null;
languages: string[];
currency: {
code: string | null;
name: string | null;
symbol: string | null;
} | null;
emoji: string | null;
} | null;
/** Autonomous system, organisation and connection type; null for bogons. */
network: {
asn: number | null;
asName: string | null;
asDomain: string | null;
/** Country the autonomous system is registered in. */
asCountry: string | null;
/** Date the AS number was allocated (YYYY-MM-DD). */
asAllocatedOn: string | null;
/** Regional internet registry: ARIN, RIPE, APNIC, LACNIC or AFRINIC. */
rir: string | null;
org: string | null;
/** Kind of organisation using the range, e.g. isp, hosting, business. */
orgType: string | null;
orgDomain: string | null;
type: "hosting" | "isp" | "business" | "education" | "government" | null;
/** Connection classification when known, e.g. Cable, DSL, Mobile, 5G. */
connectionType: string | null;
/** Announced network prefix (CIDR) the address belongs to. */
route: string | null;
isMobile: boolean | null;
isSatellite: boolean | null;
isAnycast: boolean | null;
isCdn: boolean | null;
cdnProvider: string | null;
} | null;
/** 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;
isVpn: boolean | null;
isProxy: boolean | null;
isResidentialProxy: boolean | null;
isTor: boolean | null;
/** Privacy relay such as iCloud Private Relay. */
isRelay: boolean | null;
/** Known attacker. */
isAbuser: boolean | null;
isSpam: boolean | null;
/** Bot or crawler activity (good or bad: see security.bot). */
isCrawler: boolean | null;
/** VPN, proxy, Tor or relay. */
isAnonymous: boolean | null;
/** Egress of a corporate secure web gateway. */
isCorporateGateway: boolean | null;
};
/** Provider names, confidence scores and threat details; set on privacy=true lookups, null otherwise. */
security: {
/** 0-100 threat score from the licensed source's own model. */
threatScore: number;
vpn: {
providers: string[];
/** 0-100 when isVpn is true. */
confidence: number | null;
lastSeen: string | null;
};
proxy: {
providers: string[];
/** 0-100 when isProxy is true. */
confidence: number | null;
lastSeen: string | null;
daysSeen30d: number | null;
daysSeen7d: number | null;
providerCount30d: number | null;
};
relay: {
provider: string | null;
};
bot: {
/** e.g. search_engine, ai_crawler, scanner, scraper, credential_stuffing. */
type: string | null;
operator: string | null;
confidence: number | null;
lastSeen: string | null;
/** A declared, verifiable bot such as a search engine crawler. */
isKnownGood: boolean;
};
corporateGateway: {
type: string | null;
provider: string | null;
};
} | null;
/** Set when the address is in a cloud or hosting provider range. */
cloud: {
provider: string;
region: string | null;
service: string | null;
} | null;
/** 0-100 rule-based score from the flags (a heuristic, not a measurement; the same rule on every lookup). */
riskScore: number;
riskLevel: "low" | "medium" | "high" | "critical";
/** Codes such as TOR_EXIT, VPN, PROXY, ABUSER, DATACENTER or BOGON. */
riskFactors: string[];
/** Why the address is a bogon (private, loopback, CGNAT, …). */
bogonType: string | null;
/** Which kind of source answered: native-validation (public data) or licensed-feed. */
source: string;
/** Credit line the data licence requires you to show with the result. */
attribution: string | null;
};If what you asked about does not exist, is private, or a search matches nothing, the call still succeeds: output.found is false, output.data is null and output.reason says why. Such misses are free unless the notes below say misses are billed, in which case a miss costs the price of one call.
Example response
Values are placeholders that follow the output schema (strings as "string", numbers as 0); credits shows what this call would cost at the usual price.
{
"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
Calls go only to upstreams that are healthy right now. If an attempt fails, the call is retried automatically inside the same request; a failed attempt costs nothing, and a call never costs more than its quote’s maxCredits. Live figures below are measured on real traffic.
Success rate, uptime, latency and call counts are measured live from real traffic over 30 days and show “—” until there is data.
Errors
Errors are JSON { code, error, requestId } and are never charged. The ones to handle for this endpoint:
- invalid_inputThe request failed validation before anything ran.
- unauthorizedNo valid API key or session was presented.
- insufficient_balanceThe balance cannot cover the most this call could cost.
- key_limit_reachedThe key’s own spend limit is used up for the current window.
- trial_cap_reachedAn agent trial key has used its whole trial budget.
- forbiddenThe credential is valid but may not do this.
- not_foundThe thing addressed by the URL does not exist for you.
- idempotency_conflictThe
Idempotency-Keyis already bound to a different request. - rate_limitedToo many requests in the current window.
- all_sources_failedThe call could not be answered, even after automatic retries.
- service_unavailableThis API cannot run in this deployment right now.
- timeoutThe request passed its deadline before it finished.
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.
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.
Generated from the PrimaryAPI catalog. Machine-readable contract: GET https://api.primaryapi.com/v1/apis/ip.intelligence.