element14

What this skill does

# element14 / Newark / Farnell — Component Search, Datasheets & Ordering

## Related Skills

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

One API covers three regional storefronts — same catalog, same datasheets, only pricing/stock vary by region:

| Storefront | Region | Store ID |
|------------|--------|----------|
| **Newark** | North America | `www.newark.com` |
| **Farnell** | UK / Europe | `uk.farnell.com` |
| **element14** | Asia-Pacific | `au.element14.com` |

For BOM management and export workflows, see `bom`.

## Key Differences from DigiKey/Mouser

- **Simple auth** — API key as a query parameter, no OAuth flow
- **Free API key** — register at partner.element14.com, courtesy usage allowance
- **Global coverage** — same API covers US (Newark), EU (Farnell), APAC (element14)
- **Unprotected PDFs** — datasheets hosted on farnell.com CDN, download freely with no bot protection
- **Datasheet URL in API response** — `responseGroup=medium` includes `datasheets[].url`

## API Credential Setup

1. **Register** at [partner.element14.com/member/register](https://partner.element14.com/member/register)
   - Free account — just username, email, password. No credit card needed.
   - Provides a "courtesy usage allowance" (2 calls/sec, 1,000 calls/day — sufficient for normal use)
2. **Register an application** — after logging in, go to [My API Keys](https://partner.element14.com/apps/mykeys) and click "Get API Keys"
   - App name: anything (e.g., "kicad-happy")
   - Type: "Desktop application"
   - Users: "1-10"
   - Commercial: No
   - Advertising: No
   - Check "Issue a new key for Product Search API" → select "Basic" tier
   - Agree to Terms of Service and click "Register Application"
3. **Copy your API key** — a 24-character alphanumeric string shown on the My API Keys page
4. **Set the environment variable** `ELEMENT14_API_KEY` before running the scripts:
   ```bash
   export ELEMENT14_API_KEY=your_api_key_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)
   ```

## Product Search API

**Base URL:** `https://api.element14.com/catalog/products`

All requests use GET with query parameters. Authentication is via `callInfo.apiKey`.

### Search Modes

The `term` parameter supports three search types:

| Mode | Format | Example |
|------|--------|---------|
| **Keyword** | `any:<keywords>` | `term=any:100nF 0402 X7R` |
| **MPN** | `manuPartNum:<mpn>` | `term=manuPartNum:GRM155R71C104KA88D` |
| **Distributor PN** | `id:<sku>` | `term=id:94AK6874` |

### Full Example

```
GET https://api.element14.com/catalog/products
  ?term=manuPartNum:GRM155R71C104KA88D
  &storeInfo.id=www.newark.com
  &resultsSettings.offset=0
  &resultsSettings.numberOfResults=10
  &resultsSettings.responseGroup=medium
  &callInfo.responseDataFormat=JSON
  &callInfo.apiKey=YOUR_KEY
```

### Response Groups

| Group | Fields |
|-------|--------|
| `small` | SKU, displayName, brandName, MPN, attributes |
| `medium` | + datasheets[], prices[], stock |
| `large` | + images, related products, country of origin |
| `prices` | Tiered pricing only |
| `inventory` | Stock levels by warehouse/region |

### Response Format

With `responseGroup=medium`, the response looks like:

```json
{
  "manufacturerPartNumberSearchReturn": {
    "numberOfResults": 5,
    "products": [
      {
        "sku": "94AK6874",
        "displayName": "Murata GRM155R71C104KA88D",
        "translatedManufacturerPartNumber": "GRM155R71C104KA88D",
        "brandName": "Murata Electronics",
        "datasheets": [
          {
            "type": "TechnicalDataSheet",
            "description": "Datasheet",
            "url": "https://www.farnell.com/datasheets/74273.pdf"
          }
        ],
        "prices": [
          {
            "from": 1,
            "to": 9,
            "cost": 0.156
          }
        ],
        "stock": {
          "level": 45000,
          "leastLeadTime": 0,
          "status": 4,
          "statusMessage": "In Stock"
        },
        "attributes": [
          {"attributeLabel": "Capacitance", "attributeUnit": "", "attributeValue": "100nF"},
          {"attributeLabel": "Voltage Rating", "attributeUnit": "V", "attributeValue": "16"}
        ],
        "rohsStatusCode": "YES"
      }
    ]
  }
}
```

Key fields:
- `sku` — Newark/Farnell/element14 part number
- `translatedManufacturerPartNumber` — MPN
- `brandName` — manufacturer
- `datasheets[].url` — **direct PDF URL** (farnell.com CDN, no bot protection)
- `datasheets[].type` — usually `TechnicalDataSheet`
- `prices[]` — tiered pricing with `from`, `to`, `cost`
- `stock.level` — quantity in stock
- `stock.statusMessage` — human-readable availability
- `attributes[]` — parametric specs (label, unit, value)
- `rohsStatusCode` — RoHS compliance (`YES`/`NO`)

### Store IDs

Common store IDs for the `storeInfo.id` parameter:

| Store ID | Region |
|----------|--------|
| `www.newark.com` | US (default) |
| `uk.farnell.com` | UK |
| `www.farnell.com` | EU |
| `au.element14.com` | Australia |
| `sg.element14.com` | Singapore |
| `in.element14.com` | India |

### Rate Limits

No documented rate limits beyond the courtesy usage allowance. Be respectful — use 0.5s delays between calls.

### Filters

Add to query parameters:
- `resultsSettings.refinements.filter=rohsCompliant` — RoHS parts only
- `resultsSettings.refinements.filter=inStock` — in-stock only

### Pagination

- `resultsSettings.offset` — starting index (0-based)
- `resultsSettings.numberOfResults` — max 50 per page
- Only the first 100 results are reliably pageable

## Datasheet Download & Sync

element14's farnell.com CDN serves datasheet PDFs directly — no bot protection, no special headers needed. Datasheet URLs come from the API response (`datasheets[].url`).

### Datasheet Directory Sync

Use `sync_datasheets_element14.py` to maintain a `datasheets/` directory alongside a KiCad project. Same workflow and `manifest.json` format as the DigiKey, Mouser, and LCSC skills.

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

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

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

# Use a specific store (default: www.newark.com)
python3 <skill-path>/scripts/sync_datasheets_element14.py <file.kicad_sch> --store uk.farnell.com

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

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

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

**MPN-list batch mode** (KH-312) — when you have a list of MPNs but no
KiCad project to point at. One MPN per line; blank lines and `#`
comments (full-line and inline) are skipped; generic values are filtered
via `is_real_mpn()` and de-duplicated. Output defaults to `./datasheets/`
in the current working directory when `--output` is omitted. Note:
`ELEMENT14_API_KEY` is still required even in dry-run mode; see the
v1.4 follow-up in the issue tracker if dry-run credential-independence
matters for your workflow.

The script:
- **Runs the kicad schematic analyzer** to extract components, MPNs, and distributor PNs
- **Accepts any identifier** — MPN, Newark/Farnell PN, or other distributor PNs from KiCad symbol properties
- **Prefers MPN search** (`manuPartNum:`)