mouser

What this skill does

# Mouser Electronics Parts Search & Analysis

## Related Skills

| Skill | Purpose |
|-------|---------|
| `kicad` | Schematic analysis — extracts MPNs for part lookup |
| `bom` | BOM management — orchestrates sourcing across distributors |
| `digikey` | Primary prototype source (prefer for datasheets — direct PDF links) |
| `spice` | Uses Mouser parametric data for behavioral SPICE models |

Mouser is the **secondary source for prototype orders** — use when DigiKey is out of stock or has worse pricing. For production orders, see `lcsc`/`jlcpcb`. For BOM management and export workflows, see `bom`. For datasheets, prefer DigiKey's API (direct PDF links) — Mouser blocks automated PDF downloads.

## API Credential Setup

Mouser uses **simple API key authentication** — no OAuth, no tokens, no callback URLs. The Search API key is a UUID passed as a query parameter.

### Getting Your API Key

1. Go to [mouser.com](https://www.mouser.com) → My Mouser → My Account
2. Under "APIs" section, click "Manage"
3. Register for **Search API** key — this is the one needed for part lookups and datasheet downloads
4. Search API keys may require approval (status shows "pending authorization" initially)

### Setting Credentials

Set the environment variable before running the scripts:
```bash
export MOUSER_SEARCH_API_KEY=your-search-api-key-uuid
```

If credentials are stored in a central secrets file (e.g., `~/.config/secrets.env`), load them first:
```bash
export $(grep -v '^#' ~/.config/secrets.env | grep -v '^$' | xargs)
```

## Mouser Search API Reference

All search endpoints use the Search API key as a query parameter: `?apiKey=<key>`. Content-Type is `application/json` for all POST requests.

### V1 Endpoints

#### Keyword Search
```
POST /api/v1/search/keyword?apiKey=<key>
```
```json
{
  "SearchByKeywordRequest": {
    "keyword": "100nF 0402 ceramic capacitor",
    "records": 50,
    "startingRecord": 0,
    "searchOptions": "InStock"
  }
}
```
- `searchOptions`: `"None"` | `"Rohs"` | `"InStock"` | `"RohsAndInStock"`
- `records`: max 50 per request
- `startingRecord`: offset for pagination

#### Part Number Search
```
POST /api/v1/search/partnumber?apiKey=<key>
```
```json
{
  "SearchByPartRequest": {
    "mouserPartNumber": "GRM155R71C104KA88D|RC0402FR-0710KL",
    "partSearchOptions": "Exact"
  }
}
```
- Up to **10 part numbers**, pipe-separated (`|`)
- Works with both Mouser part numbers AND manufacturer part numbers (MPNs)
- `partSearchOptions`: `"Exact"` | `"BeginsWith"` | `"Contains"`

### V2 Endpoints

V2 adds manufacturer filtering and pagination by page number.

#### Keyword + Manufacturer Search
```
POST /api/v2/search/keywordandmanufacturer?apiKey=<key>
```
```json
{
  "SearchByKeywordMfrNameRequest": {
    "keyword": "LMR51450",
    "manufacturerName": "Texas Instruments",
    "records": 25,
    "pageNumber": 1,
    "searchOptions": "InStock"
  }
}
```
Note: the wrapper object name is `SearchByKeywordMfrNameRequest` (not `SearchByKeywordMfrRequest` — the V1 name is deprecated).

#### Part Number + Manufacturer Search
```
POST /api/v2/search/partnumberandmanufacturer?apiKey=<key>
```

#### Manufacturer List
```
GET /api/v2/search/manufacturerlist?apiKey=<key>
```
Returns the full list of manufacturer names for use in filtered searches.

### V1 Deprecated Endpoints

These still work but V2 equivalents are preferred:
- `POST /api/v1/search/keywordandmanufacturer` → use V2
- `POST /api/v1/search/partnumberandmanufacturer` → use V2
- `GET /api/v1/search/manufacturerlist` → use V2

## Search Response Structure

All search endpoints return the same response format:

```json
{
  "Errors": [],
  "SearchResults": {
    "NumberOfResult": 142,
    "Parts": [...]
  }
}
```

### Key Part Fields

| Field | Type | Description |
|-------|------|-------------|
| `MouserPartNumber` | string | Mouser's internal part number (prefixed, e.g., `81-GRM155R71C104KA88`) |
| `ManufacturerPartNumber` | string | Manufacturer's part number (MPN) — use for cross-distributor matching |
| `Manufacturer` | string | Manufacturer name |
| `Description` | string | Product description |
| `Category` | string | Product category |
| `DataSheetUrl` | string | URL to datasheet PDF (Mouser-hosted — see Datasheet section) |
| `ProductDetailUrl` | string | URL to Mouser product page |
| `ImagePath` | string | Product image URL |
| `Availability` | string | Human-readable stock text (e.g., "2648712 In Stock") |
| `AvailabilityInStock` | string | Numeric stock quantity (as string) |
| `AvailabilityOnOrder` | array | Incoming stock: `[{Quantity, Date}]` |
| `LeadTime` | string | Factory lead time (e.g., "84 Days") |
| `LifecycleStatus` | string\|null | "New Product", "End of Life", etc. |
| `IsDiscontinued` | string | "true" or "false" (string, not boolean) |
| `SuggestedReplacement` | string | Replacement MPN if discontinued |
| `Min` | string | Minimum order quantity (as string) |
| `Mult` | string | Order multiple (as string) |
| `Reeling` | bool | Tape-and-reel packaging available |
| `ROHSStatus` | string | RoHS compliance status |
| `PriceBreaks` | array | Tiered pricing: `[{Quantity, Price, Currency}]` |
| `ProductAttributes` | array | Parametric specs: `[{AttributeName, AttributeValue}]` |
| `AlternatePackagings` | array\|null | Alternate packaging MPNs: `[{APMfrPN}]` |
| `SurchargeMessages` | array | Tariff/surcharge info: `[{code, message}]` |
| `ProductCompliance` | array | HTS codes, ECCN: `[{ComplianceName, ComplianceValue}]` |
| `UnitWeightKg` | object | `{UnitWeight: <float>}` in kg |

### Quirks and Gotchas

- **Price is a string** with currency symbol: `"$0.10"`, not a float. Parse it before comparing.
- **Stock is a string**: `AvailabilityInStock` returns `"2648712"` not `2648712`.
- **IsDiscontinued is a string**: `"true"` or `"false"`, not boolean.
- **Mouser part numbers have prefixes**: `81-GRM155R71C104KA88` — the prefix is Mouser-specific. Use `ManufacturerPartNumber` for cross-referencing.
- **V2 wrapper names differ from V1**: V2 uses `SearchByKeywordMfrNameRequest`, not `SearchByKeywordMfrRequest`.
- **Tariff info**: `SurchargeMessages` may contain US tariff percentages — useful for cost estimation.
- **On-order data**: `AvailabilityOnOrder` shows incoming stock quantities and expected dates.

## Datasheet Download & Sync

Mouser's `DataSheetUrl` field points to Mouser-hosted URLs (`mouser.com/datasheet/...`). These URLs **block automated downloads** — they return an HTML "Access denied" page when fetched with Python/curl/wget, even with browser User-Agent headers. The download scripts handle this with a multi-strategy approach:

1. Try the Mouser datasheet URL directly (works for some parts)
2. Scrape the Mouser product page HTML for alternative datasheet links
3. Try manufacturer-specific alternative URL patterns

Note: Mouser's product pages return 403 for most automated requests, so strategy 2 has limited success. DigiKey and LCSC are more reliable datasheet sources.

### Datasheet Directory Sync

Use `sync_datasheets_mouser.py` to maintain a `datasheets/` directory alongside a KiCad project. Same workflow and `manifest.json` format as the DigiKey skill.

```bash
# Sync datasheets for a KiCad project
python3 <skill-path>/scripts/sync_datasheets_mouser.py <file.kicad_sch>

# Preview what would be downloaded
python3 <skill-path>/scripts/sync_datasheets_mouser.py <file.kicad_sch> --dry-run

# Retry previously failed downloads
python3 <skill-path>/scripts/sync_datasheets_mouser.py <file.kicad_sch> --force

# Custom output directory
python3 <skill-path>/scripts/sync_datasheets_mouser.py <file.kicad_sch> -o ./my-datasheets

# Parallel downloads (3 workers)
python3 <skill-path>/scripts/sync_datasheets_mouser.py <file.kicad_sch> --parallel 3

# Batch mode — sync from a plain MPN list (no KiCad project required)
python3 <skill-path>/scripts/sync_datasheets_mouser.py --mpn-list mpns.txt --output ./datasheets
```

**MPN-list batch mode** (KH-312) — when you have a list of MPN