curl --request POST \
--url https://api.finowl.co/v1/ip/lookup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"ip": "8.8.8.8"
}
'{
"ip": "8.8.8.8",
"version": 4,
"country_code": "US",
"country": "United States",
"region": "California",
"city": "Mountain View",
"asn": 15169,
"as_name": "Google LLC",
"hosting": true,
"hosting_provider": "google_cloud",
"tor": false,
"reserved": false
}Look up an IP address
Get the country, city and network of an IPv4 or IPv6 address, and flag hosting and Tor traffic.
curl --request POST \
--url https://api.finowl.co/v1/ip/lookup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"ip": "8.8.8.8"
}
'{
"ip": "8.8.8.8",
"version": 4,
"country_code": "US",
"country": "United States",
"region": "California",
"city": "Mountain View",
"asn": 15169,
"as_name": "Google LLC",
"hosting": true,
"hosting_provider": "google_cloud",
"tor": false,
"reserved": false
}Good to know
- 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.
hostingmeans 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.tormeans the user is anonymous. The address is a current Tor exit node. The location is the exit node’s, not the user’s.reserved: trueusually means the wrong address. Private and loopback addresses such as10.0.0.5are not on the internet. Behind a load balancer, send the client address fromX-Forwarded-Forinstead.data_unavailableis free. If the IP data is still loading, the request returns503and 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.
Guide: sign-up fraud checks
Authorizations
Your Finowl API key, for example finowl_3f9a.... Create keys in the dashboard under API Keys.
Body
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.
64"8.8.8.8"
Response
The lookup completed. Unknown fields are empty or null.
The address in canonical form, for example IPv6 compressed and lowercased.
The IP version.
4, 6 ISO 3166-1 alpha-2 code of the country the address is registered to or used in. Empty when unknown or reserved.
The country name for country_code. Empty when unknown.
The state, province or region, such as California. null when unknown.
The nearest city. Often the location of the network operator rather than the user, especially for mobile networks. null when unknown.
The autonomous system number of the network that announces the address. null when unknown.
The name of that network's operator, such as Google LLC or an internet provider. null when unknown.
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.
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.
aws, google_cloud, azure, cloudflare, oracle_cloud, digitalocean, linode, vultr, hetzner, ovh, other_hosting, null true when the address is a current Tor exit node, so the real user is anonymous.
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.