The first step is to subscribe to a plan.

The parameter block was designed carefully to allow our users to determine their own 'risk-level'. We recommend you use this variable when deciding to block the queried IP from accessing to your application.

block: 0 - Residential or business IP (i.e. safe IP)

block: 1 - Non-residential IP (hosting provider, proxy, etc.)

block: 2 - Non-residential & residential IP (warning, may flag innocent people)

We generally recommend people to use risk level 1 (that is, only block on block == 1). It provides the best balance between stopping malicious users and avoiding false positives.

The country parameter is provided as courtesy and may not represent the actual country of the IP address, but rather the AS' country.

On behalf of the internet, please don't globally block "Bad IP's" from your website. Only query IP addresses on routes that handle sensitive data, for example, login and registration pages. IPHub intends to counter-fraud, not destroy internet freedom. Remember there are good people that use proxies to evade censorship.

The API answers in JSON format:

{
	"ip": "8.8.8.8",
	"countryCode": "US",
	"countryName": "United States",
	"asn": 15169,
	"isp": "GOOGLE",
	"block": 1
}

You would need to specify your API key in the X-Key header. Here's how you would do it on the command line on a Linux machine:

curl http://v2.api.iphub.info/ip/8.8.8.8 -H "X-Key: 123"

If you hit the rate limit, an HTTP 429 (Too Many Requests) status code will be returned.

Make sure you properly handle connection failures and non-200 OK HTTP responses.

HTTPS is available. If you use it please try to reuse existing connections instead of performing a TLS handshake at every request (if that's technically feasible on your tech stack).

If you inspect the JSON response you might find a "hostname" key, please don't use it as it's only there for backward-compatibility reasons. This feature was removed due to performance reasons.