bigdatacloudapi/bigdatacloud

Official PHP SDK for BigDataCloud APIs — IP Geolocation, Reverse Geocoding, Phone & Email Verification, Network Engineering

v1.0.0 2026-04-11 00:03 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^10

MIT

• BigDataCloud Pty Ltd

• geolocation
• ip-geolocation
• phone-validation
• email-verification
• reverse-geocoding
• bigdatacloud
• network-engineering

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('[phone]', 'AU');
echo "Valid: " . ($phone->isValid ? 'yes' : 'no') . ", Type: {$phone->lineType}\n";

// Email Verification
$email = $client->verification->verifyEmail('[e-mail]');
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

Client	Methods
$client->ipGeolocation	get, getWithConfidenceArea, getFull, getCountryByIp, getCountryInfo, getAllCountries, getHazardReport, getUserRisk, getAsnInfo, getNetworkByIp, getTimezoneByIanaId, getTimezoneByIp, parseUserAgent
$client->reverseGeocoding	reverseGeocode, reverseGeocodeWithTimezone, getTimezoneByLocation
$client->verification	validatePhone, validatePhoneByIp, verifyEmail
$client->networkEngineering	getAsnInfoFull, getReceivingFrom, getTransitTo, getBgpPrefixes, getNetworksByCidr, getAsnRankList, getTorExitNodes

Phone Validation

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

// You know the country
$phone = $client->verification->validatePhone('[phone]', '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.