Subito.it Search API Documentation Search current Subito.it classifieds across all categories except Auto (category 2, served by the Subito Motori API). Filter by free text, category, ad type, region, province, town, price, rooms and surface. Sort by date or price. Each ad carries urn, subject, body, url, category, price in EUR, features (rooms, size, floor, energy class and more), location with coordinates, images, publish and expiry dates (ISO 8601 UTC) and public advertiser info. Offset pagination: use next_start while has_more is true. Subito serves results up to offset 10000. A valid search without results is a successful, billable response.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
16 optional filters available.
string
Optional
Free text search, e.g. bicicletta. Required when c is not set.
coffee shops
integer
Optional
Category key from the categories endpoint, e.g. 7 = Appartamenti, 3 = Moto e Scooter. Category 2 (Auto) is not supported here. Required when q is not set.
10
string
Optional
s = In vendita, k = Cercasi, u = In affitto, g, h.
example
integer
Optional
Region key 1 to 20 from the regions endpoint, e.g. 4 = Lombardia.
10
integer
Optional
Province key from the places endpoint, e.g. 8 = Milano. Needs r.
10
string
Optional
6-digit ISTAT town key from the places endpoint, e.g. 015146 = Milano.
example
integer
Optional
Minimum price in EUR.
10
integer
Optional
Maximum price in EUR.
10
integer
Optional
Minimum number of rooms (real estate).
10
integer
Optional
Maximum number of rooms (real estate).
10
integer
Optional
Minimum surface in square metres (real estate).
10
integer
Optional
Maximum surface in square metres (real estate).
10
integer
Optional
0 = private seller, 1 = agency or dealer.
10
string
Optional
datedesc, priceasc or pricedesc. Defaults to datedesc.
relevance
integer
Optional
Ads per page, 1 to 100. Defaults to 30.
10
integer
Optional
Zero-based offset from 0 to 10000. Use next_start from the previous response.
0
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"ads": [
{
"id": "612919294",
"url": "https://www.subito.it/appartamenti/appartamento-milano-g-b-stoppanivrg-milano-664696487.htm",
"urn": "id:ad:612919294:list:664696487",
"body": "In elegante stabile d'epoca, dotato di servizio di portineria, la nostra Agenzia propone in vendita un ampio bilocale caratterizzato da generose metrature e da una piacevole vivibilit\u00e0 degli spazi.\n\nL'immobile composto da ingresso, luminoso soggiorno living con cucina a vista, camera matrimoniale, doppi servizi entrambi finestrati e pratico ripostiglio in quota.\n\nPunto di forza della propriet\u00e0 \u00e8 l'ampio terrazzo di circa 30 mq. Data la sua esposizione interna rende l'ambiente unico e silenzioso,",
"type": {
"key": "s",
"value": "In vendita"
},
"dates": {
"expires_at": "2027-10-15T19:08:06Z",
"published_at": "2026-10-15T19:08:06Z"
},
"price": {
"amount": 565000,
"currency": "EUR"
},
"images": [
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/85/85e5c2ef-9274-4b64-a07b-0a14be284a44?rule=gallery-desktop-2x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/19/192f6bec-73a7-4dbc-bc7f-d8f90e9d18f8?rule=gallery-desktop-2x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/9e/9eee0298-7a22-45e0-a4c6-e3df4ec2d72a?rule=gallery-desktop-2x-auto"
],
"subject": "Appartamento Milano [G.B. - STOPPANIVRG]",
"category": {
"key": 7,
"value": "Appartamenti",
"friendly_name": "appartamenti",
"macrocategory_id": 6
},
"features": {
"room": {
"label": "Locali",
"value": "2"
},
"size": {
"label": "Superficie",
"value": 81,
"display": "81 mq"
},
"floor": {
"label": "Piano",
"value": "1"
},
"heating": {
"label": "Riscaldamento",
"value": "Centralizzato"
},
"bathrooms": {
"label": "Bagni",
"value": "2"
},
"nosalesman": {
"label": "Agenzie/Tmkg",
"value": true
},
"energy_class": {
"label": "Classe energetica",
"value": "F"
},
"air_conditioning": {
"label": "Aria condizionata",
"value": true
},
"building_condition": {
"label": "Stato",
"value": "Ottimo - ristrutturato"
}
},
"location": {
"lat": 45.466647,
"lon": 9.190648,
"town": "Milano",
"region": "Lombardia",
"province": "Milano",
"region_key": 4,
"town_istat": "015146",
"province_key": 8,
"province_code": "MI"
},
"advertiser": {
"name": "Milano Piazzale Abbiategrasso",
"type": 1,
"company": true,
"shop_id": 14475,
"shop_name": "Gabetti Milano Piazzale Abbiategrasso"
}
},
{
"id": "612919325",
"url": "https://www.subito.it/appartamenti/appartamento-seregno-cod-rif-3387170vrg-monza-664696517.htm",
"urn": "id:ad:612919325:list:664696517",
"body": "CULTURA IMMOBILIARE SRL propone in vendita IN ESCUSIVA in Seregno, Via IV Novembre N. 22 bellissimo appartamento di 2 locali oltre servizi e doppio balcone posto all'ultimo piano (secondo) per complessivi 64 mq circa, in palazzina residenziale munita di ascensore di recente costruzione edificata nell'anno 2006.\n\nIngresso su soggiorno con accesso diretto alla balconata, cucina abitabile munita di balcone di servizio, bagno finestrato con ampio piatto doccia e camera matrimoniale anch'essa con acc",
"type": {
"key": "s",
"value": "In vendita"
},
"dates": {
"expires_at": "2027-10-15T19:08:05Z",
"published_at": "2026-10-15T19:08:05Z"
},
"price": {
"amount": 149000,
"currency": "EUR"
},
"images": [
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/04/04549569-d2a9-4acf-8f50-191fd8e4ee58?rule=gallery-desktop-2x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/06/0651f21e-18d9-4237-a7f8-991f817dc071?rule=gallery-desktop-2x-auto",
"https://images.sbito.it/api/v1/sbt-ads-images-pro/images/fc/fc26b495-be80-4051-bf09-0827e773887a?rule=gallery-desktop-2x-auto"
],
"subject": "Appartamento Seregno [Cod. rif 3387170VRG]",
"category": {
"key": 7,
"value": "Appartamenti",
"friendly_name": "appartamenti",
"macrocategory_id": 6
},
"features": {
"room": {
"label": "Locali",
"value": "2"
},
"size": {
"label": "Superficie",
"value": 68,
"display": "68 mq"
},
"floor": {
"label": "Piano",
"value": "2"
},
"balcony": {
"label": "Balcone",
"value": true
},
"heating": {
"label": "Riscaldamento",
"value": "Autonomo"
},
"parking": {
"label": "Parcheggio",
"value": "Box privato"
},
"elevator": {
"label": "Ascensore",
"value": true
},
"bathrooms": {
"label": "Bagni",
"value": "1"
},
"last_floor": {
"label": "Ultimo piano",
"value": true
},
"nosalesman": {
"label": "Agenzie/Tmkg",
"value": true
},
"air_conditioning": {
"label": "Aria condizionata",
"value": true
},
"building_condition": {
"label": "Stato",
"value": "Buono - abitabile"
}
},
"location": {
"lat": 45.649449,
"lon": 9.206675,
"town": "Seregno",
"region": "Lombardia",
"province": "Monza e della Brianza",
"region_key": 4,
"town_istat": "108039",
"province_key": 9,
"province_code": "MB"
},
"advertiser": {
"name": "Paderno Dugnano",
"type": 1,
"company": true,
"shop_id": 40914,
"shop_name": "Gabetti Paderno Dugnano"
}
}
],
"lines": 2,
"start": 0,
"filters": {
"c": "Appartamenti",
"r": "Lombardia",
"t": "In vendita"
},
"has_more": true,
"count_all": 21578,
"next_start": 2
},
"meta": {
"billable": true,
"endpoint_family": "search"
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A parameter is missing or invalid. This response is not billable and makes no upstream call.
{
"errors": {
"q": [
"Provide a search query (q) or a category (c)."
]
},
"message": "The request validation failed"
}Invalid Source Response
Subito answered with a shape that no longer matches the documented contract. This response is not billable.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "search"
},
"error": {
"code": "PARSER_DRIFT",
"message": "Subito returned an unexpected response. Please retry later."
},
"success": false
}Service Unavailable
The upstream service is temporarily unavailable. Please retry shortly.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "search"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The Subito service is temporarily unavailable. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.