digikey

What this skill does

# DigiKey Parts Search & Analysis

## Related Skills

| Skill | Purpose |
|-------|---------|
| `kicad` | Schematic analysis — extracts MPNs for datasheet sync |
| `bom` | BOM management — orchestrates sourcing across distributors |
| `spice` | Uses DigiKey parametric data for behavioral SPICE models |

DigiKey is the **primary source for prototype orders** (Mouser is secondary). Its API returns direct PDF datasheet links, making it the preferred datasheet source. For production orders, see `lcsc`/`jlcpcb`. For BOM management and export workflows, see `bom`.

## API Credential Setup

The DigiKey API requires OAuth 2.0 credentials. Here's how to set them up:

1. **Create a DigiKey account** at [digikey.com](https://www.digikey.com) if you don't have one
2. **Register an API app** at [developer.digikey.com](https://developer.digikey.com):
   - Sign in with your DigiKey account
   - Go to "My Apps" → "Create App"
   - App name: anything (e.g., "kicad-happy")
   - Select **"Product Information v4"** API
   - OAuth type: **Client Credentials** (2-legged, no user login needed)
   - Callback URL: `https://localhost` (not used for client credentials, but required)
   - After creation, note the **Client ID** and **Client Secret**
3. **Set the environment variables** before running the scripts:
   ```bash
   export DIGIKEY_CLIENT_ID=your_client_id_here
   export DIGIKEY_CLIENT_SECRET=your_client_secret_here
   ```
   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)
   ```

The client credentials flow has no user interaction — once configured, API calls work automatically.

## DigiKey Product Information API v4

The API is the preferred way to search DigiKey. It returns structured JSON with full product details, pricing, stock, datasheets, and parametric data.

**Base URL:** `https://api.digikey.com`

### Authentication

All API requests require OAuth 2.0. Use the **client credentials flow** (2-legged). Credentials must be loaded as environment variables (see "API Credential Setup" above).

```bash
curl -s -X POST https://api.digikey.com/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=${DIGIKEY_CLIENT_ID}&client_secret=${DIGIKEY_CLIENT_SECRET}&grant_type=client_credentials"
```

The response returns an `access_token` valid for **10 minutes**. Cache the token in a shell variable and reuse it for subsequent calls in the same session. If you get a 401 error mid-session, the token has expired — re-authenticate to get a fresh one.

### Required Headers

Every API call needs:
```
X-DIGIKEY-Client-Id: ${DIGIKEY_CLIENT_ID}
Authorization: Bearer <access_token>
```

Optional locale headers:
- `X-DIGIKEY-Locale-Language`: `en` (default), `ja`, `de`, `fr`, `ko`, `zhs`, `zht`, `it`, `es`
- `X-DIGIKEY-Locale-Currency`: `USD` (default), `CAD`, `EUR`, `GBP`, `JPY`, etc.
- `X-DIGIKEY-Locale-Site`: `US` (default), `CA`, `UK`, `DE`, etc.

### KeywordSearch — Find Parts

```
POST /products/v4/search/keyword
```

This is the primary search endpoint. Search by MPN, DigiKey part number, description, or keywords.

Request body:
```json
{
  "Keywords": "GRM155R71C104KA88D",
  "Limit": 25,
  "Offset": 0,
  "FilterOptionsRequest": {
    "MinimumQuantityAvailable": 1,
    "SearchOptions": ["InStock", "HasDatasheet", "RoHSCompliant"],
    "ManufacturerFilter": [{"Id": "..."}],
    "CategoryFilter": [{"Id": "..."}],
    "StatusFilter": [{"Id": "..."}],
    "MarketPlaceFilter": "ExcludeMarketPlace"
  },
  "SortOptions": {
    "Field": "Price",
    "SortOrder": "Ascending"
  }
}
```

Key request fields:
- `Keywords` (string, max 250 chars) — search term (MPN, DK PN, description)
- `Limit` (int, 1-50) — results per page
- `Offset` (int) — pagination offset
- `SearchOptions` — array of: `InStock`, `HasDatasheet`, `RoHSCompliant`, `NormallyStocking`, `Has3DModel`, `HasCadModel`, `HasProductPhoto`, `NewProduct`
- `SortOptions.Field` — `Price`, `QuantityAvailable`, `Manufacturer`, `ManufacturerProductNumber`, `DigiKeyProductNumber`, `MinimumQuantity`
- `MarketPlaceFilter` — `NoFilter`, `ExcludeMarketPlace`, `MarketPlaceOnly`

Response — key fields in each `Products[]` item:
```json
{
  "ManufacturerProductNumber": "GRM155R71C104KA88D",
  "Manufacturer": {"Id": 563, "Name": "Murata Electronics"},
  "Description": {
    "ProductDescription": "CAP CER 100NF 16V X7R 0402",
    "DetailedDescription": "..."
  },
  "UnitPrice": 0.01,
  "QuantityAvailable": 248000,
  "ProductUrl": "https://www.digikey.com/...",
  "DatasheetUrl": "https://...",
  "PhotoUrl": "https://...",
  "ProductVariations": [
    {
      "DigiKeyProductNumber": "490-10698-1-ND",
      "PackageType": {"Name": "Cut Tape"},
      "StandardPricing": [
        {"BreakQuantity": 1, "UnitPrice": 0.01, "TotalPrice": 0.01},
        {"BreakQuantity": 10, "UnitPrice": 0.008, "TotalPrice": 0.08}
      ],
      "QuantityAvailableforPackageType": 248000,
      "MinimumOrderQuantity": 1,
      "StandardPackage": 10000
    }
  ],
  "Parameters": [
    {"ParameterText": "Capacitance", "ValueText": "100nF"},
    {"ParameterText": "Voltage Rated", "ValueText": "16V"},
    {"ParameterText": "Temperature Coefficient", "ValueText": "X7R"},
    {"ParameterText": "Package / Case", "ValueText": "0402 (1005 Metric)"}
  ],
  "ProductStatus": {"Status": "Active"},
  "Category": {"Name": "Ceramic Capacitors"},
  "Classifications": {"RohsStatus": "ROHS3 Compliant"},
  "Discontinued": false,
  "EndOfLife": false,
  "NormallyStocking": true
}
```

### ProductDetails — Full Details for One Part

```
GET /products/v4/search/{productNumber}/productdetails
```

Use this for expanded information on a specific part. `{productNumber}` can be a DigiKey part number or manufacturer part number.

Query parameters:
- `manufacturerId` (optional) — disambiguate MPNs that match multiple manufacturers (e.g., "CR2032")

Returns the full `Product` object with all parameters, pricing (including MyPricing if authenticated with account), media links, and related products.

### Other Useful Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/products/v4/search/{pn}/productdetails` | GET | Full product info for one part |
| `/products/v4/search/productpricing/{pn}` | GET | Pricing with MyPricing for a part |
| `/products/v4/search/{pn}/media` | GET | All media (images, datasheets) for a part |
| `/products/v4/search/manufacturers` | GET | All manufacturers (use IDs in KeywordSearch filters) |
| `/products/v4/search/categories` | GET | All categories (use IDs in KeywordSearch filters) |
| `/products/v4/search/{pn}/alternatepackaging` | GET | Alternate packaging options |
| `/products/v4/search/{pn}/substitutions` | GET | Substitute parts |
| `/products/v4/search/{pn}/recommendedproducts` | GET | Recommended/associated parts |

### Rate Limits

Per-minute and daily quotas apply. HTTP 429 with `Retry-After` header on exceed.

### Error Responses

All errors return `DKProblemDetails`:
```json
{"type": "...", "title": "...", "status": 401, "detail": "Invalid token", "correlationId": "..."}
```

## Fallback: Fetch DigiKey Website

If API credentials are not available or authentication fails, search DigiKey by fetching product pages directly:

```
https://www.digikey.com/en/products/result?keywords=<url-encoded-query>
```

Examples:
- `https://www.digikey.com/en/products/result?keywords=GRM155R71C104KA88D` (by MPN)
- `https://www.digikey.com/en/products/result?keywords=100nF+0402+X7R+16V` (by specs)

Results from DigiKey can be noisy (JS-heavy pages). Look for the product table rows containing: DigiKey part number, MPN, description, unit price, stock quantity, and datasheet links. If results are truncated or empty, try searching by exact MPN rather than keywords.

## Datasheet Download & Analysis

DigiKey's API provides **direct PDF URLs** for datasheets — this is the preferred metho