# SnapEDA Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/snapeda/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/snapeda-search |

## Description

SnapEDA Search API: search electronic parts by keyword or URL on SnapMagic Search (ex-SnapEDA). Returns MPN, manufacturer, pricing, CAD availability and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/snapeda/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'USB Type C' on snapeda.com (page 1)

```json
{
  "results": [
    {
      "url": "https://www.snapeda.com/parts/CYPD3175-24LQXQ/Cypress%20Semiconductor/view-part/",
      "price": 0.93,
      "package": "Custom",
      "part_id": "2776245",
      "currency": "USD",
      "image_url": "https://snapeda.s3.amazonaws.com/pinax/images/company_logos/thumbs/Infineon-Logo.svg.png",
      "has_symbol": true,
      "description": "ARM® Cortex®-M0 EZ-PD™ CCG3PA USB Type C Microcontroller IC FLASH (64kB) 24-UFQFN Exposed Pad",
      "part_number": "CYPD3175-24LQXQ",
      "availability": "In Stock",
      "manufacturer": "Cypress Semiconductor",
      "has_footprint": true
    },
    {
      "url": "https://www.snapeda.com/parts/PI5USB30213AXEAEX/Diodes%20Zetex/view-part/",
      "price": 0.89,
      "package": "Custom",
      "part_id": "12128468",
      "currency": "USD",
      "image_url": "https://snapeda.s3.amazonaws.com/pinax/images/company_logos/thumbs/Zetex.jpg",
      "has_symbol": true,
      "description": "High Speed Type-C Dual Role Port Controller USB 3.1 T/R 24-Pin X1QFN EP",
      "part_number": "PI5USB30213AXEAEX",
      "availability": "In Stock",
      "manufacturer": "Diodes Zetex",
      "has_footprint": true
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 218,
    "total_results": 4349
  }
}
```

## Documentation

## Overview
The **SnapEDA Search API** returns electronic component listings from SnapMagic Search (ex-SnapEDA). Pass a **keyword** or a **full search URL** and receive structured JSON with MPN, manufacturer, distributor pricing, CAD availability, and pagination.

Search results load via client-side AJAX (`/api/v1/search_basic`). Piloterr uses **browser rendering** and waits for `.search-result-row` before parsing.

Supported domains: `www.snapeda.com`, `www.snapmagic.com`.

Use each result `url` or `part_number`/`manufacturer` with [SnapEDA Product](https://www.piloterr.com/library/snapeda-product) for full part details (datasheet, CAD formats, distributor pricing).

## Quickstart
```
GET https://api.piloterr.com/v2/snapeda/search?query=USB+Type+C
GET https://api.piloterr.com/v2/snapeda/search?query=https://www.snapeda.com/search/?q=Bluetooth+Module
GET https://api.piloterr.com/v2/snapeda/search?query=USB+Type+C&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or full search URL |
| `page` | integer | no | 1-based page override (default: from URL or `1`) |
| `return_page_source` | boolean | no | Rendered HTML as `{"result": "..."}` (default: `false`) |

## Response: each part (`results[]`)
| Field | Type | Description |
|---|---|---|
| `part_number` | string | MPN |
| `manufacturer` | string | Manufacturer name as displayed |
| `part_id` | string | SnapEDA internal id (`unipart_id`) |
| `url` | string | Part page URL (tracking params stripped) |
| `image_url` | string \| null | Manufacturer logo in search (not part photo) |
| `description` | string \| null | Short description when available |
| `package` | string \| null | Package type (often `Custom`) |
| `availability` | string \| null | e.g. `In Stock`, `Not in stock` |
| `price` | number \| null | Average distributor price |
| `currency` | string \| null | ISO currency (typically USD) |
| `has_symbol` | boolean \| null | Symbol CAD available |
| `has_footprint` | boolean \| null | Footprint CAD available |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Results on this page (20) |
| `total_results` | integer \| null | Total matches |
| `total_pages` | integer \| null | Total pages |

Pagination uses `?q=…&page=2` in the search URL.

## SnapEDA workflow
1. [SnapEDA Search](https://www.piloterr.com/library/snapeda-search): discover parts (this endpoint)
2. [SnapEDA Product](https://www.piloterr.com/library/snapeda-product): full part JSON

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | No parseable search results |
| `500` | Rendering or parsing error |

## Notes
- Search `image_url` is the manufacturer logo, not the part photo (use Product for `#part-image1`).
- Tracking params (`ref`, `t`, `ab_test_case`, `p`) are stripped from returned URLs.
- Costs **2 credits** per call (browser rendering, up to 90s wait).

## Main use cases
- **Component discovery**: harvest MPNs and manufacturers at scale
- **CAD availability**: filter parts with symbol/footprint models
- **BOM enrichment**: pricing and stock signals before fetching full PDP data