README

PHP client for MAC address and OUI vendor lookups, backed by macadress.com.

This is the revived version of the old macvendors.co PHP class. That service is gone; the class now talks to macadress.com instead. The original methods keep the same names and return the same shapes, so existing code keeps working. New methods expose the extra data macadress.com provides.

Install

With Composer:

composer require samymassoud/macvendors-api

Or drop src/ in and require the two files:

require 'src/ApiException.php';
require 'src/MacvendorsApi.php';

Needs PHP 7.2+ with the curl and json extensions.

Quick start

use Macvendors\Api\MacvendorsApi;

$api = new MacvendorsApi();                 // keyless
$vendor = $api->get_vendor('08:74:02:00:00:00');

echo $vendor['company'];       // "Cisco Systems, Inc"
echo $vendor['mac_prefix'];    // "08:74:02"
echo $vendor['address'];       // "" without a key, full address with one

echo $api->vendor('08:74:02:00:00:00');     // "Cisco Systems, Inc" (plain string)

API key

get_vendor(), get_vendor_*() and vendor() work with no key. The advanced methods need one:

$api = new MacvendorsApi('mk_live_xxx');
// or later:
$api->set_api_key('mk_live_xxx');

A free key (1,000 lookups a day) is instant at macadress.com/signup. See pricing for the paid tiers.

The key is sent as Authorization: Bearer <key>.

Legacy methods

Unchanged signatures, same return shapes as the original class.

Method	Returns
`get_vendor($query, $type = 'json')`	assoc array with `company`, `mac_prefix`, `address` (plus `country`, `block_type`, `registered`, `is_private`, `raw` when a key is set), or `false`
`get_vendor_json($query)`	JSON string
`get_vendor_csv($query)`	`company,mac_prefix,address`
`get_vendor_pipe($query)`	`company
`get_vendor_xml($query)`	XML string

$query is a MAC address. With a key it can also be a company name or address, resolved through the vendor directory (first match wins). macadress.com serves JSON only, so the CSV / pipe / XML strings are built on the client from the structured result.

macadress.com methods

Method	Key	What it does
`vendor($mac)`	no	Vendor name as a plain string, or `null` when there is none (unregistered, broadcast, locally administered / randomized).
`health()`	no	`true` when the API and its database are reachable.
`lookup($mac)`	yes	Full analysis: organization, OUI, IEEE block type, country, vendor address, transmission and administration type, EUI-64, IPv6 link-local, randomization confidence, device guess, registry metadata, database version.
`batch(array $macs)`	yes	Up to 100 addresses in one request. Results in input order; each carries an `error` key when that entry failed.
`extract($text)`	yes	Pull every MAC-looking substring out of free text (arp output, logs, DHCP leases) and look them all up.
`search_vendors($query, $options)`	yes	Search the registered vendor / block directory. `$options`: `country` (ISO alpha-2), `limit` (1 to 100). Returns `total` and `blocks`.

$api = new MacvendorsApi(getenv('MACADRESS_API_KEY'));

$r = $api->lookup('3C:22:FB:12:34:56');
echo $r['organization'];        // "Apple, Inc."
echo $r['country'];             // "US"
echo $r['block_type'];          // "MA-L"
echo $r['eui64'];               // "3E:22:FB:FF:FE:12:34:56"
echo $r['ipv6_link_local'];     // "fe80::3e22:fbff:fe12:3456"

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

$found = $api->extract('192.168.1.5 at 3c:22:fb:aa:bb:cc');
echo $found['count'];           // 1

$search = $api->search_vendors('Cisco', ['country' => 'US', 'limit' => 10]);
echo $search['total'];

Errors

The legacy methods return false when there is no match. The macadress.com methods throw Macvendors\Api\ApiException on failure:

use Macvendors\Api\ApiException;

try {
    $r = $api->lookup($mac);
} catch (ApiException $e) {
    // $e->statusCode   400 invalid MAC, 401 bad key, 429 rate limit / quota
    // $e->requestId    when the response carried one
    // $e->responseBody raw body
    error_log("macadress {$e->statusCode}: {$e->getMessage()}");
}

batch() and extract() also throw InvalidArgumentException before any request when the input is empty or over the limit.

Options

$api = new MacvendorsApi('mk_live_xxx', [
    'base_uri'        => 'https://api.macadress.com',  // change for a self-hosted deployment
    'timeout'         => 10.0,
    'connect_timeout' => 5.0,
    'user_agent'      => 'my-app/1.0',
]);

Upgrading from the old macvendors.co class

get_vendor() and the get_vendor_*() methods work as before.
Namespace is now Macvendors\Api. Old code using \macvendors_co\MacvendorsApi still resolves through a class alias.
Address, country and IEEE block data need an API key now; without one get_vendor() fills company and mac_prefix only.
Name / address search needs an API key.

License

MIT. See LICENSE.

macvendors / macvendors-api

Package info

Security

Statistics