MAC Address Vendor Lookup API

A FastAPI service that identifies network device manufacturers from MAC addresses using a three-tier lookup strategy for optimal performance and reliability.

Features

• Multi-format MAC address support: Accepts various formats (with/without separators)
• Partial MAC lookup: Works with full addresses or just the first 6 digits (OUI)
• Three-tier lookup strategy:
  1. Local file cache (fastest)
  2. GitHub vendor database fallback
  3. External API fallback (macvendors.com)
• Standardized output: Returns MAC addresses in dash-separated format

Supported MAC Address Formats

All of these formats are accepted:

• 000000 (OUI only)
• 00:00:01
• 00-00-02-AB-CD-EF
• 000003ABCDEF
• 00 00 04 12 34 56

How to Deploy

Using Docker Compose

services:
  api:
    image: git.shihaam.dev/shihaam/macvendors
    ports:
      - 5000:8000

Using Docker

# Pull and run
docker run -p 5000:8000 git.shihaam.dev/shihaam/macvendors

# With local MAC vendor file
docker run -p 5000:8000 -v $(pwd)/mac_list.txt:/app/mac_list.txt git.shihaam.dev/shihaam/macvendors

Local Development

# Install dependencies
pip install fastapi uvicorn httpx

# Run the server
uvicorn macvendorapi:app --host 0.0.0.0 --port 8000

API Usage

Endpoint

GET /lookup/{mac_address}

Examples

# Basic lookup
curl http://localhost:5000/lookup/70-22-FE

# Different formats
curl http://localhost:5000/lookup/7022FE
curl http://localhost:5000/lookup/70:22:FE
curl http://localhost:5000/lookup/70-22-FE-12-34-56

Expected Response

{
  "mac_address": "70-22-FE",
  "vendor": "Apple, Inc."
}

Error Responses

Invalid MAC address:

{
  "detail": "Invalid MAC address format"
}

Unknown vendor:

{
  "mac_address": "FF-FF-FF",
  "vendor": "Unknown"
}

Local MAC Vendor File

To improve performance, you can provide a local mac_list.txt file in the same format as the IEEE OUI database:

000000	Officially Xerox
000001	SuperLAN-2U
000002	BBN (was internal usage only, no longer used)

Lookup Strategy

1. Local File: Checks mac_list.txt first (fastest, no network calls)
2. GitHub Database: Falls back to the official IEEE OUI database
3. External API: Uses macvendors.com API as final fallback
4. Unknown: Returns "Unknown" if no matches found

Building from Source

# Clone repository
git clone <repository-url>
cd macvendors

# Build Docker image
docker build -t mac-vendor-api .

# Run container
docker run -p 8000:8000 mac-vendor-api

Health Check

curl http://localhost:5000/

Returns:

{
  "message": "MAC Address Vendor Lookup API"
}