# 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
```yml
services:
  api:
    image: git.shihaam.dev/shihaam/macvendors
    ports:
      - 5000:8000
```

### Using Docker
```bash
# 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
```bash
# 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
```bash
# 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:
```json
{
  "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:
```json
{
  "mac_address": "70-22-54",
  "vendor": null,
  "detail": "Vendor not found"
}
```

### Error Response (HTTP 400)
When MAC address format is invalid:
```json
{
  "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](https://gist.githubusercontent.com/aallan/b4bb86db86079509e6159810ae9bd3e4/raw/846ae1b646ab0f4d646af9115e47365f4118e5f6/mac-vendor.txt):

```
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
```bash
# 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
```bash
curl http://localhost:5000/
```

Returns:
```json
{
  "message": "MAC Address Vendor Lookup API"
}
```