Ricardo API & Scraper
The Ricardo API turns ricardo.ch, Switzerland's number-one marketplace, into clean JSON in five actions.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
search returns auction and fixed-price articles by keyword or category with the article id, title, image, condition, the current asking price (the next bid) and the buy-now price in CHF, the bid count, the closing time, the shipping cost and pickup location, the seller id and promoted or highlight flags — filtered by offer type, condition, shipping or pickup, price range, location by postcode and radius, seller type and 'has bids', and sorted by relevance, ending soon, newest, price or bids. article/bids returns the live bid ladder and full bid history for one article: the current highest bid, start price, next minimum bid, bid increment, bid count, time left, and every bid with its amount, time and the site's masked bidder nickname. seller/articles lists a seller's live articles by nickname, categories returns the full category tree, and suggest returns Ricardo's own keyword suggestions. On ricardo a search row's price is the next bid, not the current one, and a fixed-price filter includes auctions that also have buy-now — this API keeps each figure in its own field and marks each so nothing is mistaken for another. No Ricardo account and no browser — one ReefAPI key and the standard { ok, data, meta, error } envelope. Verified on 2026-09-16: 61 live calls across the five actions, all successful; the article-price detail (description, photo gallery, seller rating) that ricardo renders only inside its article page is not offered.
On Ricardo the row price is the next bid, not the current bid
A Ricardo search row shows an asking price: for an auction it is the next minimum bid, and for an article nobody has bid on yet it is the start price — never the current highest bid. The current bid, the start price and the whole bid history come from article/bids. This API keeps them apart: a row carries next_bid_price with current_bid left null, and article/bids carries the real current_bid.
| Field | Where | What it is |
|---|---|---|
| next_bid_price | search row | The current asking price = the next minimum bid (start price if no one has bid) |
| current_bid | article/bids | The current highest bid — null on a search row, real here |
| start_price / next_minimum_bid / bid_increment | article/bids | The full ladder, all in CHF |
| buy_now_price | search row | The fixed buy-now price, separate from any bid |
Bid amounts from article/bids are converted to Swiss francs. Bidder nicknames are returned exactly as Ricardo masks them (for example yn******). Ended and sold articles are not searchable on Ricardo and have no record, so this API does not offer sold-price research.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/ricardo/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "velo"
}
}{
"ok": true,
"meta": {
"api": "ricardo",
"endpoint": "search",
"mode": "live",
"latency_ms": 1316,
"record_count": 59,
"bytes": 263261,
"cache_hit": false,
"pagination": {
"page": 1,
"has_more": true,
"page_size": 59,
"total": 65735
}
},
"data": {
"articles": [
{
"article_id": "1329006920",
"title": "MTB Rockrider ST540 Rahmengrösse S (=14-16\") ideal 155-165cm",
"url": "https://www.ricardo.ch/de/a/1329006920/",
"image": "https://img.ricardostatic.ch/images/3f783270-9df4-41da-85d6-ee3447805a53/t_1000x750/mtb-rockrider-st540-rahmengroesse-s-(-14-16')-ideal-155-165cm",
"thumbnail": "https://img.ricardostatic.ch/images/3f783270-9df4-41da-85d6-ee3447805a53/t_265x200/mtb-rockrider-st540-rahmengroesse-s-(-14-16')-ideal-155-165cm",
"category_id": 82249,
"condition": "used",
"currency": "CHF",
"offer_type": "auction",
"is_auction": true,
"is_buy_now": false,
"next_bid_price": 52,
"current_bid": null,
"bids_count": 25,
"has_bids": true,
"buy_now_price": null,
"can_make_offer": false,
"money_guard": false,
"start_date": "2026-09-07T12:10:00Z",
"end_date": "2026-09-17T11:51:00Z",
"created_date": "2026-09-07T12:10:00Z",
"seller_id": "390439078",
"brand": "Decathlon",
"size": "38cm",
"product_type": "bicycle",
"co2_savings": "370.0 kg",
"shipping": [
{
"method": "[trimmed-depth]",
"cost": "[trimmed-depth]",
"currency": "[trimmed-depth]",
"zip_code": "[trimmed-depth]",
"city": "[trimmed-depth]"
}
],
"pickup_location": {
"zip_code": "8712",
"city": "Stäfa"
},
"is_promoted": false,
"promo_tier": null,
"highlight": "popular"
},
{
"article_id": "1329751598",
"title": "Rocky Mountain Vertex Team",
"url": "https://www.ricardo.ch/de/a/1329751598/",
"image": "https://img.ricardostatic.ch/images/c57450a2-8df2-4ba6-bf53-adb2206b286d/t_1000x750/rocky-mountain-vertex-team",
"thumbnail": "https://img.ricardostatic.ch/images/c57450a2-8df2-4ba6-bf53-adb2206b286d/t_265x200/rocky-mountain-vertex-team",
"category_id": 82249,
"condition": "used",
"currency": "CHF",
"offer_type": "auction",
"is_auction": true,
"is_buy_now": false,
"next_bid_price": 300,
"current_bid": null,
"bids_count": 0,
"has_bids": false,
"buy_now_price": null,
"can_make_offer": false,
"money_guard": false,
"start_date": "2026-09-15T19:11:00Z",
"end_date": "2026-09-22T19:08:00Z",
"created_date": "2026-09-15T19:11:00Z",
"seller_id": "406271721",
"brand": "Rocky Mountain Bicycles",
"size": "46cm",
"product_type": "bicycle",
"co2_savings": "370.0 kg",
"shipping": [
{
"method": "[trimmed-depth]",
"cost": "[trimmed-depth]",
"currency": "[trimmed-depth]",
"zip_code": "[trimmed-depth]",
"city": "[trimmed-depth]"
}
],
"pickup_location": {
"zip_code": "5703",
"city": "Seon"
},
"is_promoted": false,
"promo_tier": null,
"highlight": null
},
{
"article_id": "1329223010",
"title": "Neuaufbau Rennvelo Alu gr. 62 cm",
"url": "https://www.ricardo.ch/de/a/1329223010/",
"image": "https://img.ricardostatic.ch/images/a2532c9a-aed1-4a5b-b5bb-f4965d1515a3/t_1000x750/neuaufbau-rennvelo-alu-gr-62-cm",
"thumbnail": "https://img.ricardostatic.ch/images/a2532c9a-aed1-4a5b-b5bb-f4965d1515a3/t_265x200/neuaufbau-rennvelo-alu-gr-62-cm",
"category_id": 82249,
"condition": "used",
"currency": "CHF",
"offer_type": "auction_with_buynow",
"is_auction": true,
"is_buy_now": true,
"next_bid_price": 76,
"current_bid": null,
"bids_count": 27,
"has_bids": true,
"buy_now_price": 300,
"can_make_offer": false,
"money_guard": false,
"start_date": "2026-09-09T21:26:00Z",
"end_date": "2026-09-16T18:22:00Z",
"created_date": "2026-09-09T21:26:00Z",
"seller_id": "408764073",
"brand": null,
"size": "62cm",
"product_type": "bicycle",
"co2_savings": "370.0 kg",
"shipping": [
{
"method": "[trimmed-depth]",
"cost": "[trimmed-depth]",
"currency": "[trimmed-depth]",
"zip_code": "[trimmed-depth]",
"city": "[trimmed-depth]"
},
{
"method": "[trimmed-depth]",
"cost": "[trimmed-depth]",
"currency": "[trimmed-depth]",
"zip_code": "[trimmed-depth]",
"city": "[trimmed-depth]"
}
],
"pickup_location": {
"zip_code": "8044",
"city": "Zürich"
},
"is_promoted": false,
"promo_tier": null,
"highlight": "popular"
}
],
"count": 59,
"total_results": 65735,
"sponsored_dropped": 1,
"spellcheck": null,
"page_size": 60,
"page": 1,
"sort": "relevance",
"language": "de",
"has_more": true
}
}What the Ricardo API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search ricardo.ch by keyword and/or category: article id, title, image, condition, the current asking price (next bid) and buy-now price in CHF, bid count, closing time, shipping cost and pickup location, seller id and promoted/highlight flags. Filter by offer type (auction / buy-now), condition, shipping or pickup, price range, location (zip + radius), seller type and 'has bids'; sort by relevance, ending soon, newest, price or bids. Promoted 'Top-Angebot' rows are dropped and counted; a misspelling returns its matches plus the site's spelling suggestion. | Pricing teams call search to search ricardo.ch by keyword and/or category. | query, category, offer_type, condition, shipping, ... |
| seller/articles | Every live article a ricardo seller currently has listed, by seller nickname - same rows as search, with the same filters and sorts. ricardo does not publish a browser-free seller rating/score. | Marketplace operators call seller/articles to get every live article a ricardo seller currently has listed, by seller nickname - same rows as s…. | seller, offer_type, condition, shipping, price_min, ... |
| article/bids | The live bid ladder and full bid history for one article: current highest bid, start price, next minimum bid, bid increment, bid count, the time left, and every bid (amount, masked bidder nick, time, winning/autobid) - all in CHF. This is ricardo's auction core; the rich static record (description, photo gallery, seller score) is not available browser-free (see the docs). | Catalog enrichment teams call article/bids to get the live bid ladder and full bid history for one article. | article_id, language, max_rotations |
| categories | ricardo's category tree in the chosen language: id, name, slug, parent id and top-level flag. Use a slug (or id) as search's category. Filter by parent_id, or top_level for the top categories only. | Retail analysts call categories to get ricardo's category tree in the chosen language. | parent_id, top_level, language, max_rotations |
| suggest | ricardo's own keyword suggestions for the start of a search term, each with the category it points to when ricardo attaches one. | Pricing teams call suggest to get ricardo's own keyword suggestions for the start of a search term, each with the category it p…. | query, language, max_rotations |
Call search from your stack
curl -X POST https://api.reefapi.com/ricardo/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"velo"}'import requests
r = requests.post(
"https://api.reefapi.com/ricardo/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "velo"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/ricardo/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "velo"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.ricardo.search with {"query":"velo"}.Who uses this API and why
- Swiss resellers and collectors track auctions ending soon in a category and read the full bid history of the ones that matter.
- Price watchers compare the buy-now price against the current bid and the shipping or pickup cost before bidding.
- Deal finders filter by condition, price range and postcode radius to surface local pickup bargains.
- Sellers and analysts pull a seller's whole live inventory by nickname to monitor a competitor.
Questions developers ask before integrating
Is the price on a search result the current bid?
No. A Ricardo search row shows the asking price — the next minimum bid for an auction, or the start price for an auction with no bids yet — in the next_bid_price field, and current_bid is left null. To get the current highest bid, the start price, the bid increment and the full bid history, call article/bids with the article id.
How do I get the bids on an auction?
article/bids returns the live ladder for one article: current_bid (the highest bid), start_price, next_minimum_bid, bid_increment, bids_count, the time left, and a bids list where each bid has its amount in CHF, the time, whether it is winning or an automatic bid, and the bidder's nickname masked the way Ricardo shows it.
What is the difference between auction, fixed_price and auction_with_buynow?
auction is a pure auction, auction_with_buynow has both a live bid and a buy-now price, and fixed_price is a buy-now article. Note that Ricardo's fixed_price filter means 'buy-now available', so it also returns auction_with_buynow rows; each row's offer_type tells you exactly which it is.
Can I search within a category, or in French and Italian?
Yes. Pass category as a Ricardo category slug (velos-82249), a category URL, or a numeric id, and combine it with a keyword to search inside that category. language can be de, fr or it — Ricardo is Swiss — and it drives the titles and the category slugs; prices are always in Swiss francs.
Are promoted 'Top-Angebot' articles included?
Promoted articles that sit at the top and ignore the sort order are dropped by default and counted in sponsored_dropped; count is the organic rows. Pass include_sponsored=true to get them back with is_promoted: true. A paid highlight that still respects the sort is kept and marked with promo_tier.
What does Ricardo NOT return through this API?
The article description, the full photo gallery, the seller's rating and the full specification list are rendered only inside Ricardo's article page and are not available without a browser, so this API does not offer a full product detail — it returns the rich search rows and the complete bid ladder instead. Sold or ended articles are not searchable and have no record, so there is no sold-price history, and there is no GTIN or barcode.
What is the Ricardo API?
Ricardo API is a ReefAPI endpoint group for switzerland's #1 marketplace: auction and buy-now articles, live bids, prices, shipping and pickup — in chf. It returns live JSON through POST requests under /ricardo/v1.
Is the Ricardo API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Ricardo calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Ricardo login or account?
No login to Ricardo is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Ricardo data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Ricardo API use?
Ricardo actions currently cost 1 credit per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Ricardo from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call ricardo actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the Ricardo API a Ricardo scraper?
It is the managed alternative to a DIY Ricardo scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same switzerland's #1 marketplace: auction and buy-now articles, live bids, prices, shipping and pickup — in chf back as clean JSON.
Why does my Ricardo scraper keep getting blocked?
Most Ricardo scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked or failed calls are free.