README

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

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.

Sign up: https://app.ipgeolocation.io/signup
Verify your email if prompted
Sign in: https://app.ipgeolocation.io/login
Open your dashboard: https://app.ipgeolocation.io/dashboard
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 include 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.

ipgeolocation / ipgeolocation-php-sdk

Package info

Security

Statistics