Ricardo APIricardo.ch ↗
Search Ricardo.ch listings by keyword, category, and sort order. Returns prices, condition, brand, shipping, and category facets for Switzerland's largest marketplace.
What is the Ricardo API?
The Ricardo.ch API provides access to Switzerland's largest online marketplace through 1 endpoint, search_listings, which returns up to 60 listings per page including fields like title, prices, condition, brand, shipping details, and category facets. It supports keyword search with optional filtering by category slug and sorting by price, relevance, recency, or auction activity, making it practical for price monitoring, inventory research, and category exploration across Ricardo.ch.
curl -X GET 'https://api.parse.bot/scraper/127062df-d927-47e2-9f95-41cc2749072d/search_listings?sort=best&query=laptop' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace ricardo-ch-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Ricardo.ch marketplace SDK — search listings, browse categories, drill into details."""
from parse_apis.ricardo_ch_api import Ricardo, SortOrder, InvalidInput
client = Ricardo()
# Search for laptops sorted by newest, cap at 5 results.
for listing in client.listings.search(query="laptop", sort=SortOrder.NEWEST, limit=5):
price_label = f"CHF {listing.buy_now_price}" if listing.buy_now_price else "auction only"
print(f"{listing.title} — {price_label} [{listing.condition}]")
# Use .first() to grab a single listing for deeper inspection.
hit = client.listings.search(query="macbook", sort=SortOrder.BEST, limit=1).first()
if hit is not None:
print(f"\nTop result: {hit.title}")
print(f" Seller: {hit.seller_id} | Ends: {hit.end_date}")
for ship in hit.shipping:
print(f" Ships from {ship.city} ({ship.zip_code}) — cost {ship.cost}")
# Fetch the full search page to access category facets alongside listings.
page = client.search_pages.search(query="laptop")
print(f"\nTotal results: {page.total_results} across {len(page.categories)} categories")
for cat in page.categories[:3]:
print(f" {cat.name}: {cat.count} listings (slug={cat.slug})")
# Drill into the top category using its slug from the previous response.
top_category = page.categories[0]
for item in client.listings.search(query="laptop", category_slug=top_category.slug, limit=3):
print(f" [{top_category.name}] {item.title}")
# Handle invalid input gracefully.
try:
client.search_pages.search(query="laptop", sort="bad_sort")
except InvalidInput as e:
print(f"\nExpected error: {e.message}")
print("\nexercised: listings.search / search_pages.search / InvalidInput")
Search marketplace listings by keyword, optionally filtered by category and sorted by price or other criteria. Returns paginated results with 60 listings per page. The response includes category facets with slugs that can be used for subsequent filtered searches. Each listing includes pricing (auction bid price and/or buy-now price), condition, brand, seller, and shipping information.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-indexed). Each page returns up to 60 results. |
| sort | string | Sort order for results. |
| queryrequired | string | Search keyword(s) to find listings. |
| category_slug | string | Category slug to filter results, in the format '{name}-{id}' (e.g. 'notebooks-39272', 'sports-41875'). Available slugs are returned in the 'categories' array of the response. |
{
"type": "object",
"fields": {
"page": "Current page number",
"sort": "Sort order applied",
"query": "The search query used",
"has_more": "Whether more pages of results are available",
"listings": "Array of listing objects with id, title, prices, condition, brand, shipping, etc.",
"page_size": "Number of results per page (60)",
"categories": "Array of category facets with id, name, slug, and count for the current search",
"total_results": "Total number of matching listings"
},
"sample": {
"data": {
"page": 1,
"sort": "best",
"query": "laptop",
"has_more": true,
"listings": [
{
"id": "1199769942",
"url": "https://www.ricardo.ch/de/a/1199769942/",
"brand": null,
"title": "1GB 1Rx16 PC3-10600S-9-10-C1",
"end_date": "2026-08-23T17:08:00Z",
"shipping": [
{
"key": "parcel_b_10kg",
"city": "Zürich",
"cost": 15,
"zipCode": "8050"
}
],
"bid_price": 0.05,
"condition": "acceptable",
"image_url": "https://img.ricardostatic.ch/images/d34a6e07-51b9-4b48-8d9c-b712b9032185/t_265x200/1gb-1rx16-pc3-10600s-9-10-c1",
"seller_id": "406826855",
"bids_count": 0,
"category_id": 39232,
"has_auction": true,
"has_buy_now": true,
"buy_now_price": 4,
"is_money_guard": false
}
],
"page_size": 60,
"categories": [
{
"id": 39091,
"name": "Computer & Netzwerk",
"slug": "computer-netzwerk-39091",
"count": 9055
}
],
"total_results": 13106
},
"status": "success"
}
}About the Ricardo API
Searching Listings
The search_listings endpoint accepts a required query parameter and returns paginated results containing up to 60 listing objects per page. Each listing includes an id, title, pricing data, condition, brand, and shipping details. Pagination is controlled via the page parameter (1-indexed), and the has_more field in the response indicates whether additional pages exist. The total_results field gives the full count of matching listings for a given query.
Filtering and Sorting
Results can be narrowed using the category_slug parameter, which accepts slugs in the format {name}-{id} (for example, notebooks-39272 or sports-41875). These slugs are returned directly in the categories array of any search response, each entry carrying an id, name, slug, and count. This means you can run a broad keyword search first and then use the returned category slugs for follow-up filtered queries. The sort parameter controls ordering and supports options including price, relevance, recency, and auction activity.
Response Structure
Every response echoes back the query, sort, page, and page_size (fixed at 60) used for that request, making it straightforward to reconstruct or log request context alongside results. The listings array is the primary payload, and the categories facet array doubles as a discovery mechanism — useful when you don't know the exact category slug ahead of time and want to see how Ricardo.ch has bucketed the results for a given search term.
The Ricardo API is a managed, monitored endpoint for ricardo.ch — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ricardo.ch changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official ricardo.ch API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track price trends for specific product keywords across Ricardo.ch listings over time
- Compare new vs. used condition pricing for consumer electronics using the
conditionandpricesfields - Build a category browser by extracting
categoriesfacets from broad keyword searches - Monitor brand-specific inventory by combining
querywithbrandfiltering via category slugs - Identify arbitrage opportunities by sorting results by price and comparing against other Swiss marketplaces
- Aggregate shipping cost data across listings for a given product category
- Audit auction activity by sorting listings by auction criteria and capturing bid-related pricing fields
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Ricardo.ch have an official developer API?+
How do category slugs work in the search_listings endpoint?+
{name}-{id}, such as notebooks-39272. You don't need to know them in advance — every search response returns a categories array with id, name, slug, and count fields for the matched results. You can use those slugs directly in subsequent requests as the category_slug parameter to narrow results.Is individual listing detail data (full description, seller profile, bid history) available?+
What is the maximum number of results I can retrieve for a query?+
page_size of 60 results. The total_results field in the response tells you the full match count, and has_more indicates whether additional pages exist. You can paginate through results using the page parameter, but retrieval is limited to what Ricardo.ch surfaces for a given search.