macadress

PHP library

macadress.com for PHP.

A typed PHP client for the MAC address and OUI vendor lookup API: vendor name, IEEE block, country, address type, EUI-64 / IPv6 derivation, randomization confidence and a device guess. Laravel service provider and facade included.

On Packagist: macadress/macadress-php. PHP 8.2+, MIT licensed. Source at github.com/sapisos/macadress-php.

Install

composer require macadress/macadress-php

Look up a vendor

The name-only lookup needs no API key:

use Macadress\Client;

$mac = new Client;

$mac->vendor('00:03:93:AB:12:34');   // "Apple, Inc."
$mac->vendor('02:1a:2b:3c:4d:5e');   // null (unregistered, private, or randomized)

Full analysis

Everything else needs a free API key:

$mac = new Client('mk_live_xxx');

$r = $mac->lookup('3C:22:FB:12:34:56');

$r->organization();              // ?string
$r->country();                   // "US" | null
$r->blockType();                 // Macadress\Enums\BlockType::MaL | null
$r->isPotentiallyRandomized();   // bool
$r->randomizationConfidence();   // RandomizationConfidence::None | ::Possible | ::Likely
$r->eui64();                     // "3E:22:FB:FF:FE:12:34:56" | null
$r->device()->category();        // DeviceCategory::Unknown (usually)
$r->explanation();               // plain-English summary

// anything not covered by a typed getter is still reachable
$r->get('vendor_location.city');
$r->toArray();

Batch and directory search

foreach ($mac->batch(['00:03:93:00:00:00', '3C:22:FB:00:00:00', 'bad']) as $item) {
    echo $item->failed()
        ? "{$item->input()} -> {$item->error()}\n"
        : "{$item->input()} -> {$item->organization()}\n";
}

$hits = $mac->searchVendors('Cisco', ['country' => 'US', 'limit' => 20]);
foreach ($hits as $block) {
    echo "{$block->organization()} ({$block->country()})\n";
}

Errors

Every failure is a typed exception under Macadress\Exceptions\MacadressException: InvalidMacException (400), AuthenticationException (401), RateLimitException (429, with ->retryAfter), QuotaExceededException, TransportException for a network failure. Each carries ->statusCode, ->requestId and ->responseBody.

use Macadress\Exceptions\RateLimitException;

try {
    $r = $mac->lookup($input);
} catch (RateLimitException $e) {
    sleep($e->retryAfter ?? 5);
}

Laravel

The service provider and Macadress facade auto-register. Add your key to .env:

MACADRESS_API_KEY=mk_live_xxx      # optional; omit for keyless vendor() only

Then use the facade, or type-hint the client (it is bound as a singleton):

use Macadress\Laravel\Facades\Macadress;

Macadress::vendor('00:03:93:AB:12:34');
Macadress::lookup('00:03:93:AB:12:34')->organization();

// or inject it
public function show(string $mac, \Macadress\Client $macadress)
{
    return $macadress->lookup($mac)->toArray();
}

Publish the config with php artisan vendor:publish --tag=macadress-config to override the base URI or timeouts (for example to point at a self-hosted deployment).

Quota

Each lookup(), batch() address, and searchVendors() call is one API call against your plan, the same as a direct REST call: see pricing. The keyless vendor() endpoint is free for 1,000 lookups a day per IP; sending a key lifts that to your plan quota.

Links