Collectors · Classifieds & vehicles
Subito.it Scraper API in Python
Classified ads from Subito.it — motori by km/year/fuel, immobili by mq/locali, everything by price, comune and seller. One POST from Python with the input, rows back as JSON with 39 fields, $0.001 per delivered ad. No proxies or parsers to maintain.

First call
Install, call, read the rows.
pip install requestsimport os, requests
r = requests.post(
"https://api.quanticdata.io/v1/scraper/collectors/subito_search/run",
headers={"Authorization": f"Bearer {os.environ['QD_API_KEY']}"},
json={
"query": "iphone 15",
"title_only": True,
"max_results": 30,
},
timeout=120,
)
r.raise_for_status()
run = r.json()["payload"]
print(run["count"], "rows,", run["cost"]["usd"], "USD")
for row in run["results"]:
print(row.get("ad_id"), row.get("title"), row.get("url"), row.get("price"))The key comes from an environment variable, never from the code. The run answers in the same request when it finishes in time; payload.results holds the rows and payload.cost what they cost.
Request parameters
What the collector takes.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
query | string | no | What to search, e.g. "iphone 15". Optional when a category is set — leaving it out browses that category by filters alone, which is how a motori or immobili search usually works. |
category | string: all, motori, auto, accessori-auto, moto-e-scooter, accessori-moto, nautica, caravan-e-camper, veicoli-commerciali, immobili, appartamenti, camere-posti-letto, ville-singole-e-a-schiera, terreni-e-rustici, garage-e-box, loft-mansarde, case-vacanza, uffici-locali-commerciali, lavoro, offerte-lavoro, servizi, cerco-lavoro, attrezzature, elettronica, informatica, videogiochi, audio-video, fotografia, telefonia, casa-e-persona, arredamento-casalinghi, elettrodomestici, giardino-fai-da-te, abbigliamento-accessori, bambini-giocattoli, sport-hobby, animali, accessori-per-animali, musica-film, libri-riviste, strumenti-musicali, sport, biciclette, hobby-collezionismo, vari, annunci-vari | no (default all) | Subito category to search in. "all" searches every category (and disables Subito's own price/seller filtering — this collector re-applies it). |
region | string: italia, abruzzo, basilicata, calabria, campania, emilia-romagna, friuli-venezia-giulia, lazio, liguria, lombardia, marche, molise, piemonte, puglia, sardegna, sicilia, toscana, trentino-alto-adige, umbria, valle-d-aosta, veneto | no (default italia) | Italian region to search in. "italia" searches the whole country. |
city | string | no | Optional province inside the region, as it appears in a Subito URL ("roma", "milano", "reggio-emilia"). Needs `region`. |
town | string | no | Optional comune inside the province, as it appears in a Subito URL ("ladispoli", "sesto-san-giovanni"). Needs `city`. This is the level real-estate searches usually want. |
ad_type | string: sale, free, wanted | no (default sale) | Which kind of ad: for sale, given away for free, or wanted. |
sort | string: recent, relevance, price_asc, price_desc | no (default recent) | Result order. |
title_only | boolean | no (default false) | Match the query against ad titles only. Subito's default also matches the description, which pulls in loosely related ads. |
shippable_only | boolean | no (default false) | Only ads the seller will ship. |
min_price | integer | no | Lowest price in euro. Ads with no stated price are excluded when set. |
max_price | integer | no | Highest price in euro. Ads with no stated price are excluded when set. |
seller_type | string: any, private, company | no (default any) | Private sellers, verified dealers, or both. |
min_km | integer | no | Motori. Lowest mileage in kilometres. Applied to the ads even in the categories where Subito offers no mileage filter (veicoli commerciali, caravan). |
max_km | integer | no | Motori. Highest mileage in kilometres. |
min_year | integer | no | Motori. Earliest registration year. |
max_year | integer | no | Motori. Latest registration year. |
fuel | string: petrol, diesel, lpg, electric, cng, hybrid, mild_hybrid_petrol, mild_hybrid_diesel, full_hybrid_petrol, full_hybrid_diesel, plugin_hybrid_petrol, plugin_hybrid_diesel | no | Motori. Subito splits hybrids by kind, so "hybrid" is its own value and does not cover the mild/full/plug-in ones. |
gearbox | string: manual, automatic, sequential | no | Motori. Transmission type. |
vehicle_condition | string: used, km0, new | no | Motori. Used, zero-km or new. |
min_size | integer | no | Immobili. Smallest floor area in square metres. |
max_size | integer | no | Immobili. Largest floor area in square metres. |
min_rooms | integer | no | Immobili. Fewest locali. |
max_rooms | integer | no | Immobili. Most locali (Subito caps its own filter at "more than 10"). |
max_results | integer | no (default 30) | How many ads to deliver at most (1–150). You pay only for delivered ads. |
Response fields
39 fields per ad.
| Field | Type | What it holds |
|---|---|---|
rank | integer | 1-based position in the delivered results. |
page | integer | Result page the ad came from. |
ad_id | string | Subito listing id (the number ending the ad URL). |
title | string | Ad title. |
url | string, nullable | Ad URL. |
price | string, nullable | Price as shown ("450 €"). Null for free and wanted ads. |
price_value | number, nullable | Parsed price in euro. |
category | string, nullable | Category the ad is filed under ("Telefonia"). |
category_slug | string, nullable | Category slug ("telefonia"). |
condition | string, nullable | Item condition as stated ("Come nuovo - perfetto o ricondizionato"). |
km | integer, nullable | Motori. Exact mileage — Subito's card shows only the bucket ("70.000 - 74.999"). |
year | integer, nullable | Motori. Registration year. |
fuel | string, nullable | Motori. Fuel as a stable key ("diesel", "plugin_hybrid_petrol"), matching the input enum; the Italian label is in features. |
gearbox | string, nullable | Motori. "manual", "automatic" or "sequential". |
vehicle_condition | string, nullable | Motori. "used", "km0" or "new". |
size_sqm | integer, nullable | Immobili. Floor area in square metres. |
rooms | integer, nullable | Immobili. Number of locali. |
date | string, nullable | Publication time as ISO 8601 with the Europe/Rome offset in force ("2026-09-03T00:56:18+02:00"; +01:00 in winter). |
region | string, nullable | Region ("Emilia-Romagna"). |
city | string, nullable | Province ("Parma"). |
town | string, nullable | Comune ("Parma"). |
seller_type | string | "private" or "company". |
seller_name | string, nullable | Shop or advertiser name, when stated. |
seller_id | string, nullable | Subito user id of the seller. |
shippable | boolean | Seller offers shipping. |
shipping_cost | number, nullable | Shipping cost in euro, when stated. |
promoted | boolean | Paid visibility (gallery placement). |
urgent | boolean | Marked urgent by the seller. |
description | string, nullable | Full ad text (first 600 characters) — not the truncated card excerpt. |
thumbnail | string, nullable | First photo. |
images | string[] | Every photo, in the ad's order. |
features | object | Every other attribute the ad states, as label → value ("Km": "142.000", "Superficie": "85 mq"). Keys depend on the category. |
ad_type | string, nullable | Ad type as Subito words it ("In vendita", "In regalo", "Cercasi"). |
ad_uuid | string, nullable | Stable UUID of the ad. |
province_code | string, nullable | Two-letter province code (RM, MI, NA…). |
town_istat | string, nullable | ISTAT code of the comune. |
shop_id | string, nullable | Subito shop id when the seller has a shop page. |
image_count | integer | Number of photos on the ad. |
phone_available | boolean | True when the seller shows a phone number on the ad. |
Add ?format=csv to the runs endpoint to get the same rows as CSV.
Long runs
Run in the background, then poll.
A run that needs more time can go to the background: send "async": true, get 202 with the run id, and poll the runs endpoint until the status is done. Reading a run is free.
import os, time, requests
H = {"Authorization": f"Bearer {os.environ['QD_API_KEY']}"}
r = requests.post("https://api.quanticdata.io/v1/scraper/collectors/subito_search/run", headers=H,
json={**{"query":"iphone 15","title_only":True,"max_results":30}, "async": True}, timeout=30)
run_id = r.json()["payload"]["run_id"]
while True:
run = requests.get(f"https://api.quanticdata.io/v1/scraper/collectors/runs/{run_id}", headers=H, timeout=30).json()["payload"]
if run["status"] in ("done", "failed"):
break
time.sleep(5)
print(run["status"], run["count"])Errors
What can come back, and what is billed.
| Status | Meaning | Billed |
|---|---|---|
400 | The input does not match the collector (payload.errors) | No |
401 | Missing or wrong API key | No |
402 | Balance and free credit do not cover the run: top up | No |
422 | The input can never resolve; retrying the same input cannot help | No |
424 | The run failed at the source (blocked, timed out, layout changed); safe to retry | No |
429 | Rate limit or a per-account brake; wait for Retry-After | No |
Only delivered rows are billed: a run that delivers nothing costs nothing.
Price
$0.001 per delivered ad.
| Rows | Cost |
|---|---|
| 1 | $0.001 |
| 1,000 | $1.00 |
| 10,000 | $10.00 |
Up to 150 ads per run; split larger jobs into several runs. The $2 free credit every month covers about 2,000 ads. No subscription; paid tiers lower the unit price. All collector prices: collector pricing.
Before you run it
Questions developers ask
Is there a free Subito.it ads API?
Every account gets $2 of free usage each month, about 2,000 ads of this collector at $0.001 each, with no card.
Do I have to handle proxies, retries or blocks?
No. The collector runs on our network and handles them; a run blocked at the source returns 424 and is not billed.
How many rows can one run return?
Up to 150 ads per run (the max_results input, where the collector has one).
Can an AI agent run it?
Yes: the MCP server exposes it as the run_collector tool, with the same input and price. See the MCP server.
Run it on the free credit.
Create an API key, export it as QD_API_KEY and run the example. $0.001 per delivered ad, no subscription.