README

Official PHP SDK for BigDataCloud APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, and Network Engineering.

Zero external dependencies — requires only ext-curl and ext-json.

Installation

composer require bigdatacloudapi/bigdatacloud

API Key

Get a free API key at bigdatacloud.com/login. No credit card required.

export BIGDATACLOUD_API_KEY=your-key-here

Quick Start

use BigDataCloud\BigDataCloudClient;

// Reads BIGDATACLOUD_API_KEY from environment
$client = BigDataCloudClient::fromEnvironment();

// Or pass the key directly
// $client = new BigDataCloudClient('your-key-here');

// IP Geolocation
$geo = $client->ipGeolocation->get('1.1.1.1');
echo "{$geo->location->city}, {$geo->country->name}\n";

// Reverse Geocoding
$place = $client->reverseGeocoding->reverseGeocode(-33.87, 151.21);
echo "{$place->city}, {$place->countryName}\n";

// Phone Validation — countryCode is required
$phone = $client->verification->validatePhone('+61412345678', 'AU');
echo "Valid: " . ($phone->isValid ? 'yes' : 'no') . ", Type: {$phone->lineType}\n";

// Email Verification
$email = $client->verification->verifyEmail('user@example.com');
echo "Valid: " . ($email->isValid ? 'yes' : 'no') . ", Disposable: " . ($email->isDisposable ? 'yes' : 'no') . "\n";

Confidence Area

The confidenceArea field may encode multiple polygons. Use the helper:

use BigDataCloud\ConfidenceAreaHelper;

$geo = $client->ipGeolocation->getWithConfidenceArea('1.1.1.1');
$polygons = ConfidenceAreaHelper::splitIntoPolygons($geo->confidenceArea);
foreach ($polygons as $i => $ring) {
    echo "Ring " . ($i + 1) . ": " . count($ring) . " points\n";
}

Available APIs

Phone Validation

Both methods require explicit country context — never uses server IP silently:

// You know the country
$phone = $client->verification->validatePhone('+61412345678', 'AU');

// You know the end user's IP (pass their IP, not your server's)
$phone = $client->verification->validatePhoneByIp('0412345678', $userIp);

Error Handling

use BigDataCloud\BigDataCloudException;

try {
    $geo = $client->ipGeolocation->get('1.1.1.1');
} catch (BigDataCloudException $e) {
    echo "API error {$e->statusCode}: {$e->getMessage()}\n";
}

Samples

export BIGDATACLOUD_API_KEY=your-key-here
php samples/ip_geolocation.php
php samples/reverse_geocoding.php
php samples/verification.php
php samples/network_engineering.php

Requirements

• PHP 8.1+
• ext-curl
• ext-json

License

MIT — see LICENSE.