IPGeolocation PHP SDK

Overview

Official PHP SDK for the IPGeolocation.io IP Location API.

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk . Get geolocation, company, ASN, timezone, network, hostname, abuse, user-agent, and security data.

• PHP 8.1+
• Sync client built on Guzzle
• Typed responses plus raw JSON and XML methods

Installation

composer require ipgeolocation/ipgeolocation-php-sdk

<?php

require __DIR__ . '/vendor/autoload.php';

use Ipgeolocation\Sdk\IpGeolocationClient;

• package: ipgeolocation/ipgeolocation-php-sdk
• Package page: https://packagist.org/packages/ipgeolocation/ipgeolocation-php-sdk
• GitHub repository: https://github.com/IPGeolocation/ip-geolocation-api-php

Quick Start

<?php

require __DIR__ . '/vendor/autoload.php';

use Ipgeolocation\Sdk\IpGeolocationClient;

$client = new IpGeolocationClient([
    'api_key' => getenv('IPGEO_API_KEY'),
]);

try {
    $response = $client->lookupIpGeolocation([
        'ip' => '8.8.8.8',
    ]);

    echo $response->data->ip . PHP_EOL; // 8.8.8.8
    echo ($response->data->location?->country_name ?? '') . PHP_EOL; // United States
    echo ($response->data->location?->city ?? '') . PHP_EOL;
    echo ($response->data->time_zone?->name ?? '') . PHP_EOL;
    echo ($response->metadata->credits_charged ?? 0) . PHP_EOL;
} finally {
    $client->close();
}

You can pass plain arrays to request methods. If you want validation before the request is sent, use LookupIpGeolocationRequest and BulkLookupIpGeolocationRequest .

At a Glance

Get Your API Key

Create an IPGeolocation account and copy an API key from your dashboard.

1. Sign up: https://app.ipgeolocation.io/signup
2. Verify your email if prompted
3. Sign in: https://app.ipgeolocation.io/login
4. Open your dashboard: https://app.ipgeolocation.io/dashboard
5. Copy an API key from the API Keys section

For server-side code, keep the API key in an environment variable or secret manager. For browser-based single lookups on paid plans, use request-origin auth instead of exposing an API key in frontend code.

Plan Behavior

Feature availability depends on your plan and request parameters.

Paid plans still need include for optional modules. fields and excludes only trim the response. They do not turn modules on or unlock paid data.

Client Configuration

The client constructor accepts either an IpGeolocationClientConfig or an array with the same keys.

Available Methods

Request Options

Examples

The examples below assume you already have a configured client in scope:

$client = new IpGeolocationClient([
    'api_key' => getenv('IPGEO_API_KEY'),
]);

$response = $client->lookupIpGeolocation();
echo $response->data->ip . PHP_EOL;

$response = $client->lookupIpGeolocation([
    'ip' => 'ipgeolocation.io',
]);

echo $response->data->ip . PHP_EOL;
echo ($response->data->domain ?? '') . PHP_EOL; // ipgeolocation.io
echo ($response->data->location?->country_name ?? '') . PHP_EOL;

$response = $client->lookupIpGeolocation([
    'ip' => '9.9.9.9',
    'include' => ['security', 'abuse'],
]);

echo ($response->data->security?->threat_score ?? 0) . PHP_EOL;
echo ($response->data->abuse?->emails[0] ?? '') . PHP_EOL;

$visitorUa = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9';

$response = $client->lookupIpGeolocation([
    'ip' => '115.240.90.163',
    'include' => ['user_agent'],
    'headers' => ['User-Agent' => $visitorUa],
]);

echo ($response->data->user_agent?->name ?? '') . PHP_EOL;
echo ($response->data->user_agent?->operating_system?->name ?? '') . PHP_EOL;

$response = $client->lookupIpGeolocation([
    'ip' => '8.8.8.8',
    'include' => ['security'],
    'fields' => ['location.country_name', 'security.threat_score', 'security.is_vpn'],
    'excludes' => ['currency'],
]);

echo ($response->data->location?->country_name ?? '') . PHP_EOL;
echo ($response->data->security?->threat_score ?? 0) . PHP_EOL;
echo ($response->data->security?->is_vpn ? 'true' : 'false') . PHP_EOL;

$response = $client->lookupIpGeolocationRaw([
    'ip' => '8.8.8.8',
    'output' => 'xml',
]);

echo $response->data . PHP_EOL;

$response = $client->bulkLookupIpGeolocation([
    'ips' => ['8.8.8.8', 'invalid-ip', '1.1.1.1'],
    'include' => ['security'],
]);

foreach ($response->data as $result) {
    if ($result->success) {
        echo $result->data->ip . PHP_EOL;
        echo ($result->data->security?->threat_score ?? 0) . PHP_EOL;
        continue;
    }

    echo ($result->error->message ?? '') . PHP_EOL;
}

Response Metadata

Each method returns an ApiResponse with data and metadata .

metadata includes:

Helper methods:

$metadata = $response->metadata;

echo $metadata->status_code . PHP_EOL;
echo $metadata->duration_ms . PHP_EOL;
print_r($metadata->headerValues('X-Credits-Charged'));
echo ($metadata->firstHeaderValue('Content-Type') ?? '') . PHP_EOL;

JSON Helpers

Typed response objects extend ValueObject , so you can turn them into arrays or JSON when you need to log, cache, or forward them.

$array = $response->data->toArray();
$json = json_encode($response->data, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR);

print_r($array);
echo $json . PHP_EOL;

Errors

The SDK throws these exception classes:

• Ipgeolocation\Sdk\ValidationException
• Ipgeolocation\Sdk\SerializationException
• Ipgeolocation\Sdk\TransportException
• Ipgeolocation\Sdk\RequestTimeoutException
• Ipgeolocation\Sdk\ApiException
• Ipgeolocation\Sdk\BadRequestException
• Ipgeolocation\Sdk\UnauthorizedException
• Ipgeolocation\Sdk\ForbiddenException
• Ipgeolocation\Sdk\NotFoundException
• Ipgeolocation\Sdk\MethodNotAllowedException
• Ipgeolocation\Sdk\PayloadTooLargeException
• Ipgeolocation\Sdk\UnsupportedMediaTypeException
• Ipgeolocation\Sdk\LockedException
• Ipgeolocation\Sdk\RateLimitException
• Ipgeolocation\Sdk\ClientClosedRequestException
• Ipgeolocation\Sdk\ServerErrorException

Example:

try {
    $client->lookupIpGeolocation(['ip' => '8.8.8.8']);
} catch (\Ipgeolocation\Sdk\ApiException $error) {
    echo $error->status_code . PHP_EOL;
    echo ($error->api_message ?? '') . PHP_EOL;
    echo $error->getMessage() . PHP_EOL;
}

Troubleshooting

• bulk lookup requires api_key in client config Bulk lookup does not support request-origin auth on its own.
• single lookup requires api_key or request_origin in client config Set at least one authentication option before calling the single lookup methods.
• XML output is not supported by typed methods Use lookupIpGeolocationRaw or bulkLookupIpGeolocationRaw for XML output.
• client is closed Create a new client after calling close .
• TransportException or RequestTimeoutException Increase connect_timeout or read_timeout , or add retry logic. read_timeout is how long the client waits for response data before timing out.

Frequently Asked Questions

Links

• API docs: https://ipgeolocation.io/documentation/ip-location-api.html
• Dashboard: https://app.ipgeolocation.io/dashboard
• Pricing: https://ipgeolocation.io/pricing.html
• Packagist package: https://packagist.org/packages/ipgeolocation/ipgeolocation-php-sdk
• GitHub repo: https://github.com/IPGeolocation/ip-geolocation-api-php