# Newegg Search

## Overview

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

## Description

Newegg Search API: search product listings by keyword or URL on Newegg. Returns prices, ratings, stock flags, marketplace/combo signals 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/newegg/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'ryzen 5 9600x' on newegg.com (page 1)

```json
{
  "results": [
    {
      "url": "https://www.newegg.com/amd-ryzen-5-9000-series-ryzen-5-9600x-granite-ridge-socket-am5-desktop-cpu-processor/p/N82E16819113844",
      "brand": "AMD",
      "model": "100-100001405WOF",
      "price": 189.99,
      "title": "AMD Ryzen 5 9600X - Ryzen 5 9000 Series Granite Ridge (Zen 5) 6-Core 3.9 GHz - Socket AM5 65W - Radeon Graphics Processor - 100-100001405WOF",
      "rating": 4.8,
      "currency": "USD",
      "in_stock": true,
      "is_combo": false,
      "image_url": "https://c1.neweggimages.com/ProductImageCompressAll300/19-113-844-05.jpg",
      "product_id": "N82E16819113844",
      "item_number": "19-113-844",
      "availability": "in_stock",
      "review_count": 484,
      "is_marketplace": false,
      "is_refurbished": false,
      "original_price": 279,
      "promotion_text": "+ $10 off w/ promo code SSF69677, limited offer"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "keyword": "ryzen 5 9600x",
    "per_page": 20,
    "total_pages": 1,
    "total_results": 8
  }
}
```

## Documentation

## Overview
The **Newegg Search API** returns product listings from Newegg. Pass a **keyword** or a **full search URL** and receive structured JSON with prices, ratings, stock flags, marketplace/combo signals, and pagination.

Piloterr uses **browser rendering** and parses embedded `window.__initialState__` JSON from the search results page.

Use each result `url` or `product_id` with [Newegg Product](https://www.piloterr.com/library/newegg-product) for full PDP data (specs, images, promo codes, seller info).

## Quickstart
```
GET https://api.piloterr.com/v2/newegg/search?query=ryzen+5+9600x
GET https://api.piloterr.com/v2/newegg/search?query=https://www.newegg.com/p/pl?d=ryzen+5+9600x
GET https://api.piloterr.com/v2/newegg/search?query=laptops&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or full Newegg search URL (`/p/pl?d=…`) |
| `page` | integer | no | 1-based page number (default: 1) |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example |
|---|---|
| Keyword | `ryzen 5 9600x` → `https://www.newegg.com/p/pl?d=ryzen+5+9600x` |
| Full URL | `https://www.newegg.com/p/pl?d=ryzen+5+9600x` |
| Paginated URL | `https://www.newegg.com/p/pl?d=laptops&page=2` |

## Response: each listing (`results[]`)
| Field | Type | Description |
|---|---|---|
| `product_id` | string | `N82E168…` (Newegg catalog), `9SI…` (marketplace), or combo ID |
| `item_number` | string | Internal Newegg item number |
| `title` | string | Product or combo title |
| `url` | string | PDP or combo page URL |
| `price` | number | Final price |
| `original_price` | number | Strikethrough / MSRP |
| `currency` | string | `USD` on www.newegg.com |
| `brand` | string \| null | Brand name |
| `model` | string \| null | Manufacturer model / MPN |
| `rating` | number \| null | Rating out of 5 |
| `review_count` | integer \| null | Review count |
| `image_url` | string \| null | Main thumbnail |
| `in_stock` | boolean \| null | Raw availability flag |
| `availability` | string \| null | `in_stock` / `out_of_stock` |
| `promotion_text` | string \| null | Display promo text |
| `is_combo` | boolean | Bundle listing |
| `is_marketplace` | boolean | Third-party seller (`9SI…`) |
| `is_refurbished` | boolean | Newegg Refreshed (`T` suffix) |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Page size (20 default) |
| `total_results` | integer \| null | Total matches |
| `total_pages` | integer \| null | Total pages |
| `next` | string \| null | Next page URL |
| `keyword` | string | Search term (`d=` param) |

## Newegg API workflow
1. [Newegg Search](https://www.piloterr.com/library/newegg-search): discover listings by keyword or URL (this endpoint)
2. [Newegg Product](https://www.piloterr.com/library/newegg-product): fetch full PDP JSON from `product_id`, item number, or URL

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Page without `__initialState__` or no parseable results |
| `500` | Rendering or parsing error |

## Notes
- Combo deals appear in search results but are not supported by **Newegg Product** yet.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Price monitoring**: track Newegg first-party vs marketplace offers
- **Catalog discovery**: harvest `product_id` and URLs at scale
- **Promo tracking**: capture `promotion_text` and discount deltas