Ricardo Category Listings API Documentation List Ricardo.ch listings of one category, with the same result fields, filters and pagination as the search endpoint. Leaf and child categories give the best results; find category ids with the categories endpoint. A valid category without listings 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.
6 optional filters available.
string
Required
Ricardo category number, e.g. 82249 for Velos. Leaf and child categories give the best results; 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,
"total": 15443,
"results": [
{
"id": "1327275878",
"url": "https://www.ricardo.ch/de/a/1327275878/",
"city": "Wauwil",
"title": "Pivot Firebird Carbon 27.5 | Fox 38 180 mm - Gr\u00f6sse M",
"currency": "CHF",
"end_date": "2026-11-16T19:51:00Z",
"position": 1,
"zip_code": "6242",
"condition": "acceptable",
"image_url": "https://img.ricardostatic.ch/images/d0bd6c59-a24c-4e62-b0c5-874622ec316f/t_450/pivot-firebird-carbon-275-fox-38-180-mm-groesse-m",
"seller_id": "200095338",
"created_at": "2026-08-18T20:28:00Z",
"offer_type": "fixed_price",
"category_id": "82249",
"buy_now_price": 2800
},
{
"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,
"category_id": "82249"
},
"meta": {
"billable": true,
"endpoint_family": "category"
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
The category_id is missing or not a category number, or the page, limit, price range or language is out of range. This response is not billable.
{
"errors": {
"category_id": [
"A category_id is required, e.g. 82249."
]
},
"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.