Skip to main content
POST
Moving from ip/lookup? IP Intelligence is the IP lookup endpoint under a new name, with the same request and response. Change the path from /v1/ip/lookup to /v1/ip/intelligence. The old path now returns 410 with the code endpoint_renamed.

​
Good to know

  • Only need the location? IP Geolocation returns the same location fields without the network and privacy signals.
  • Country is reliable, city is approximate. Country-level results are accurate for most addresses. The city is often the network operator’s location, which can be far from the user, especially on mobile networks.
  • The data is refreshed daily. Addresses that recently changed hands may show their previous owner for a day or two.
  • hosting means a server, not a person. The address belongs to a cloud or hosting provider. Real users rarely browse from these, so it often points to a bot, VPN or proxy. Some company VPNs and privacy relays also run on cloud providers.
  • tor means the user is anonymous. The address is a current Tor exit node. The location is the exit node’s, not the user’s.
  • reserved: true usually means the wrong address. Private and loopback addresses such as 10.0.0.5 are not on the internet. Behind a load balancer, send the client address from X-Forwarded-For instead.
  • data_unavailable is free. If the IP data is still loading, the request returns 503 and is not charged. Try again after a few seconds.
  • Credit DB-IP if you show locations. The geolocation data is licensed under CC BY 4.0. If you display the city, region or country to users, include “IP geolocation by DB-IP” near it.
  • risk is a starting point. Tor exits, VPNs, hosting networks and iCloud Private Relay raise the score; verified search engine crawlers lower it. Combine it with your own signals before blocking anyone.
  • network.type is a heuristic. It comes from the hosting flag and the network operator’s name, and is often unknown.
  • network.allocated can be a re-registration date rather than the first allocation, because the registries’ files record the latest change.
IP geolocation by DB-IP (CC BY 4.0). Time zones from GeoNames (CC BY 4.0). VPN ranges from X4BNet lists_vpn (MIT).

Guide: sign-up fraud checks

Combine IP Intelligence with email and phone checks when someone registers.

Authorizations

​
Authorization
string
header
required

Your Finowl API key, for example finowl_3f9a.... Create keys in the dashboard under API Keys.

Body

application/json
​
ip
string
required

An IPv4 or IPv6 address, such as 8.8.8.8 or 2001:4860:4860::8888. Ranges (CIDR), hostnames, ports and IPv6 zones such as fe80::1%eth0 return invalid_input.

Maximum string length: 64
Example:

"8.8.8.8"

Response

The lookup completed. Unknown fields are empty or null.

​
ip
string
required

The address in canonical form, for example IPv6 compressed and lowercased.

​
version
enum<integer>
required

The IP version.

Available options:
4,
6
​
country_code
string
required

ISO 3166-1 alpha-2 code of the country the address is registered to or used in. Empty when unknown or reserved.

​
country
string
required

The country name for country_code. Empty when unknown.

​
region
string | null
required

The state, province or region, such as California. null when unknown.

​
city
string | null
required

The nearest city. Often the location of the network operator rather than the user, especially for mobile networks. null when unknown.

​
asn
integer | null
required

The autonomous system number of the network that announces the address. null when unknown.

​
as_name
string | null
required

The name of that network's operator, such as Google LLC or an internet provider. null when unknown.

​
hosting
boolean
required

true when the address is in a range published by a cloud provider or belongs to a known hosting network. Real users rarely browse from these addresses, so it often indicates a server, VPN or proxy.

​
hosting_provider
enum<string> | null
required

The hosting provider when hosting is true, other_hosting for any other hosting network, null otherwise. Treat values you don't recognize like other_hosting.

Available options:
aws,
google_cloud,
azure,
cloudflare,
oracle_cloud,
digitalocean,
linode,
vultr,
hetzner,
ovh,
other_hosting,
null
​
tor
boolean
required

true when the address is a current Tor exit node, so the real user is anonymous.

​
reserved
boolean
required

true for private, loopback, link-local, carrier-grade NAT, documentation and other reserved addresses. These are not on the public internet, so all location and network fields are empty, null or false. Usually it means you sent your proxy's address instead of the client's.

​
location
object
required

Where city is, and the local time there. Every field is null for reserved addresses.

​
country_info
object | null
required

Details of country_code. null when country_code is empty.

​
network
object
required

The network that announces the address and how it was registered. Every field is null for reserved addresses.

​
privacy
object
required

Signals that the traffic is anonymized or automated. Every flag is false and every name null for reserved addresses.

​
risk
object
required

A simple score of how likely the address hides the real user, for ranking and review rather than as a probability. Weights are added for each factor present and the total is clamped to 0–100: tor_exit 80, vpn 50, hosting 40, icloud_private_relay 30, unknown_network 10, and verified_crawler subtracts 40.