Switzerland's #1 marketplace as JSON, with the real bid on every article
The Ricardo API turns ricardo.ch, Switzerland's number-one marketplace, into clean JSON in five actions.
5 active endpoints. Every call is 1 credit.
- POST/ricardo/v1/search
- POST/ricardo/v1/seller/articles
- POST/ricardo/v1/article/bids
- POST/ricardo/v1/categories
- POST/ricardo/v1/suggest
What Ricardo endpoints does ReefAPI ship?
5 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Ricardo API
3 of 5 endpoints, ready to run
Auction and buy-now articles: 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 flags.
{ "ok": true, "meta": { "api": "ricardo", "endpoint": "search", "mode": "live", "latency_ms": 620.7, "record_count": 59, "cache_hit": false }, "data": { "articles": [ { "article_id": "1316178300", "title": "Mofa Klingel Velo Glocke Bremgarten", "url": "https://www.ricardo.ch/de/a/1316178300/", "image": "https://img.ricardostatic.ch/images/0f5dfdd5-64db-4a70-a213-ed37ceb10f0b/t_1000x750/mofa-klingel-velo-glocke-bremgarten", "thumbnail": "https://img.ricardostatic.ch/images/0f5dfdd5-64db-4a70-a213-ed37ceb10f0b/t_265x200/mofa-klingel-velo-glocke-bremgarten", "category_id": 82142, "condition": "used", "currency": "CHF", "offer_type": "auction", "is_auction": true, "is_buy_now": false, "next_bid_price": 33, "current_bid": null, "bids_count": 0, "has_bids": false, "buy_now_price": null, "can_make_offer": false, "money_guard": false, "start_date": "2026-09-09T13:42:00Z", "end_date": "2026-09-16T13:41:00Z", "created_date": "2026-04-08T11:34:00Z", "seller_id": "404803544", "brand": null, "size": null, "product_type": "auto_part", "co2_savings": null, "shipping": [ { "method": "pickup", "cost": 0, "currency": "CHF", "zip_code": "6206", "city": "Neuenkirch" } ], "pickup_location": { "zip_code": "6206", "city": "Neuenkirch" }, "is_promoted": false, "promo_tier": null, "highlight": null }, { "article_id": "1316177060", "title": "Mofa Glocke Velo Klingel E.Affentranger Brunnen", "url": "https://www.ricardo.ch/de/a/1316177060/", "image": "https://img.ricardostatic.ch/images/b7f9d10f-b217-4dc3-b4f5-da423c2de784/t_1000x750/mofa-glocke-velo-klingel-eaffentranger-brunnen", "thumbnail": "https://img.ricardostatic.ch/images/b7f9d10f-b217-4dc3-b4f5-da423c2de784/t_265x200/mofa-glocke-velo-klingel-eaffentranger-brunnen", "category_id": 82142, "condition": "used", "currency": "CHF", "offer_type": "auction", "is_auction": true, "is_buy_now": false, "next_bid_price": 33, "current_bid": null, "bids_count": 0, "has_bids": false, "buy_now_price": null, "can_make_offer": false, "money_guard": false, "start_date": "2026-09-09T13:42:00Z", "end_date": "2026-09-16T13:41:00Z", "created_date": "2026-04-08T11:14:00Z", "seller_id": "404803544", "brand": null, "size": null, "product_type": "auto_part", "co2_savings": null, "shipping": [ { "method": "pickup", "cost": 0, "currency": "CHF", "zip_code": "6206", "city": "Neuenkirch" } ], "pickup_location": { "zip_code": "6206", "city": "Neuenkirch" }, "is_promoted": false, "promo_tier": null, "highlight": null }, { "article_id": "1324277680", "title": "Damen Softshell Jacke Icepeak braun Grösse 38 guter Zustand", "url": "https://www.ricardo.ch/de/a/1324277680/", "image": "https://img.ricardostatic.ch/images/ef2b904e-af23-4fe0-904b-4b0a3f5b9e11/t_1000x750/damen-softshell-jacke-icepeak-braun-groesse-38-guter-zustand", "thumbnail": "https://img.ricardostatic.ch/images/ef2b904e-af23-4fe0-904b-4b0a3f5b9e11/t_265x200/damen-softshell-jacke-icepeak-braun-groesse-38-guter-zustand", "category_id": 40844, "condition": "used", "currency": "CHF", "offer_type": "auction", "is_auction": true, "is_buy_now": false, "next_bid_price": 15, "current_bid": null, "bids_count": 0, "has_bids": false, "buy_now_price": null, "can_make_offer": false, "money_guard": true, "start_date": "2026-09-09T13:42:00Z", "end_date": "2026-09-16T13:41:00Z", "created_date": "2026-07-12T19:56:00Z", "seller_id": "408829784", "brand": "Icepeak", "size": "38", "product_type": "jacket", "co2_savings": "13.0 kg", "shipping": [ { "method": "parcel_b_2kg", "cost": 9, "currency": "CHF", "zip_code": "8633", "city": "Wolfhausen" } ], "pickup_location": null, "is_promoted": false, "promo_tier": null, "highlight": null } ], "count": 59, "total_results": 65727, "sponsored_dropped": 1, "spellcheck": null, "page_size": 60, "page": 1, "sort": "ending_soon", "language": "de", "has_more": true } }
How the Ricardo API works
Ricardo is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 252 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Find an auction ending soon, then read what it really costs to win
A Ricardo search row shows the next bid, not the current one, and it does not carry the bid history. Get the shortlist from search, then ask article/bids for the true current bid and the whole ladder.
query 'velo', sort ending_soon — auctions closing soonest, with next_bid_price, buy_now_price and the closing time on every row.
article_id from a row — current_bid (the real highest bid), start_price, next_minimum_bid, bid_increment and every bid in CHF.
the row's seller, by nickname — the rest of that seller's live inventory to compare against.
A live auction with its true current bid, the next bid you would have to place, the buy-now alternative and the seller's other articles — all in Swiss francs, no account, no browser.
curl -X POST https://api.reefapi.com/ricardo/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"velo"}'{
"ok": true,
"data": { … },
"meta": {
"api": "ricardo",
"endpoint": "search",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
What the Ricardo API covers
Measured on 2026-09-16 over 61 live calls, all successful. Swiss francs; site languages de, fr and it.
search, article/bids, seller/articles, categories, suggest
offer type, condition, shipping/pickup, price range, postcode + radius, seller type, has-bids
relevance, ending soon, newest, price up/down, most bids, total price up/down
current bid, start price, next minimum bid, increment, bid count, time left, full bid history
de, fr, it / CHF
full product detail (description, gallery, seller rating) and sold-price history — Ricardo renders these only inside the article page
What people build with Ricardo
The jobs this data is most often used for.
endpoints
credit per call
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.
What Ricardo data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 252 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
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"])Have a question? We got answers.
The questions people actually ask before wiring up Ricardo.
Get a free key →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.
91 E-commerce & Marketplaces APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Ricardo, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 251 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-09-16.