README

Official PHP SDK for the Watch-IP visitor geolocation API.

Watch-IP looks up the geolocation of whoever is currently loading your page — it's designed to be called directly from the visitor's own browser with a publishable, origin-locked API key. There is no server-to-server or arbitrary-IP lookup mode; see the docs for why.

This repo is a read-only mirror published for Packagist (which clones directly from git rather than hosting an uploaded artifact like PyPI/npm). Development happens in the main Digitload/watch-ip monorepo; issues and PRs should go there too.

Calling it from PHP therefore means calling it from your own server rather than a visitor's browser. That's a legitimate way to use this SDK for testing or internal tooling, but the request won't carry the Origin header a browser fetch sends automatically — and origin-locking means the API will reject it with origin_not_allowed unless you pass an origin set to one of the key's allowed origins yourself.

Install

composer require digitload/watch-ip-sdk

Requires PHP 8.1+ with the curl and json extensions (both bundled with virtually every PHP install).

Usage

use Digitload\WatchIP\WatchIP;

$client = new WatchIP('wip_pub_xxxxxxxx', origin: 'https://example.com');
$geo = $client->getGeo();

echo $geo['country'], ' ', $geo['city'], ' ', $geo['timezone'];

Or, for a one-off call without holding onto a client instance:

use function Digitload\WatchIP\getGeo;

$geo = getGeo('wip_pub_xxxxxxxx', ['origin' => 'https://example.com']);

Error handling

Every failure — a rejected request (invalid key, disallowed origin, rate limit) or a network error — throws a WatchIPError with a status and a stable error code:

use Digitload\WatchIP\WatchIP;
use Digitload\WatchIP\WatchIPError;

$client = new WatchIP('wip_pub_xxxxxxxx', origin: 'https://example.com');

try {
    $geo = $client->getGeo();
} catch (WatchIPError $err) {
    echo $err->getErrorCode(), ' ', $err->getStatus(), ' ', $err->getMessage();
    // e.g. "origin_not_allowed" 403 "This origin is not authorized for this API key."
}

WatchIPError extends \RuntimeException, but note getErrorCode() rather than getCode(): Exception::getCode() is int-typed in PHP (its constructor parameter is int $code), while the API's error codes are strings like "origin_not_allowed". Rather than fight that typing mismatch, this SDK leaves getCode() alone and adds getErrorCode(): string for the API's code.

Optional fields and timeouts

$geo = $client->getGeo(['include' => ['hostname'], 'timeout' => 5.0]);

Requirements

PHP 8.1+ with ext-curl and ext-json. No Composer runtime dependencies — requests are made with a small cURL wrapper rather than pulling in Guzzle.

License

MIT

digitload / watch-ip-sdk

Package info

Security

Statistics