README

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

Table of Contents

• Installation
• Quick Start
• At a Glance
• Get Your API Key
• Authentication
• Plan Behavior
• Client Configuration
• Available Methods
• Request Options
• Examples
• Response Metadata
• JSON Helpers
• Errors
• Troubleshooting
• Frequently Asked Questions
• Links

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.

Authentication

API Key

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

Request-Origin Auth

$client = new IpGeolocationClient([
    'request_origin' => 'https://app.example.com',
]);

request_origin must be an absolute http or https origin with no path, query string, fragment, or userinfo.

Important

Request-origin auth does not work with /v3/ipgeo-bulk. Bulk lookup always requires api_key.

Note

If you set both api_key and request_origin, both are sent. The API key appears in the query string, so avoid logging full request URLs.

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

Note

Typed methods support JSON only. Use the raw methods when you need XML output.

Request Options

Examples

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

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

Caller IP

Omit ip to look up the public IP of the machine making the request.

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

Domain Lookup

Domain lookup is a paid-plan feature.

$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;

Security and Abuse

$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;

User-Agent Parsing

To parse a visitor user-agent string, pass include: ["user_agent"] and send the visitor string in the request User-Agent header.

$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;

Note

The user_agent request field overrides the SDK's default outbound User-Agent header. It takes precedence over headers["User-Agent"].

Filtered Response

$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;

Raw XML

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

echo $response->data . PHP_EOL;

Bulk Lookup

Bulk lookup is a paid-plan feature and always requires api_key.

Each bulk result is either a success or an error.

$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