API documentation

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.

Additional information

IPHub intends to counter-fraud, not promote Internet censorship. We kindly ask you to perform checks only on sensitive pages (e.g.: login or order pages) instead of globally denying access to your website/application.

API details

The API answers in JSON format:

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

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

curl https://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.

For connection failures (e.g. TCP connection reset) and 5xx HTTP errors you may want to retry the request at least once with at least a 200 ms delay.

Recommended timeout is 5 seconds.

HTTPS is available. If you use it, please try to reuse existing connections instead of performing a TLS handshake at every request (see Connection pooling below).

Look up multiple IP addresses in a single request:

POST https://v2.api.iphub.info/ip/bulk

Send a JSON array of IP addresses in the request body:

["8.8.8.8", "1.1.1.1", "9.9.9.9"]

The response is an array of results:

[
    {"ip": "8.8.8.8", "block": 1, "countryCode": "US", ...},
    {"ip": "1.1.1.1", "block": 1, "countryCode": "AU", ...},
    ...
    {"ip": "2.2.2.2", "error": "Rate limit exceeded"}
]

Example using curl:

curl -X POST https://v2.api.iphub.info/ip/bulk \
  -H "X-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["8.8.8.8", "1.1.1.1"]'

Each IP address in the request counts as one lookup against your plan quota.

Maximum 1,000,000 IP addresses per request.

Connection pooling

If you're making a high-volume of requests, ensure your application reuses HTTP/HTTPS connections (connection pooling) rather than opening (and closing) new connections for each request. This improves performance and avoids being flagged as a denial-of-service attack by our infrastructure.

  • PHP: PHP 8.5 introduces curl_share_init_persistent() which enables connection reuse across requests natively. For earlier versions, if using Laravel Octane, you may use the cego/curl-handle-reuse-laravel-octane package.
  • Go: Implements connection pooling natively using the default http.Transport, assuming you fully read and close the response body.
  • Node.js: Uses connection pooling via http.Agent by default since Node.js 19. Earlier versions require setting keepAlive: true.
  • Python: Use a requests.Session() object to reuse connections across multiple requests.