# eBay Search

Search eBay.com listings with keyword, category, price, condition, buying-format and free-shipping filters plus the upstream sort orders. Returns the result cards (title, link, product id, condition, price with currency, quantity sold, sponsored flag, shipping, location, thumbnail), related searches, category facets and the approximate total_results. Valid empty results (a filter combination with no matches, a page beyond the last) are billable success.

- **Documentation:** [https://scrappa.co/docs/ebay-api/ebay_search](https://scrappa.co/docs/ebay-api/ebay_search)
- **API group:** eBay API
- **Endpoint:** `GET https://scrappa.co/api/ebay/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | Yes | Free text search, e.g. coffee maker. |
| `category` | integer | No | eBay category id. 0 = all categories. |
| `page` | integer | No | Result page, 1-based. Default: 1. |
| `per_page` | integer | No | Results per page. Allowed: 60, 120, 240. Default: 60. |
| `sort` | integer | No | Upstream sort order: 1, 7, 10, 12, 15 or 16. |
| `buy_it_now` | boolean | No | Only Buy It Now listings. |
| `auction` | boolean | No | Only auction listings. |
| `condition` | array | No | Repeatable condition id, e.g. 1000 = New. |
| `price_min` | number | No | Minimum price. |
| `price_max` | number | No | Maximum price. |
| `free_shipping` | boolean | No | Only listings with free shipping. |
| `preferred_location` | integer | No | Preferred item location filter. |
| `location_postal` | string | No | Postal code for the location filter, e.g. 10001. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/ebay/search?q=coffee+maker&page=1&per_page=60"
```

## Example response

```json
{
    "success": true,
    "data": {
        "query": "coffee maker",
        "page": 1,
        "per_page": 60,
        "total_results": 100000,
        "has_more": true,
        "results": [
            {
                "title": "Automatic 4-Cup Coffee Maker with Glass Carafe, Reusable Filter, and Keep Warm",
                "link": "https://www.ebay.com/itm/287059807763",
                "product_id": "287059807763",
                "price": {
                    "raw": "$22.47",
                    "extracted": 22.47,
                    "currency": "USD"
                },
                "quantity_sold": 27,
                "sponsored": false
            }
        ],
        "related_searches": [
            {
                "query": "coffee maker 12 cup",
                "link": "https://www.ebay.com/sch/i.html?_nkw=coffee+maker+12+cup&_sop=12"
            }
        ],
        "categories": [
            {
                "id": 20625,
                "name": "Kitchen, Dining & Bar"
            }
        ]
    },
    "meta": {
        "endpoint_family": "search"
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
|  | A public parameter is invalid. This response is not billable. |  |
|  | eBay did not return usable data for this request. This response is not billable. |  |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)