IP Intelligence

Open in ChatGPT Open in Claude

Location and network details for an IPv4 or IPv6 address (country, region, city, time zone, ASN and network owner) with risk flags from open lists such as Tor exit nodes and cloud provider ranges. Location data comes from DB-IP Lite (CC BY 4.0) and must be credited wherever results are shown.

POST https://YOUR_API_HOST/v1/ip

Credits and caching

Success billing. 1 credit per lookup. You are charged only when the lookup finds something; a not-found result is free.
Results are cached per account for 7 days. Repeating the same lookup in that window is free and returns cache_hit: true.
Invalid input, rate limits and errors are never charged.
Read the billing rules for the full picture.

Request

Send a JSON body with Authorization: Bearer <key>. The body can be up to 64 KB.

Field	Type	Required	Notes
`ip`	string	yes	Up to 100 characters.

Example request

Terminal

curl -X POST https://YOUR_API_HOST/v1/ip \
  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip":"8.8.8.8"}'

1const response = await fetch("https://YOUR_API_HOST/v1/ip", {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({
8    "ip": "8.8.8.8"
9  }),
10});
11
12const result = await response.json();
13if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`);
14console.log(result.found, result.data, result.credits_charged);

1import os
2import requests
3
4response = requests.post(
5    "https://YOUR_API_HOST/v1/ip",
6    headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
7    json={
8        "ip": "8.8.8.8",
9    },
10    timeout=30,
11)
12result = response.json()
13if not response.ok:
14    raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}")
15print(result["found"], result["data"], result["credits_charged"])

Response

The status is 200 whether or not anything was found. Check found. Every response also carries the X-Request-Id, X-Credits-Charged, X-Credits-Remaining and X-RateLimit-* headers.

Envelope

Field	Type	Notes
`request_id`	string	-
`product`	"ip"	-
`found`	boolean	False means the lookup ran and found nothing; it is free.
`reason`	string or null	Why nothing was found; null when found.
`sources`	array of string	Where the data came from, including any attribution the licence requires.
`credits_charged`	integer	0 for a cache hit, a not-found result or an error.
`credits_remaining`	integer	-
`cache_hit`	boolean	True when the account already paid for this lookup within the cache window.
`cache`	object	-

The `data` object

Present when found is true, otherwise null.

Field	Type	Notes
`ip`	string	-
`version`	4 or 6	-
`country`	string or null	ISO 3166-1 alpha-2 country code
`region`	string or null	-
`city`	string or null	-
`latitude`	number or null	-
`longitude`	number or null	-
`timezone`	string or null	IANA time zone name; null when the location source does not carry one (DB-IP Lite does not)
`asn`	integer or null	Autonomous system number
`asn_org`	string or null	Organization that holds the ASN
`is_hosting`	boolean	True when the address is inside a published cloud or hosting provider range
`hosting_provider`	string or null	-
`is_tor`	boolean	True when the address is on the Tor Project exit list
`is_vpn`	boolean or null	Always null in this release: no VPN data source with resale-compatible terms is installed, so VPN status is unknown
`risk_score`	integer	Minimum 0. Maximum 100.
`risk_factors`	array of object	-
`risk_factors[].factor`	string	One of `tor_exit`, `hosting_provider`.
`risk_factors[].points`	integer	-
`risk_factors[].description`	string	-
`attribution`	"IP geolocation by DB-IP"	-

Captured example (2026-10-18)

A real run of this lookup on 2026-10-18, using the request above, which is a public input. The envelope fields are left out.

1{
2  "product": "ip",
3  "found": true,
4  "data": {
5    "ip": "8.8.8.8",
6    "version": 4,
7    "country": "US",
8    "region": "California",
9    "city": "Mountain View",
10    "latitude": 37.422,
11    "longitude": -122.085,
12    "timezone": null,
13    "asn": 15169,
14    "asn_org": "Google LLC",
15    "is_hosting": true,
16    "hosting_provider": "Google",
17    "is_tor": false,
18    "is_vpn": null,
19    "risk_score": 25,
20    "risk_factors": [
21      {
22        "factor": "hosting_provider",
23        "points": 25,
24        "description": "The address belongs to a cloud or hosting provider (Google), where traffic is often automated."
25      }
26    ],
27    "attribution": "IP geolocation by DB-IP"
28  },
29  "sources": [
30    "IP geolocation by DB-IP (db-ip.com), CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)",
31    "IP to ASN data by DB-IP (https://db-ip.com), licensed CC BY 4.0. License: https://creativecommons.org/licenses/by/4.0/",
32    "Published cloud provider IP ranges"
33  ]
34}

Errors

400 invalid_input: The request input is invalid.
401 unauthorized: The API key is missing, malformed, revoked or unknown.
402 insufficient_credits: The account does not have enough credits for this lookup. Error code: insufficient_credits. During a trial whose allowance is used up the code is trial_allowance_exhausted: nothing is charged and the customer starts the plan from the billing page.
405 method_not_allowed: This endpoint does not accept that HTTP method.
413 payload_too_large: The request body is too large.
429 rate_limited: Too many requests for this API key.
500 internal_error: An unexpected error occurred.
503 provider_unavailable: The data source for this product is unavailable right now.