Ricardo Search API Documentation 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.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
1 required parameter needed before sending a request.
7 optional filters available.
string
Required
Search keywords, e.g. velo.
coffee shops
string
Optional
Restrict the search to one Ricardo category number, e.g. 82249 for Velos. Use the categories endpoint to find ids.
1234567890
integer
Optional
1-based page number, 1 to 50. Defaults to 1. Ranking shifts between calls, so pages can overlap; ids are unique inside one page.
1
integer
Optional
Results per page, 1 to 100. Defaults to 20.
10
boolean
Optional
Set true to return pure auctions only. Defaults to false.
true
integer
Optional
Minimum price in whole CHF, 0 or higher.
10
integer
Optional
Maximum price in whole CHF. Must be at least price_min.
10
string
Optional
Language of labels and the listing url: de or fr. Defaults to de.
en
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"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
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
The query is missing, or the page, limit, price range or language is out of range. This response is not billable.
{
"errors": {
"query": [
"A search query is required, e.g. velo."
]
},
"message": "The request validation failed"
}Invalid Source Response
Ricardo answered with a response Scrappa could not read. This response is not billable.
{
"error": {
"code": "PARSER_DRIFT",
"message": "Ricardo returned a response Scrappa could not read. Please retry later."
},
"success": false
}Service Unavailable
The upstream service is temporarily unavailable. Please retry shortly.
{
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The Ricardo API is temporarily unavailable. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.