iplocate / php-iplocate
PHP client for the IPLocate.io geolocation API
Requires
- php: ^8.0
- guzzlehttp/guzzle: ^7.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- guzzlehttp/psr7: ^2.0
- phpstan/phpstan: ^1.0
- phpunit/phpunit: ^9.0.0 || ^10.0.0 || ^11.0.0 || ^12.0.0
README
A PHP client for the IPLocate.io geolocation API. Look up detailed geolocation and threat intelligence data for any IP address:
- IP geolocation: IP to country, IP to city, IP to region/state, coordinates, timezone, postal code
- ASN information: Internet service provider, network details, routing information
- Privacy & threat detection: VPN, proxy, Tor, hosting provider detection
- Company information: Business details associated with IP addresses - company name, domain, type (ISP/hosting/education/government/business)
- Abuse contact: Network abuse reporting information
- Hosting detection: Cloud provider and hosting service detection using our proprietary hosting detection engine
See what information we can provide for your IP address.
Getting started
You can make 1,000 free requests per day with a free account. For higher plans, check out API pricing.
Requirements
- PHP 8.0 or higher
- Guzzle HTTP client
Installation
Install via Composer:
composer require iplocate/php-iplocate
Or add to your composer.json
:
{ "require": { "iplocate/php-iplocate": "^1.0" } }
Quick start
<?php use IPLocate\IPLocate; // Create a client with your API key // Get your free API key from https://iplocate.io/signup $client = new IPLocate('your-api-key'); // Look up an IP address $result = $client->lookup('8.8.8.8'); echo "IP: {$result->ip}\n"; if ($result->country) { echo "Country: {$result->country}\n"; } if ($result->city) { echo "City: {$result->city}\n"; } // Check privacy flags echo "Is VPN: " . ($result->privacy->isVpn ? 'Yes' : 'No') . "\n"; echo "Is Proxy: " . ($result->privacy->isProxy ? 'Yes' : 'No') . "\n";
Get your own IP address information
// Look up your own IP address (no IP parameter) $result = $client->lookupSelf(); echo "Your IP: {$result->ip}\n";
Get the country for an IP address
$result = $client->lookup('203.0.113.1'); echo "Country: {$result->country} ({$result->countryCode})\n";
Get the currency code for a country by IP address
$result = $client->lookup('203.0.113.1'); echo "Currency: {$result->currencyCode}\n";
Get the calling code for a country by IP address
$result = $client->lookup('203.0.113.1'); echo "Calling code: +{$result->callingCode}\n";
Authentication
Get your free API key from IPLocate.io, and pass it when creating the client:
$client = new IPLocate('your-api-key');
Examples
IP address geolocation lookup
use IPLocate\IPLocate; $client = new IPLocate('your-api-key'); $result = $client->lookup('203.0.113.1'); echo "Country: {$result->country} ({$result->countryCode})\n"; if ($result->latitude && $result->longitude) { echo "Coordinates: {$result->latitude}, {$result->longitude}\n"; }
Check for VPN/Proxy Detection
$result = $client->lookup('192.0.2.1'); if ($result->privacy->isVpn) { echo "This IP is using a VPN\n"; } if ($result->privacy->isProxy) { echo "This IP is using a proxy\n"; } if ($result->privacy->isTor) { echo "This IP is using Tor\n"; }
ASN and network information
$result = $client->lookup('8.8.8.8'); if ($result->asn) { echo "ASN: {$result->asn->asn}\n"; echo "ISP: {$result->asn->name}\n"; echo "Network: {$result->asn->route}\n"; }
Custom configuration
use GuzzleHttp\Client; use IPLocate\IPLocate; // Custom timeout and HTTP client $customHttpClient = new Client([ 'timeout' => 60.0, 'verify' => true, ]); $client = new IPLocate( apiKey: 'your-api-key', timeout: 60.0, httpClient: $customHttpClient ); // Custom base URL (for enterprise customers) $client = new IPLocate( apiKey: 'your-api-key', baseUrl: 'https://custom-endpoint.com/api' );
Response structure
The LookupResponse
object contains all available data:
class LookupResponse { public string $ip; public Privacy $privacy; public ?string $country; public ?string $countryCode; public bool $isEu; public ?string $city; public ?string $continent; public ?float $latitude; public ?float $longitude; public ?string $timeZone; public ?string $postalCode; public ?string $subdivision; public ?string $currencyCode; public ?string $callingCode; public ?string $network; public ?ASN $asn; public ?Company $company; public ?Hosting $hosting; public ?Abuse $abuse; }
Properties marked as ?
are nullable and may be null
if data is not available.
Error handling
use IPLocate\IPLocate; use IPLocate\Exceptions\AuthenticationException; use IPLocate\Exceptions\InvalidIPException; use IPLocate\Exceptions\NotFoundException; use IPLocate\Exceptions\RateLimitException; use IPLocate\Exceptions\APIException; $client = new IPLocate('your-api-key'); try { $result = $client->lookup('8.8.8.8'); } catch (InvalidIPException $e) { echo "Invalid IP address: {$e->getMessage()}\n"; } catch (AuthenticationException $e) { echo "Invalid API key: {$e->getMessage()}\n"; } catch (NotFoundException $e) { echo "IP address not found: {$e->getMessage()}\n"; } catch (RateLimitException $e) { echo "Rate limit exceeded: {$e->getMessage()}\n"; } catch (APIException $e) { echo "API error ({$e->getCode()}): {$e->getMessage()}\n"; }
Common API errors:
InvalidIPException
: Invalid IP address format (HTTP 400)AuthenticationException
: Invalid API key (HTTP 403)NotFoundException
: IP address not found (HTTP 404)RateLimitException
: Rate limit exceeded (HTTP 429)APIException
: Other API errors (HTTP 500, etc.)
API reference
For complete API documentation, visit iplocate.io/docs.
Development
Install dependencies
composer install
Run tests
composer test
Run tests with coverage
composer test-coverage
Run static analysis
composer phpstan
Fix code style
composer cs-fix
Integration tests
Set the IPLOCATE_API_KEY
environment variable to run integration tests:
export IPLOCATE_API_KEY=your-api-key composer test
Examples
See the examples/ directory for more detailed usage examples:
License
This project is licensed under the MIT License - see the LICENSE file for details.
About IPLocate.io
Since 2017, IPLocate has set out to provide the most reliable and accurate IP address data.
We process 50TB+ of data to produce our comprehensive IP geolocation, IP to company, proxy and VPN detection, hosting detection, ASN, and WHOIS data sets. Our API handles over 15 billion requests a month for thousands of businesses and developers.
- Email: support@iplocate.io
- Website: iplocate.io
- Documentation: iplocate.io/docs
- Sign up for a free API Key: iplocate.io/signup