# eBay Search

Search eBay to retrieve listing results with pricing, condition, seller, and shipping data in JSON format.

## Endpoint

```
GET /v1/ebay/search/{query}
```

## Description

The eBay Search endpoint allows you to search eBay listings and retrieve structured result data. The query parameter should be a URL-encoded query string.

## Authentication

All requests require authentication using the `X-Api-Key` header. See the [Authentication guide](/docs/guides/authentication) for more details.

## Path Parameters

### `query` (required)

**Type:** `string`

A URL-encoded query string for the eBay search.

**Examples:**
- `q=vinyl+records`
- `q=iphone+15+case`

## Request Headers

### `X-Proxy-Location` (optional)

**Type:** `string`

Specify the proxy location for the search. Supported countries: `EU`, `CA`, `US`, `IE`, `GB`, `FR`, `DE`, `SE`, `IN`, `JP`, `KR`, `SG`, `AU`, `BR`.

### `X-User-Agent` (optional)

**Type:** `string`

Optional header to specify device type `desktop` or `mobile`. Defaults to `desktop`.

**Allowed values:** `desktop`, `mobile`

## Example Requests

### cURL

```bash
curl --request GET \
  --url 'https://api.serply.io/v1/ebay/search/q=vinyl+records' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

### JavaScript

```javascript
const response = await fetch('https://api.serply.io/v1/ebay/search/q=vinyl+records', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
```

### Python

```python
import requests

url = "https://api.serply.io/v1/ebay/search/q=vinyl+records"
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)
```

## Response

The response is a JSON object containing organic listing results from eBay.

### Response Structure

```json
{
  "results": [
    {
      "title": "string",
      "link": "string",
      "position": "number",
      "result_type": "string",
      "metadata": {
        "price": "string",
        "was_price": "string",
        "condition": "string",
        "image": "string",
        "seller": "string",
        "seller_feedback": "string",
        "attributes": ["string"]
      }
    }
  ],
  "total": "number",
  "query": "string",
  "ts": "number",
  "device_region": "string",
  "device_type": "null"
}
```

### Response Fields

#### `results` (array)

An array of listing objects, each containing:

- **`title`** (string): Listing title
- **`link`** (string): URL to the listing on eBay
- **`position`** (number): Position of the listing in search results
- **`result_type`** (string): Result classification, e.g. `organic`
- **`metadata`** (object): Additional listing details
  - **`price`** (string): Current listing price, as displayed
  - **`was_price`** (string, optional): Pre-discount price, present only when the listing shows a markdown
  - **`condition`** (string): Item condition, e.g. `Pre-Owned`, `New`
  - **`image`** (string): URL to the listing's thumbnail image
  - **`seller`** (string): Seller username
  - **`seller_feedback`** (string): Seller feedback score and percentage, as displayed
  - **`attributes`** (array of strings): Additional listing details such as shipping cost, delivery estimate, item location, or `or Best Offer`

#### `total` (number)

Reported total match count. This field is not yet reliable and currently returns `0` regardless of the actual number of matching listings — use the length of `results` for a real count.

#### `query` (string)

The search query that was run.

#### `ts` (number)

Time in seconds the request took to complete.

#### `device_region` (string)

Proxy region used for the request, if specified via `X-Proxy-Location`.

#### `device_type` (null)

Device type used for the search.

### Example Response

```json
{
  "results": [
    {
      "title": "Prince - Welcome 2 America 12” Vinyl Album 2x Records With One Etched Side",
      "link": "https://www.ebay.com/itm/267755938013?epid=...",
      "position": 1,
      "result_type": "organic",
      "metadata": {
        "price": "$27.06",
        "was_price": "$27.00",
        "condition": "Pre-Owned",
        "image": "https://i.ebayimg.com/images/g/.../s-l500.webp",
        "seller": "dshvinyl",
        "seller_feedback": "100% positive (1.2K)",
        "attributes": [
          "or Best Offer",
          "+$4.94 delivery in 2-3 days",
          "Located in United Kingdom"
        ]
      }
    }
  ],
  "total": 0,
  "query": "vinyl records",
  "ts": 2.53,
  "device_region": "",
  "device_type": null
}
```

## Status Codes

- **200 OK**: Successful request
- **201 Created**: Request processed successfully
- **404 Not Found**: Resource not found
- **422 Unprocessable Entity**: Validation error
- **429 Too Many Requests**: Rate limit exceeded

## Error Handling

If an error occurs, the API will return an appropriate HTTP status code with an error message in the response body.