README

The official PHP client for the ip-api.io IP intelligence platform. One client covers IP geolocation, email validation and verification (syntax, MX, SMTP deliverability), fraud detection and risk scoring, VPN/proxy/Tor detection, disposable email detection, ASN lookup, WHOIS, reverse DNS, MX records and domain age.

Zero Composer dependencies — just ext-curl and ext-json.

Install

composer require ip-api-io/ipapi-php

Quickstart

use IpApiIo\Client;

$client = new Client(apiKey: 'YOUR_API_KEY'); // free key at https://ip-api.io

// Where is this IP, and is it risky?
$info = $client->lookup('8.8.8.8');
echo $info['location']['country'];               // "United States"
var_dump($info['suspicious_factors']['is_vpn']);  // false

$risk = $client->riskScore('8.8.8.8');
echo "{$risk['score']} {$risk['risk_level']}";    // 0 low

$email = $client->validateEmail('user@example.com');
echo $email['reachable'];                          // "yes"

An API key is required — the API rejects keyless requests with 401. Sign up at ip-api.io for a free key.

Documentation

Each guide documents the methods for one capability, with runnable examples and a link to the matching ip-api.io product page:

IP geolocation & bulk lookup — lookup, lookupBatch
Email validation & verification — emailInfo, validateEmail, validateEmailBatch
Fraud detection & risk scoring — riskScore, emailRiskScore, ipReputation
VPN, proxy & Tor detection — torCheck, suspicious_factors
ASN & DNS lookups — asn, whois, reverseDns, forwardDns, mxRecords
Domain age checker — domainAge, domainAgeBatch
Errors, rate limits & usage — exception types, rateLimit, usageSummary

Methods

Every method maps to one ip-api.io endpoint and its product page:

Method	Endpoint	Product page
`lookup(?string $ip = null)`	`GET /api/v1/ip[/{ip}]`	IP geolocation
`lookupBatch(array $ips)`	`POST /api/v1/ip/batch` (≤100 IPs)	Bulk IP lookup
`emailInfo(string $email)`	`GET /api/v1/email/{email}`	Email validation
`validateEmail(string $email)`	`GET /api/v1/email/advanced/{email}`	Advanced email validation
`validateEmailBatch(array $emails)`	`POST /api/v1/email/advanced/batch` (≤100)	Email list cleaning
`riskScore(?string $ip = null)`	`GET /api/v1/risk-score[/{ip}]`	Risk score
`emailRiskScore(string $email)`	`GET /api/v1/risk-score/email/{email}`	Fraud detection
`ipReputation(string $ip)`	`GET /api/v1/ip-reputation/{ip}`	IP reputation
`torCheck(string $ip)`	`GET /api/v1/tor/{ip}`	Tor detection
`asn(string $ip)`	`GET /api/v1/asn/{ip}`	ASN lookup
`whois(string $domain)`	`GET /api/v1/dns/whois/{domain}`	WHOIS lookup
`reverseDns(string $ip)`	`GET /api/v1/dns/reverse/{ip}`	Reverse DNS
`forwardDns(string $hostname)`	`GET /api/v1/dns/forward/{hostname}`	—
`mxRecords(string $domain)`	`GET /api/v1/dns/mx/{domain}`	MX record lookup
`domainAge(string $domain)`	`GET /api/v1/domain/age/{domain}`	Domain age checker
`domainAgeBatch(array $domains)`	`POST /api/v1/domain/age/batch`	Domain age checker
`rateLimit()`	`GET /api/v1/ratelimit`	—
`usageSummary()`	`GET /api/v1/usage/summary`	—

All methods return parsed JSON as associative arrays.

Error handling

The client throws typed exceptions and never retries — on 429, RateLimitError::$reset tells you when your quota renews:

use IpApiIo\AuthenticationError;
use IpApiIo\RateLimitError;

try {
    $client->lookup('8.8.8.8');
} catch (RateLimitError $e) {
    echo "limit={$e->limit} remaining={$e->remaining} resets_at={$e->reset}";
} catch (AuthenticationError $e) {
    echo 'invalid API key';
}

See docs/error-handling.md for the full exception taxonomy.

ip-api-io / ipapi-php

Maintainers

Package info

Statistics

Security