README

A lightweight PHP library for interacting with the ipapi.is API. It provides convenient methods to look up reputation and metadata for single or multiple IPs and to fetch WHOIS information. The library is distributed via Composer and built on HTTPlug so you can use any PSR-18 compatible HTTP client.

• API: https://ipapi.is/
• Package name: 22h/ipapi-client
• Minimum PHP version: 8.2

Features

• Lookup a single IP
• Lookup multiple IPs in one request (requires an API key)
• Fetch WHOIS information (e.g., by ASN, requires an API key)
• Optional API key support
• Region-aware base URLs (Global, Germany, US East, Singapore)
• PSR-compliant HTTP stack via HTTPlug and auto-discovery

Installation

Install via Composer:

composer require 22h/ipapi-client

This package relies on HTTPlug discovery to find a PSR-18 HTTP client and PSR-17 factories. If your project doesn’t already provide these, Composer will suggest/install suitable implementations (e.g., guzzlehttp/guzzle, nyholm/psr7, etc.).

Quick Start

<?php
use TwentyTwo\Ipapi\Client;

$client = new Client();

// Optional: authenticate if you have a key
// $client->setApiKey('your_api_key_here');

// Single IP lookup
$result = $client->lookup()->ip('107.174.138.172');
// $result is an associative array with keys like 'ip', 'rir', 'is_proxy', 'is_vpn', etc.

// Multiple IP lookup (requires an API key)
$results = $client->lookup()->ips(['107.174.138.172', '215.252.225.125']);
// $results is an associative array keyed by IP, plus meta like 'total_elapsed_ms'.

// WHOIS lookup (e.g., for an ASN, requires an API key)
$whois = $client->lookup()->whois('AS36352');
// $whois is a raw text string

Regions

ipapi.is offers multiple regional endpoints. You can select the base URL using the provided enum TwentyTwo\Ipapi\Utils\Regions or pass a custom URL string.

use TwentyTwo\Ipapi\Client;
use TwentyTwo\Ipapi\Utils\Regions;

$client = new Client();

// Use a predefined region
$client->setUrl(Regions::US_EAST);

// Or set a custom base URL manually, a path is kept as prefix
// $client->setUrl('https://proxy.example.com/ipapi');

Available regions:

• Regions::GLOBAL → https://api.ipapi.is
• Regions::GERMANY → https://de.ipapi.is
• Regions::US_EAST → https://us.ipapi.is
• Regions::SINGAPORE → https://sg.ipapi.is

Authentication

Bulk lookups and WHOIS require an API key, single lookups work without one (with a reduced response and a daily limit). If you have one, set it once on the client before calling lookup():

$client->setApiKey('your_api_key_here');

The key will be automatically included in supported requests.

Error Handling

Every exception thrown by the client extends TwentyTwo\Ipapi\Exception\IpapiClientException:

• AuthenticationException for 401/403, e.g. an invalid API key or a bulk lookup without key.
• ApiException for every other error status code (4xx/5xx), e.g. an invalid IP address or a rate limit. Both carry the API error message, the HTTP status code (getStatusCode()) and the API error code (getErrorCode(), e.g. ERR_FORBIDDEN_INVALID_API_KEY).
• IpapiClientException itself for network errors (the original exception is available via getPrevious()) and unexpected responses, e.g. when the API does not return a WHOIS record.

Example:

use TwentyTwo\Ipapi\Exception\ApiException;
use TwentyTwo\Ipapi\Exception\AuthenticationException;
use TwentyTwo\Ipapi\Exception\IpapiClientException;

try {
    $data = $client->lookup()->ip('1.2.3.4');
} catch (AuthenticationException $e) {
    // Handle auth/authorization issues
    error_log('Auth error (' . $e->getStatusCode() . ', ' . $e->getErrorCode() . '): ' . $e->getMessage());
} catch (ApiException $e) {
    // Handle other API errors
    error_log('API error (' . $e->getStatusCode() . '): ' . $e->getMessage());
} catch (IpapiClientException $e) {
    // Network errors and unexpected responses
    error_log('Client error: ' . $e->getMessage());
}

Example Script

There is a runnable example at example/example.php:

IPAPI_KEY=your_api_key_here php example/example.php

Edit that file to try different calls (single IP, multiple IPs, WHOIS). The API key is optional.

Requirements

• PHP 8.2+
• A PSR-18 HTTP client and PSR-17 factories (auto-discovered via php-http/discovery)

Development

• Install dependencies:

composer install

• Run tests:

composer test

• Static analysis (PHPStan at level max with strict rules):

composer phpstan

• Coding standards (Mago linter and formatter):

composer cs      # check
composer cs-fix  # format the code

• Everything at once:

composer check

Versioning

This library follows Semantic Versioning (SemVer) as much as possible.

License

Released under the MIT License. See LICENSE.md for details.

Links

• ipapi.is: https://ipapi.is/
• HTTPlug: https://httplug.io/