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
• 70-2A:54 (mixed formats)
• 702A-54 (partial mixed)

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

Response Format

Success Response (HTTP 200)

When a vendor is found:

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

Not Found Response (HTTP 404)

When MAC address is valid but vendor is not found:

{
  "mac_address": "70-22-54",
  "vendor": null,
  "detail": "Vendor not found"
}

Error Response (HTTP 400)

When MAC address format is invalid:

{
  "mac_address": "70-22-HI",
  "vendor": null,
  "detail": "Invalid MAC address format"
}

HTTP Status Codes

• 200 OK: Valid MAC address with vendor found
• 400 Bad Request: Invalid MAC address format
• 404 Not Found: Valid MAC address but vendor not found

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)
000003 XEROX CORPORATION

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. Not Found: Returns vendor not found if no matches are 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"
}