Subito API & Scraper
The Subito API returns Italy's largest classifieds site as clean JSON in seven actions: search for the marketplace in any category, cars/search for cars, motorcycles and vans, real_estate/search for property for sale, for rent and holiday rentals, listing for the full record of any ad, and categories, locations and suggest for the ids and terms the searches take.
🤖 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.
Every row carries the price, whether the item is free, whether the price is unpublished or a placeholder, region, province, town and zone, a private, business or pro seller with the shop name, condition, whether shipping is available and the TuttoSubito shipping cost, urgent and 'In vetrina' flags, the publication or renewal date and the expiry date, images, the description and every attribute Subito publishes. Vehicle rows add make, model, version, registration year and month, mileage, fuel, gearbox, body type, power in kW and hp, emission class and used, Km0 or new; property rows add surface, rooms, bathrooms, floor, building condition, energy class, heating, furnished, elevator, balcony and garden. listing can also add the seller's rating, reply time, badges and years on Subito, the pro shop and TuttoSubito delivery prices and times. Every filter was checked live to narrow the result and every returned row to match it. Rows that do not contain any of your search words are removed and counted, because Subito matches short words loosely. On 14 ads in 7 categories, the title, town, seller type and photo count matched each ad's own page. No Subito account, no browser - one ReefAPI key and the standard { ok, data, meta, error } envelope.
Five Subito results that are not what they look like
A Subito ad can show 0 € without being free, sit at the top of a cheapest-first list only because it has no price, carry a date that is only its latest renewal, or match your keyword only loosely. Each looks like an ordinary row. This engine labels or removes every one.
| Search or ad | What Subito shows | What the API returns | the catch |
|---|---|---|---|
| Pro bike ads, price on request | 0 € | price: null, price_not_published: true | 0 € is how a seller leaves the price out; free items are a separate ad type and come back as price 0 with is_free: true |
| 'bici' cheapest first | ads without a price first | unpriced_excluded: true | Without it, the first page of a cheapest-first bike search was ads with no price; the API leaves them out of price sorts unless you set price_min |
| 'lego', newest first | 303,503 results, 28 of the first 30 cars and alloy wheels ('cerchi in lega') | 56,518 LEGO ads, 30 of 30 on pages 1 to 3 | The keyword is matched as words, singular and plural alike; include_fuzzy_matches returns Subito's own looser results, flagged |
| 'bici' most expensive first | 1,234,567 € | price_looks_placeholder: true | Round-number fillers top the expensive end; the flag keeps them out of averages without hiding them |
| Any ad | today's date | published_or_renewed_at | Subito's date is the latest publication or renewal - ads first posted in earlier years carry today's date |
Measured on 2026-09-16. Classified ads come and go - the searches above are dated.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/subito/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "bici"
}
}{
"ok": true,
"meta": {
"api": "subito",
"endpoint": "search",
"mode": "live",
"latency_ms": 2253.7,
"record_count": 30,
"bytes": 118668,
"cache_hit": false,
"stop_reason": "limit_reached"
},
"data": {
"listings": [
{
"ad_id": "641765354",
"urn": "id:ad:d3619a14-6d31-41a0-95ab-75975a30e325:list:641765354",
"title": "telaio carbonio specialized xs full",
"url": "https://www.subito.it/biciclette/telaio-carbonio-specialized-xs-full-sassari-641765354.htm",
"category_id": "41",
"category": "Biciclette",
"macro_category_id": "18",
"ad_type": "sale",
"ad_type_label": "In vendita",
"price": 1300,
"currency": "EUR",
"is_free": false,
"price_not_published": false,
"price_looks_placeholder": false,
"published_or_renewed_at": "2026-09-16T15:40:13+02:00",
"expires_at": "2027-04-02T08:44:45+02:00",
"location": {
"region_id": "19",
"region": "Sardegna",
"province_id": "8",
"province": "Sassari",
"province_code": "SS",
"town_id": "112053",
"town": "Sennori",
"zone_id": null,
"zone": null,
"latitude": 40.788062,
"longitude": 8.595407,
"coordinates_precision": "town",
"address": null,
"address_latitude": null,
"address_longitude": null,
"address_withheld": false
},
"seller": {
"type": "private",
"seller_id": "8689485",
"name": null,
"name_withheld": false,
"is_company": false,
"shop_id": null,
"shop_name": null,
"vat_number": null
},
"condition": "like_new",
"condition_label": "Come nuovo - perfetto o ricondizionato",
"shipping": {
"shippable": true,
"tuttosubito": true,
"method": "Spedizione con TuttoSubito",
"cost": 7.99,
"currency": "EUR",
"package_size": "Grande - fino a 15kg",
"carriers": []
},
"is_urgent": false,
"in_vetrina": true,
"is_sold": false,
"image_count": 6,
"images": [
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/4e/4e913035-5711-4042-b183-4e8ee83beb94?rule=fullscreen-1x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/a5/a50b8df9-6033-4195-9c87-91f4ff59b5b5?rule=fullscreen-1x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/f9/f97d2bc1-ef17-4bd2-a527-ce2fa6965bd3?rule=fullscreen-1x-auto"
],
"has_360_images": false,
"description": "vendo TELAIO carbonio fact 11 specialized epic expert 2023, come nuovo per passaggio ad altro modello.\nvolendo posso offrire BICI COMPLETA con ruote e forcella ( FOX FLOAT X Performance with Specialized GENIE Shock Tech, Ride Dynamics Trail Tune, 2-position lever w/3 setting Open mode tuning range, LSR adjustment, S2-S6:210x55mm) in alluminio , guarnitura sram eagle X01, 12 v. Prezzo da concordare!",
"attributes": [
{
"key": "[trimmed-depth]",
"label": "[trimmed-depth]",
"value": "[trimmed-depth]",
"values": "[trimmed-depth]",
"value_id": "[trimmed-depth]"
},
{
"key": "[trimmed-depth]",
"label": "[trimmed-depth]",
"value": "[trimmed-depth]",
"values": "[trimmed-depth]",
"value_id": "[trimmed-depth]"
},
{
"key": "[trimmed-depth]",
"label": "[trimmed-depth]",
"value": "[trimmed-depth]",
"values": "[trimmed-depth]",
"value_id": "[trimmed-depth]"
}
],
"is_possible_repost": false,
"repost_of": null,
"matches_query_words": true
},
{
"ad_id": "660656417",
"urn": "id:ad:7f7bc203-2118-42e8-a2f7-9607c5fcefd4:list:660656417",
"title": "Componenti vari Corsa e MTB Shimano XTR Dura Roval",
"url": "https://www.subito.it/biciclette/componenti-vari-corsa-e-mtb-shimano-xtr-dura-roval-genova-660656417.htm",
"category_id": "41",
"category": "Biciclette",
"macro_category_id": "18",
"ad_type": "sale",
"ad_type_label": "In vendita",
"price": 48,
"currency": "EUR",
"is_free": false,
"price_not_published": false,
"price_looks_placeholder": false,
"published_or_renewed_at": "2026-09-16T15:40:12+02:00",
"expires_at": "2027-09-14T11:34:29+02:00",
"location": {
"region_id": "3",
"region": "Liguria",
"province_id": "1",
"province": "Genova",
"province_code": "GE",
"town_id": "010025",
"town": "Genova",
"zone_id": null,
"zone": null,
"latitude": 44.411493,
"longitude": 8.932688,
"coordinates_precision": "town",
"address": null,
"address_latitude": null,
"address_longitude": null,
"address_withheld": false
},
"seller": {
"type": "private",
"seller_id": "103183596",
"name": null,
"name_withheld": false,
"is_company": false,
"shop_id": null,
"shop_name": null,
"vat_number": null
},
"condition": "very_good",
"condition_label": "Ottimo - poco usato e ben conservato",
"shipping": {
"shippable": true,
"tuttosubito": true,
"method": "Spedizione con TuttoSubito",
"cost": 0.99,
"currency": "EUR",
"package_size": "Piccolo - fino a 2kg",
"carriers": [
"[trimmed-depth]",
"[trimmed-depth]",
"[trimmed-depth]"
]
},
"is_urgent": false,
"in_vetrina": true,
"is_sold": false,
"image_count": 6,
"images": [
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/24/24d6d6d6-b66e-4312-9dd4-9e430b8a8e74?rule=fullscreen-1x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/92/9273006c-47ef-4772-9b3f-d041f321ac8f?rule=fullscreen-1x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/8e/8e355020-c0e9-40a1-893c-9ab4e89210d6?rule=fullscreen-1x-auto"
],
"has_360_images": false,
"description": "Vendo componenti bici da corsa e MTB\nIl prezzo indicato nell' annuncio è indicativo, si prega di contattarmi per chiedere ulteriori info.\n\nSella prologo scratch 3DMSS (150 grammi e tecnologia 3D, condizioni pari al nuovo)\nGuarnitura Shimano Ultegra 172,5 (Buone condizioni)\nGuarnitura Shimano Dura ace 172,5 (Buone condizioni)\nCorone Shimano Ultegra 50/34 11V (2000 km percorsi)\nDisco shimano dura ace 160 mm (Meno di 300 km percorsi)\nReggisella Specialized Tarmac S works SL8, SL9, CRUX 5 con zero offset 380 mm\nCiclocomputer Polar m460 + supporto da manubrio originale (ottime condizioni)\nScarpe Sh",
"attributes": [
{
"key": "[trimmed-depth]",
"label": "[trimmed-depth]",
"value": "[trimmed-depth]",
"values": "[trimmed-depth]",
"value_id": "[trimmed-depth]"
},
{
"key": "[trimmed-depth]",
"label": "[trimmed-depth]",
"value": "[trimmed-depth]",
"values": "[trimmed-depth]",
"value_id": "[trimmed-depth]"
},
{
"key": "[trimmed-depth]",
"label": "[trimmed-depth]",
"value": "[trimmed-depth]",
"values": "[trimmed-depth]",
"value_id": "[trimmed-depth]"
}
],
"is_possible_repost": false,
"repost_of": null,
"matches_query_words": true
},
{
"ad_id": "660200993",
"urn": "id:ad:5618a478-64e2-4d08-9a10-6c0e546e2274:list:660200993",
"title": "Bici da corsa",
"url": "https://www.subito.it/biciclette/bici-da-corsa-pordenone-660200993.htm",
"category_id": "41",
"category": "Biciclette",
"macro_category_id": "18",
"ad_type": "sale",
"ad_type_label": "In vendita",
"price": 650,
"currency": "EUR",
"is_free": false,
"price_not_published": false,
"price_looks_placeholder": false,
"published_or_renewed_at": "2026-09-16T15:40:12+02:00",
"expires_at": "2027-09-10T12:05:53+02:00",
"location": {
"region_id": "7",
"region": "Friuli-Venezia Giulia",
"province_id": "2",
"province": "Pordenone",
"province_code": "PN",
"town_id": "093025",
"town": "Maniago",
"zone_id": null,
"zone": null,
"latitude": 46.170752,
"longitude": 12.707994,
"coordinates_precision": "town",
"address": null,
"address_latitude": null,
"address_longitude": null,
"address_withheld": false
},
"seller": {
"type": "private",
"seller_id": "118340712",
"name": null,
"name_withheld": false,
"is_company": false,
"shop_id": null,
"shop_name": null,
"vat_number": null
},
"condition": "good",
"condition_label": "Buono - usato ma ben conservato",
"shipping": {
"shippable": false,
"tuttosubito": false,
"method": null,
"cost": null,
"currency": null,
"package_size": null,
"carriers": []
},
"is_urgent": false,
"in_vetrina": true,
"is_sold": false,
"image_count": 3,
"images": [
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/f3/f37873a9-3309-46ae-a239-82dc6a980fe0?rule=fullscreen-1x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/d6/d6fb2642-7a4e-4708-894f-c43b9e6ae8b5?rule=fullscreen-1x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/e8/e86d8166-c716-4160-b6c7-03ffc38f3711?rule=fullscreen-1x-auto"
],
"has_360_images": false,
"description": "BOTTECCHIA EMMEDUE in carbonio costruita a mano in italia da maestri artigiani della cicli BOTTECCHIA taglia 51 con Super Record 11v, 52-36/12-27 e12-29, ruote Mavic sis-SLR + ruote riserva Mavic Aksium. Usata e mantenuta perfettamente con regolari manutenzioni, quindi pronta all'uso.",
"attributes": [
{
"key": "[trimmed-depth]",
"label": "[trimmed-depth]",
"value": "[trimmed-depth]",
"values": "[trimmed-depth]",
"value_id": "[trimmed-depth]"
},
{
"key": "[trimmed-depth]",
"label": "[trimmed-depth]",
"value": "[trimmed-depth]",
"values": "[trimmed-depth]",
"value_id": "[trimmed-depth]"
},
{
"key": "[trimmed-depth]",
"label": "[trimmed-depth]",
"value": "[trimmed-depth]",
"values": "[trimmed-depth]",
"value_id": "[trimmed-depth]"
}
],
"is_possible_repost": false,
"repost_of": null,
"matches_query_words": true
}
],
"count": 30,
"total": 271434,
"hidden_seller_rows_dropped": 0,
"possible_reposts": 0,
"fuzzy_matches_dropped": 0,
"page": 1,
"limit": 30,
"sort_applied": "newest",
"has_more": true,
"keyword_match": "words",
"filters_applied": {
"q": "bici",
"t": "In vendita"
},
"unpriced_excluded": false
}
}What the Subito API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search Subito.it, Italy's largest classifieds site, by keyword and/or category: price (free items, unpublished and placeholder prices labelled), region, province, town and zone, private, business or pro seller with shop, condition, shipping and TuttoSubito cost, urgent and 'In vetrina' flags, publication/renewal and expiry dates, images, description and every published attribute. Filter by category, ad type, condition, shipping, price, location, seller type or seller; sort by newest, relevance or price. | Price-intelligence teams call search to search Subito.it, Italy's largest classifieds site, by keyword and/or category. | query, titles_only, category, ad_type, condition, ... |
| cars/search | Search Subito Motori - cars, motorcycles and vans: price, make, model and version, year, registration, mileage, fuel, gearbox, body type, doors, seats, colour, power in kW and hp, engine size, emission class, used/Km0/new, dealer or private seller, town and province. Filter by vehicle type, make, model, year, mileage, fuel, gearbox, body type, condition, engine size, motorcycle type, price, seller type and location; sort by newest, relevance or price. | Classifieds aggregators call cars/search to search Subito Motori - cars, motorcycles and vans. | vehicle_type, query, make, model, year_min, ... |
| real_estate/search | Search Subito Immobili - property for sale, for rent and holiday rentals, rooms, garages, land and offices: price or rent, surface in m², rooms, bathrooms, floor, building condition, energy class, heating, furnished, elevator, balcony, garden, parking, agency or private owner, town and zone. Filter by transaction, property type, price, surface, rooms, bathrooms, building condition, furnished, elevator, balcony, garden, seller type and location; sort by newest, relevance or price. | Resale and arbitrage tools call real_estate/search to search Subito Immobili - property for sale, for rent and holiday rentals, rooms, garages, lan…. | transaction, property_type, query, surface_min, surface_max, ... |
| listing | The full Subito ad by id, URL or urn, in any category: title, price (free, unpublished and placeholder labelled), description, all images, condition, shipping and TuttoSubito cost, every published attribute with its Italian label, publication/renewal and expiry dates, location, vehicle or property details and the seller. include_page_details adds the favourites count, the seller's rating, reply time, badges and years on Subito, the pro shop profile and TuttoSubito delivery prices and times. | Lead-generation teams call listing to get the full Subito ad by id, URL or urn, in any category. | ad_id, include_page_details, include_pii, max_rotations |
| categories | Subito's category tree (macro categories and their categories, with ids and the ad types each accepts) - the ids the search actions take. | Price-intelligence teams call categories to get subito's category tree (macro categories and their categories, with ids and the ad types each…. | max_rotations |
| locations | Find Subito's location ids: search a town or province by name, or list Italy's regions, or the provinces of one region - the values region, province and town take. | Classifieds aggregators call locations to find Subito's location ids. | query, region, max_rotations |
| suggest | Subito's own search suggestions for what a user is typing, each with the category Subito predicts and its probability. | Resale and arbitrage tools call suggest to get subito's own search suggestions for what a user is typing, each with the category Subito pred…. | query, max_rotations |
Call search from your stack
curl -X POST https://api.reefapi.com/subito/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"bici"}'import requests
r = requests.post(
"https://api.reefapi.com/subito/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "bici"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/subito/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "bici"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.subito.search with {"query":"bici"}.Who uses this API and why
- Used-car dealers and valuation tools track Italian asking prices by make, model, year, mileage and fuel with cars/search, with Km0 and new cars kept apart from used ones.
- Property analysts follow rents and sale prices, surface and rooms by province and town with real_estate/search, separating private owners from agencies.
- Resale and pricing tools compare second-hand prices by condition and shipping, keeping free items, unpublished prices and loosely matched rows out of the averages.
- Market-mapping teams list every ad of a pro shop or business seller with seller_id, without collecting private sellers' names or addresses.
Questions developers ask before integrating
Which parts of Subito does the API cover?
The whole site in three search actions. search covers every marketplace category with Subito's own category ids - 177,275 ads for 'bici' on 2026-09-16. cars/search covers cars, motorcycles and vans - 78,713 FIAT cars and 16,144 Ducati motorcycles that day. real_estate/search covers apartments, houses, land, garages, offices, rooms and holiday homes for sale and rent - 3,164 apartments for rent in the province of Milan. listing returns the full ad from any category. categories lists Subito's 45 categories, locations finds region, province and town ids, and suggest returns Subito's own search suggestions. Subito is Italian only; prices are in EUR.
Is a private seller's name or address included?
No. A private seller's display name is left out, and so is the street address with exact coordinates that some ads (mostly property) carry; the town and its coordinates stay. Business and pro sellers are returned with their name, shop and VAT number where Subito shows one. Subito does not show phone numbers to visitors, so the API does not return them.
Why does a keyword search return fewer results than Subito's site?
Subito matches short words loosely: on the site the newest 30 results for 'lego' were mostly cars with 'lega' alloy wheels, out of 303,503. The API matches your keyword as words, singular and plural alike, so 'lego' returns 56,518 LEGO ads and pages 1 to 3 were full of them; 'giochi' also finds 'gioco' and 'sedia' finds 'sedie'. Spelling mistakes still return results (checked on 'iphnoe', 'divanno' and four more). Any row that still contains none of your words is removed and counted in fuzzy_matches_dropped. Set include_fuzzy_matches to get Subito's own matching with a matches_query_words flag on every row.
How do I tell a free item, an unpublished price and a placeholder apart?
By the flags on every row. A free item has price 0 and is_free true. An ad without a price, or showing 0 €, has price null and price_not_published true. A filler number such as 1,234,567 € keeps its value with price_looks_placeholder true.
Do the filters really narrow the results?
Each one was checked live on 2026-09-16: the filtered total had to be smaller than the unfiltered one, and every returned row had to match. For 'bici' (177,275 ads): new condition 16,634, shipping available 73,487, pro sellers 7,062, Lombardy 35,052, between 100 and 300 € 39,094. For FIAT cars (78,713): Panda 19,032, diesel 30,982, automatic 4,295, 2018 to 2020 10,474. For apartments for rent in Milan (3,164): furnished 2,449, 50 to 80 m² 1,543, three rooms or more 882.
What is the difference between private, business and pro sellers?
Subito has three kinds of advertiser, and the API keeps them apart. private is a person. pro is a verified shop with a shop page. business is an account registered as a company, often with a VAT number, but without a verified shop - Subito's own 'private' filter mixes these in with people; seller_type lets you ask for each separately (1,267 business ads for 'bici' on 2026-09-16).
Are 'In vetrina' and sponsored ads marked?
Ads that paid for 'In vetrina' appear in their normal place in the results with in_vetrina true; urgent ads carry is_urgent. Subito's separate gallery of promoted ads is not mixed in - ask for include_sponsored and it comes back apart under sponsored[].
What does Subito not publish?
Phone numbers, private sellers' real names, a sold status (removed ads return NOT_FOUND), view counts, stock and barcodes. Seller ratings are not part of the search results; listing with include_page_details adds them where the seller has reviews.
What is the Subito API?
Subito API is a ReefAPI endpoint group for italy's largest classifieds: marketplace, cars and real estate as json. It returns live JSON through POST requests under /subito/v1.
Is the Subito API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Subito calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Subito login or account?
No login to Subito 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 Subito 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 Subito API use?
Subito actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Subito from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call subito actions with the same key, credit pool and JSON envelope used by normal REST requests.