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
• Fetch WHOIS information (e.g., by ASN)
• 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
$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)
$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
// $client->setUrl('https://custom.example.com');

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

Some endpoints or require an API key. If you have one, set it once on the client:

$client->setApiKey('your_api_key_here');

The key will be automatically included in supported requests.

Error Handling

• On HTTP errors (4xx/5xx), the client throws exceptions.
• If the API returns a JSON error with a message field on error status codes, an TwentyTwo\Ipapi\Exception\AuthenticationException is thrown with the original HTTP status code.
• Otherwise, a generic TwentyTwo\Ipapi\Exception\IpapiClientException is thrown.

Example:

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->getMessage());
} catch (IpapiClientException $e) {
    // Handle other API errors
    error_log('API error: '.$e->getMessage());
}

Example Script

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

php example/example.php

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

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:

vendor/bin/phpunit

• Static analysis:

vendor/bin/phpstan analyse

• Coding standards:

vendor/bin/phpcs

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/