# Ricardo Search API Documentation

<p><strong>Ricardo Search API Documentation</strong> Search Ricardo.ch auctions and fixed-price listings by keyword: for each result the position, id, title, web url, image, category id, offer type (auction, auction_with_buynow or fixed_price), condition (new, like_new, acceptable or damaged), the minimum next bid for auctions, the buy-now price, bid count, end date (ISO 8601, UTC), seller id and nickname, zip code, city and the cheapest paid shipping price. All prices are CHF numbers. Filter by category, auctions only and a CHF price range. total is the upstream hit count and has_more is true while more pages exist. Ranking shifts between calls, so pages can overlap. A valid search without hits is a successful response with an empty results list.</p>

- **Documentation:** [https://scrappa.co/docs/ricardo-api/ricardo_search](https://scrappa.co/docs/ricardo-api/ricardo_search)
- **API group:** Ricardo API
- **Endpoint:** `GET https://scrappa.co/api/ricardo/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 |
| --- | --- | --- | --- |
| `query` | string | Yes | Search keywords, e.g. velo. |
| `category_id` | string | No | Restrict the search to one Ricardo category number, e.g. 82249 for Velos. Use the categories endpoint to find ids. |
| `page` | integer | No | 1-based page number, 1 to 50. Defaults to 1. Ranking shifts between calls, so pages can overlap; ids are unique inside one page. |
| `limit` | integer | No | Results per page, 1 to 100. Defaults to 20. |
| `auction_only` | boolean | No | Set true to return pure auctions only. Defaults to false. |
| `price_min` | integer | No | Minimum price in whole CHF, 0 or higher. |
| `price_max` | integer | No | Maximum price in whole CHF. Must be at least price_min. |
| `language` | string | No | Language of labels and the listing url: de or fr. Defaults to de. |

## Example response

```json
{
    "data": {
        "page": 1,
        "limit": 3,
        "query": "velo",
        "total": 65590,
        "results": [
            {
                "id": "1329430148",
                "url": "https://www.ricardo.ch/de/a/1329430148/",
                "city": "Meinier",
                "title": "Velo appartement",
                "currency": "CHF",
                "end_date": "2026-12-11T14:18:00Z",
                "position": 1,
                "zip_code": "1252",
                "condition": "acceptable",
                "image_url": "https://img.ricardostatic.ch/images/99e35507-b0f7-40f5-9c74-503bf9848e76/t_450/velo-appartement",
                "seller_id": "412043312",
                "created_at": "2026-09-12T13:19:00Z",
                "offer_type": "fixed_price",
                "category_id": "41915",
                "buy_now_price": 280
            },
            {
                "id": "1331859138",
                "url": "https://www.ricardo.ch/de/a/1331859138/",
                "city": "Kyburg",
                "title": "Mtb Fully SCOTT made in USA ab Service",
                "currency": "CHF",
                "end_date": "2026-10-15T20:17:00Z",
                "position": 2,
                "zip_code": "8314",
                "condition": "acceptable",
                "image_url": "https://img.ricardostatic.ch/images/07ca7e25-beb1-4497-b245-006a87522ad9/t_450/mtb-fully-scott-made-in-usa-ab-service",
                "seller_id": "409290340",
                "created_at": "2026-10-08T20:36:00Z",
                "offer_type": "auction_with_buynow",
                "category_id": "82249",
                "next_min_bid": 240,
                "buy_now_price": 280
            }
        ],
        "has_more": true
    },
    "meta": {
        "billable": true,
        "endpoint_family": "search"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | The query is missing, or the page, limit, price range or language is out of range. This response is not billable. |
| 503 | Invalid Source Response | Ricardo answered with a response Scrappa could not read. This response is not billable. |
| 503 | Service Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

## 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)