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.

22h / ipapi-client

Maintainers

Details