IPGeolocation.io PHP SDK

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

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk. Get geolocation, company, ASN, time zone, 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

Item	Value
Package	ipgeolocation/ipgeolocation-php-sdk
Namespace	Ipgeolocation\Sdk
Supported Endpoints	/v3/ipgeo, /v3/ipgeo-bulk
Supported Inputs	IPv4, IPv6, domain
Main Data Returned	Geolocation, company, ASN, time zone, network, hostname, abuse, user-agent, currency, security
Authentication	API key
Response Formats	Structured JSON, raw JSON, raw XML
Bulk Limit	Up to 50,000 IPs or domains per request
Transport	Guzzle

Get Your API Key

Create an IPGeolocation.io 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

Keep your IPGeolocation.io API key in an environment variable or secret manager.

Authentication

API Key

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

The API key is sent as the apiKey query parameter, so avoid logging full request URLs.

Plan Behavior

Feature availability depends on your plan and request parameters.

Capability	Free	Paid
Single IPv4 and IPv6 lookup	Supported	Supported
Domain lookup	Not supported	Supported
Bulk lookup	Not supported	Supported
Non-English lang	Not supported	Supported
Optional modules via include	Not supported	Supported
include: ["*"]	Base response only	All plan-available modules

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

Client Configuration

Field	Type	Default	Notes
api_key	string	unset	Your IPGeolocation.io API key.
base_url	string	https://api.ipgeolocation.io	Use the final address of your API or proxy. Redirects are followed only when the protocol, host and port stay the same.
connect_timeout	float	10.0	Time to connect and receive response headers, in seconds. Must be greater than zero.
read_timeout	float	30.0	Time to wait for the next part of the response, in seconds. Must be greater than zero.

The client constructor accepts either an IpGeolocationClientConfig or an array with the same keys. If you supply a custom HTTP client or transport, its own settings can also affect timeouts.

Available Methods

Method	Returns	Notes
lookupIpGeolocation($request = null)	ApiResponse with typed data	Single lookup. Typed JSON response.
lookupIpGeolocationRaw($request = null)	ApiResponse with string data	Single lookup. Raw JSON or XML string.
bulkLookupIpGeolocation($request)	ApiResponse with bulk result array	Bulk lookup. Typed JSON response.
bulkLookupIpGeolocationRaw($request)	ApiResponse with string data	Bulk lookup. Raw JSON or XML string.
close()	void	Closes the client. Do not reuse the client after this.

Note

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

Request Options

Field	Applies To	Notes
ip	Single lookup	IPv4, IPv6, or domain. Omit it for caller IP lookup.
ips	Bulk lookup	Array of 1 to 50,000 IPs or domains.
lang	Single and bulk	One of en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt, ar (Arabic).
include	Single and bulk	Array of module names such as security, abuse, user_agent, hostname, liveHostname, hostnameFallbackLive, geo_accuracy, dma_code, or *.
fields	Single and bulk	Array of field paths to keep, for example ["location.country_name", "security.threat_score"].
excludes	Single and bulk	Array of field paths to remove from the response.
user_agent	Single and bulk	Overrides the outbound User-Agent header.
headers	Single and bulk	Extra request headers. Use an associative array where each value is a string or an array of strings.
output	Single and bulk	"json" or "xml". Typed methods require JSON.

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. If the API sends missing, extra or invalid rows, the typed lookup throws SerializationException. The raw lookup returns the response as received.

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

Field	Meaning
credits_charged	Credits charged for the request when the API returns that header
successful_records	Number of successful bulk records when the API returns that header
status_code	HTTP status code
duration_ms	Client-side request time in milliseconds
raw_headers	Response headers as an associative array of header names to string arrays

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.

$response = $client->lookupIpGeolocation(['ip' => '8.8.8.8']);
$array = $response->data->toArray();
$json = json_encode($response->data, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR);

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

When you use print_r() or var_dump() on a client or its settings, the SDK shows [REDACTED] in place of your API key. Settings printed as JSON also hide the key. You can still read the key from $config->api_key.

Errors

If a request error includes your API key, the SDK hides it. This also applies to error messages in typed bulk results. If the error response is too large or ends early, you still get the HTTP status. Some error details may be left out to keep the key hidden.

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

• Missing API key Set api_key before making a lookup.
• 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 the next part of the response.

Frequently Asked Questions

Can I pass a plain array instead of a request object?

Yes. All client methods accept either the typed request object or a plain array with the same keys.

How do I look up my own public IP?

Call lookupIpGeolocation() with no ip value.

How do I get XML?

Use the raw methods with output => "xml".

How do I read bulk errors?

Check $result->success. Success items use $result->data. Error items use $result->error->message.

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