macadress

Official JavaScript and TypeScript client for the macadress.com MAC address and OUI vendor lookup API.

• Vendor name, OUI, IEEE block, country, address type, EUI-64 / IPv6 link-local, randomization confidence, device guess
• Keyless vendor-name lookup, plus keyed single / batch / directory-search endpoints
• Typed results and a typed error per failure mode
• Zero dependencies. Runs on Node 18+, Deno, Bun and browsers on the platform fetch
• Ships ESM + CommonJS + .d.ts on npm, and TypeScript source on JSR

import { Client } from "macadress";

const macadress = new Client("mk_live_xxx");

await macadress.vendor("00:03:93:AB:12:34");            // "Apple, Inc."   (no API key required)
(await macadress.lookup("00:03:93:AB:12:34")).country; // "US"

Install

npm install macadress

// Deno
import { Client } from "jsr:@macadress/sdk";
// or:  deno add jsr:@macadress/sdk

// Bun
// bun add macadress

// Browser / no build step
import { Client } from "https://esm.sh/macadress";

Getting a key

vendor() needs no key. Everything else does. A free key (1,000 lookups a day) is instant at macadress.com/signup; see pricing for more.

Usage

Create a client

import { Client } from "macadress";

const macadress = new Client("mk_live_xxx");

// keyless: only vendor() will work
const anon = new Client();

// options (an object may be passed as the only argument too)
const configured = new Client("mk_live_xxx", {
  baseUri: "https://api.macadress.com", // change only for a self-hosted deployment
  timeout: 10_000,                      // milliseconds
  headers: { "X-Trace": "my-app" },
  fetch: myFetch,                       // inject a fetch implementation
});

vendor() - name only, no key

Resolves to the vendor string, or null when the address is valid but has no vendor to report (unregistered, private, or locally administered / randomized).

await macadress.vendor("00:03:93:AB:12:34");   // "Apple, Inc."
await macadress.vendor("02:1a:2b:3c:4d:5e");   // null

:, -, . and space grouping are all accepted; a bare 12-hex string works too.

lookup() - full analysis

const r = await macadress.lookup("3C:22:FB:12:34:56");

r.organization;              // string | null
r.isVendorLookupReliable;    // boolean  (false for a private block / LAA)
r.oui;                       // "3C:22:FB"
r.matchedPrefix;             // full matched block at its real width
r.blockType;                 // "MA-L" | "MA-M" | "MA-S" | "IAB" | "CID" | null
r.country;                   // "US" | null
r.administrationType;        // "universally_administered" | "locally_administered"
r.isPotentiallyRandomized;   // boolean
r.randomizationConfidence;   // "none" | "possible" | "likely"
r.eui64;                     // "3E:22:FB:FF:FE:12:34:56" | null
r.ipv6LinkLocal;             // "fe80::3e22:fbff:fe12:3456" | null
r.device.category;           // "unknown" (usually)
r.explanation;               // plain-English summary
r.databaseVersion;           // "2026-08-30" (UTC sync date)

Any field without a typed getter is still reachable:

r.get("vendor_location.city");   // dot path, undefined if absent
r.raw;                           // the decoded payload as given
JSON.stringify(r);               // the same payload back out

Enum values are plain strings; the exported objects give you named constants:

import { BlockType } from "macadress";
if (r.blockType === BlockType.MaL) { /* ... */ }

batch() - up to 100 at once

Results come back in input order; check each item for a per-entry error.

for (const item of await macadress.batch(["00:03:93:00:00:00", "3C:22:FB:00:00:00", "bad"])) {
  console.log(item.failed ? `${item.input} -> ERROR ${item.error}` : `${item.input} -> ${item.organization}`);
}

Throws TypeError (no request made) if the array is empty or has more than 100 entries.

searchVendors() - the directory

const result = await macadress.searchVendors("Cisco", { country: "US", limit: 20 });

result.total;   // total matches, ignoring the limit
for (const block of result) {
  console.log(`${block.blockType} ${block.organization} (${block.country})`);
}

health()

await macadress.health();   // boolean, keyless, uncounted

Errors

Every failure is an instance of MacadressError.

| Class | When | |---|---| | InvalidMacError | HTTP 400, the input did not parse | | AuthenticationError | HTTP 401, missing or invalid API key | | RateLimitError | HTTP 429, per-minute rate exceeded. .retryAfter (seconds) when sent | | QuotaExceededError | HTTP 429, billing-cycle quota spent. Subclass of RateLimitError | | ApiError | any other 4xx/5xx, or an unreadable response | | TransportError | never reached the API: DNS, connection, TLS, timeout. .cause holds the original | | ConfigurationError | bad client options (thrown before any request) |

Each carries .statusCode, .requestId and .responseBody where available.

import { Client, RateLimitError, MacadressError } from "macadress";

try {
  const r = await macadress.lookup(input);
} catch (error) {
  if (error instanceof RateLimitError) {
    await sleep((error.retryAfter ?? 5) * 1000);
  } else if (error instanceof MacadressError) {
    report(`macadress ${error.statusCode}: ${error.message} (${error.requestId})`);
  } else {
    throw error;
  }
}

Runtimes

The client calls the global fetch, Headers, URL and AbortSignal.timeout, so it runs unchanged on:

• Node 18+ (fetch is built in)
• Deno and Bun
• Browsers, Cloudflare Workers, and other edge runtimes

On an older runtime, pass your own fetch through the fetch option.

Examples

Runnable scripts in examples/ (build first: npm run build):

node examples/01-vendor-name.mjs 00:03:93:AB:12:34
MACADRESS_API_KEY=mk_live_xxx node examples/02-full-lookup.mjs 3C:22:FB:00:00:00
MACADRESS_API_KEY=mk_live_xxx node examples/03-batch.mjs
MACADRESS_API_KEY=mk_live_xxx node examples/04-search-vendors.mjs Cisco US
deno run --allow-net examples/deno.ts 00:03:93:AB:12:34

Development

Contributing needs Node 22+ (the test run strips TypeScript types natively). The published bundle targets Node 18+.

npm install
npm run typecheck    # tsc --noEmit
npm test             # node --test
npm run build        # tsup -> dist/ (esm + cjs + d.ts)

The version lives in src/version.ts; keep package.json, jsr.json and the CHANGELOG heading in step with it on a release.

Links

• API reference: https://macadress.com/docs
• Issues: https://github.com/sapisos/macadress-js/issues
• PHP client: https://github.com/sapisos/macadress-php

License

MIT, see LICENSE. A product of ApisOS FZE.