# Subito.it Search API Documentation

<p><strong>Subito.it Search API Documentation</strong> 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.</p>

- **Documentation:** [https://scrappa.co/docs/subito-api/subito_search](https://scrappa.co/docs/subito-api/subito_search)
- **API group:** Subito.it API
- **Endpoint:** `GET https://scrappa.co/api/subito/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | No | Free text search, e.g. bicicletta. Required when c is not set. |
| `c` | integer | No | 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. |
| `t` | string | No | s = In vendita, k = Cercasi, u = In affitto, g, h. |
| `r` | integer | No | Region key 1 to 20 from the regions endpoint, e.g. 4 = Lombardia. |
| `ci` | integer | No | Province key from the places endpoint, e.g. 8 = Milano. Needs r. |
| `to` | string | No | 6-digit ISTAT town key from the places endpoint, e.g. 015146 = Milano. |
| `ps` | integer | No | Minimum price in EUR. |
| `pe` | integer | No | Maximum price in EUR. |
| `rs` | integer | No | Minimum number of rooms (real estate). |
| `re` | integer | No | Maximum number of rooms (real estate). |
| `szs` | integer | No | Minimum surface in square metres (real estate). |
| `sze` | integer | No | Maximum surface in square metres (real estate). |
| `advt` | integer | No | 0 = private seller, 1 = agency or dealer. |
| `sort` | string | No | datedesc, priceasc or pricedesc. Defaults to datedesc. |
| `lim` | integer | No | Ads per page, 1 to 100. Defaults to 30. |
| `start` | integer | No | Zero-based offset from 0 to 10000. Use next_start from the previous response. |

## Example response

```json
{
    "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

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. This response is not billable and makes no upstream call. |
| 503 | Invalid Source Response | Subito answered with a shape that no longer matches the documented contract. This response is not billable. |
| 503 | Service Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)