Skip to main content
POST

​
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.
  • Coordinates are a point in the city, not the user. Use them to place a pin or pick a nearby region, not to find a street address.
  • location.timezone comes from the coordinates. It is the time zone of the nearest large city in the same country, or the country’s only time zone when the city is unknown. local_time is the time there when you made the request.
  • The data is refreshed daily. Addresses that recently changed hands may show their previous location for a day or two.
  • 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.
  • Need to know if the address can be trusted? IP Intelligence adds the network, VPN, Tor, hosting and relay flags and a risk score, for the same 1 credit.
IP geolocation by DB-IP (CC BY 4.0). Time zones from GeoNames (CC BY 4.0).

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.

​
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 fields are empty or null. 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.