# Subito.it API scraper - Italy's largest classifieds site: marketplace search with condition, shipping and TuttoSubito, private/business/pro seller filters, cars and motorcycles, real estate for sale and rent, and the full ad record. No account, no browser; private sellers' personal data withheld.

> 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.
> ReefAPI engine `subito` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/subito/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /subito/v1/search — 2 credits
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.

**Parameters:**
- `query` (string, optional) — Free-text keyword, as typed into Subito's search box.
- `titles_only` (boolean, optional) — Match the keyword in ad titles only.
- `category` (string, optional) — Subito category id or name (41 = Biciclette, 12 = Telefonia, 14 = Arredamento e Casalinghi); the categories action lists them.
- `ad_type` (enum, optional, default "sale") — sale (default), wanted, gift, rent or holiday_rent. [one of: sale, wanted, gift, rent, holiday_rent]
- `condition` (array, optional) — One or more of new, like_new, very_good, good, damaged. [one of: new, like_new, very_good, good, damaged]
- `shippable` (boolean, optional) — Only ads with shipping available.
- `price_min` (number, optional) — Lowest price in EUR (monthly rent on rentals).
- `price_max` (number, optional) — Highest price in EUR (monthly rent on rentals).
- `region` (string, optional) — Italian region, by name or Subito id (4 = Lombardia). See the locations action.
- `province` (string, optional) — Province by its two-letter code (MI, RM, NA) or name.
- `town` (string, optional) — Town (comune) by its 6-digit id from the locations action, e.g. 015146 = Milano.
- `seller_type` (array, optional) — One or more of private, business, pro. [one of: private, business, pro]
- `seller_id` (string, optional) — seller.seller_id from a result row: that seller's ads.
- `urgent_only` (boolean, optional) — Only ads marked urgent.
- `sort` (enum, optional, default "newest") — newest (Subito's default: last published or renewed first), relevance, price_asc, price_desc. Price sorts leave out ads without a price unless price_min is given. [one of: newest, relevance, price_asc, price_desc]
- `page` (integer, optional, default 1) — Result page (Subito serves the first 10,000 results).
- `limit` (integer, optional, default 30) — Rows per page, up to 100.
- `include_sponsored` (boolean, optional, default false) — Also return Subito's paid gallery carousel ('In vetrina') for the same filters, apart, under sponsored[]. One extra request.
- `include_fuzzy_matches` (boolean, optional, default false) — By default the keyword is matched as words (singular and plural alike), so 'lego' does not also return cars with 'lega' alloy wheels, and any row that still contains none of your words is dropped and counted. true uses Subito's own looser matching and keeps every row, flagged matches_query_words.
- `include_pii` (boolean, optional, default false) — Return private sellers' display names and the street address/exact coordinates some ads carry.
- `max_rotations` (integer, optional, default 3) — Upstream attempts on fresh exits before giving up.

**Returns:** listings[]{ad_id, urn, title, url, category_id, category, macro_category_id, ad_type, ad_type_label, price, currency, is_free, price_not_published, price_looks_placeholder, published_or_renewed_at, expires_at, location{region_id, region, province_id, province, province_code, town_id, town, zone_id, zone, latitude, longitude, coordinates_precision, address, address_withheld}, seller{type, seller_id, name, name_withheld, is_company, shop_id, shop_name, vat_number}, condition, condition_label, shipping{shippable, tuttosubito, method, cost, currency, package_size, carriers[]}, is_urgent, in_vetrina, is_sold, image_count, images[], has_360_images, description, attributes[]{key, label, value, values[], value_id}, is_possible_repost, repost_of, matches_query_words, vehicle{} | property{}}, count, total, page, limit, has_more, sort_applied, filters_applied, unpriced_excluded, keyword_match, fuzzy_matches_dropped, hidden_seller_rows_dropped, possible_reposts, sponsored_total, sponsored[]

**Example request body:**
```json
{
  "query": "bici"
}
```

### POST /subito/v1/cars/search — 2 credits
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.

**Parameters:**
- `vehicle_type` (enum, optional, default "car") — car (default), motorcycle or van. [one of: car, motorcycle, van]
- `query` (string, optional) — Free-text keyword, as typed into Subito's search box.
- `make` (string, optional) — Make as Subito lists it, e.g. FIAT, ALFA ROMEO, Yamaha (cars and motorcycles).
- `model` (string, optional) — Model name as Subito lists it, with make (e.g. 147, Panda, MT-07).
- `year_min` (integer, optional) — Earliest registration year.
- `year_max` (integer, optional) — Latest registration year.
- `mileage_min` (number, optional) — Lowest mileage, km (snapped to Subito's 5,000-km steps).
- `mileage_max` (number, optional) — Highest mileage, km (snapped to Subito's 5,000-km steps).
- `fuel` (array, optional) — petrol, diesel, lpg, methane, electric, hybrid, mild/full/plug-in hybrid petrol or diesel, other. [one of: petrol, diesel, lpg, electric, other, hybrid, methane, mild_hybrid_petrol, mild_hybrid_diesel, full_hybrid_petrol, full_hybrid_diesel, plug_in_hybrid_petrol, plug_in_hybrid_diesel]
- `gearbox` (array, optional) — manual, automatic, sequential, other. [one of: manual, automatic, sequential, other]
- `body_type` (array, optional) — Cars: small_car, city_car, sedan, estate, mpv, suv, convertible, coupe, other. [one of: small_car, sedan, estate, mpv, suv, convertible, coupe, city_car, other]
- `vehicle_condition` (array, optional) — used, km0, new. [one of: used, km0, new]
- `cubic_capacity_min` (number, optional) — Motorcycles: smallest engine, cc (snapped to Subito's steps 50/125/150/250/600/750/…).
- `cubic_capacity_max` (number, optional) — Motorcycles: largest engine, cc (snapped to Subito's steps).
- `motorcycle_type` (array, optional) — Motorcycles: sport, cross_enduro, custom_cafe_racer, scooter, touring, quad, vintage, other. [one of: sport, cross_enduro, custom_cafe_racer, scooter, touring, quad, vintage, other]
- `price_min` (number, optional) — Lowest price in EUR (monthly rent on rentals).
- `price_max` (number, optional) — Highest price in EUR (monthly rent on rentals).
- `region` (string, optional) — Italian region, by name or Subito id (4 = Lombardia). See the locations action.
- `province` (string, optional) — Province by its two-letter code (MI, RM, NA) or name.
- `town` (string, optional) — Town (comune) by its 6-digit id from the locations action, e.g. 015146 = Milano.
- `seller_type` (array, optional) — One or more of private, business, pro. [one of: private, business, pro]
- `seller_id` (string, optional) — seller.seller_id from a result row: that seller's ads.
- `urgent_only` (boolean, optional) — Only ads marked urgent.
- `sort` (enum, optional, default "newest") — newest (Subito's default: last published or renewed first), relevance, price_asc, price_desc. Price sorts leave out ads without a price unless price_min is given. [one of: newest, relevance, price_asc, price_desc]
- `page` (integer, optional, default 1) — Result page (Subito serves the first 10,000 results).
- `limit` (integer, optional, default 30) — Rows per page, up to 100.
- `include_sponsored` (boolean, optional, default false) — Also return Subito's paid gallery carousel ('In vetrina') for the same filters, apart, under sponsored[]. One extra request.
- `include_fuzzy_matches` (boolean, optional, default false) — By default the keyword is matched as words (singular and plural alike), so 'lego' does not also return cars with 'lega' alloy wheels, and any row that still contains none of your words is dropped and counted. true uses Subito's own looser matching and keeps every row, flagged matches_query_words.
- `include_pii` (boolean, optional, default false) — Return private sellers' display names and the street address/exact coordinates some ads carry.
- `max_rotations` (integer, optional, default 3) — Upstream attempts on fresh exits before giving up.

**Returns:** listings[]{ad_id, urn, title, url, category_id, category, macro_category_id, ad_type, ad_type_label, price, currency, is_free, price_not_published, price_looks_placeholder, published_or_renewed_at, expires_at, location{region_id, region, province_id, province, province_code, town_id, town, zone_id, zone, latitude, longitude, coordinates_precision, address, address_withheld}, seller{type, seller_id, name, name_withheld, is_company, shop_id, shop_name, vat_number}, condition, condition_label, shipping{shippable, tuttosubito, method, cost, currency, package_size, carriers[]}, is_urgent, in_vetrina, is_sold, image_count, images[], has_360_images, description, attributes[]{key, label, value, values[], value_id}, is_possible_repost, repost_of, matches_query_words, vehicle{make, make_id, model, model_id, model_variant, version, year, registration, mileage_km, mileage_range, fuel, gearbox, body_type, doors, seats, colour, power_kw, power_hp, cubic_capacity_cc, emission_class, vehicle_condition, new_drivers_ok, vat_deductible, reference}}, count, total, page, limit, has_more, sort_applied, filters_applied, unpriced_excluded, keyword_match, fuzzy_matches_dropped, hidden_seller_rows_dropped, possible_reposts, sponsored_total, sponsored[]

**Example request body:**
```json
{
  "make": "ALFA ROMEO"
}
```

### POST /subito/v1/real_estate/search — 2 credits
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.

**Parameters:**
- `transaction` (enum, required) — sale, rent, holiday_rent or wanted. [one of: sale, rent, holiday_rent, wanted]
- `property_type` (enum, optional) — apartment, house, land, garage, loft_other, holiday_home, office_commercial or room. Omit for all real estate. [one of: apartment, house, land, garage, loft_other, holiday_home, office_commercial, room]
- `query` (string, optional) — Free-text keyword, as typed into Subito's search box.
- `surface_min` (number, optional) — Smallest surface, m².
- `surface_max` (number, optional) — Largest surface, m².
- `rooms_min` (integer, optional) — Fewest rooms (locali).
- `rooms_max` (integer, optional) — Most rooms (locali).
- `bathrooms_min` (integer, optional) — Fewest bathrooms.
- `bathrooms_max` (integer, optional) — Most bathrooms.
- `building_condition` (array, optional) — new_build, excellent, good, to_renovate. [one of: new_build, excellent, good, to_renovate]
- `furnished` (boolean, optional) — Rentals: furnished only.
- `elevator` (boolean, optional) — With an elevator.
- `balcony` (boolean, optional) — With a balcony.
- `garden` (boolean, optional) — With a garden (houses, holiday homes).
- `price_min` (number, optional) — Lowest price in EUR (monthly rent on rentals).
- `price_max` (number, optional) — Highest price in EUR (monthly rent on rentals).
- `region` (string, optional) — Italian region, by name or Subito id (4 = Lombardia). See the locations action.
- `province` (string, optional) — Province by its two-letter code (MI, RM, NA) or name.
- `town` (string, optional) — Town (comune) by its 6-digit id from the locations action, e.g. 015146 = Milano.
- `seller_type` (array, optional) — One or more of private, business, pro. [one of: private, business, pro]
- `seller_id` (string, optional) — seller.seller_id from a result row: that seller's ads.
- `urgent_only` (boolean, optional) — Only ads marked urgent.
- `sort` (enum, optional, default "newest") — newest (Subito's default: last published or renewed first), relevance, price_asc, price_desc. Price sorts leave out ads without a price unless price_min is given. [one of: newest, relevance, price_asc, price_desc]
- `page` (integer, optional, default 1) — Result page (Subito serves the first 10,000 results).
- `limit` (integer, optional, default 30) — Rows per page, up to 100.
- `include_sponsored` (boolean, optional, default false) — Also return Subito's paid gallery carousel ('In vetrina') for the same filters, apart, under sponsored[]. One extra request.
- `include_fuzzy_matches` (boolean, optional, default false) — By default the keyword is matched as words (singular and plural alike), so 'lego' does not also return cars with 'lega' alloy wheels, and any row that still contains none of your words is dropped and counted. true uses Subito's own looser matching and keeps every row, flagged matches_query_words.
- `include_pii` (boolean, optional, default false) — Return private sellers' display names and the street address/exact coordinates some ads carry.
- `max_rotations` (integer, optional, default 3) — Upstream attempts on fresh exits before giving up.

**Returns:** listings[]{ad_id, urn, title, url, category_id, category, macro_category_id, ad_type, ad_type_label, price, currency, is_free, price_not_published, price_looks_placeholder, published_or_renewed_at, expires_at, location{region_id, region, province_id, province, province_code, town_id, town, zone_id, zone, latitude, longitude, coordinates_precision, address, address_withheld}, seller{type, seller_id, name, name_withheld, is_company, shop_id, shop_name, vat_number}, condition, condition_label, shipping{shippable, tuttosubito, method, cost, currency, package_size, carriers[]}, is_urgent, in_vetrina, is_sold, image_count, images[], has_360_images, description, attributes[]{key, label, value, values[], value_id}, is_possible_repost, repost_of, matches_query_words, property{surface_m2, rooms, bathrooms, floor, building_condition, energy_class, heating, parking, furnished, elevator, balcony, garden, air_conditioning, available_now, short_term_rental, no_agencies, …}}, count, total, page, limit, has_more, sort_applied, filters_applied, unpriced_excluded, keyword_match, fuzzy_matches_dropped, hidden_seller_rows_dropped, possible_reposts, sponsored_total, sponsored[]

**Example request body:**
```json
{
  "transaction": "rent",
  "region": "4"
}
```

### POST /subito/v1/listing — 1 credit
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.

**Parameters:**
- `ad_id` (string, required) — The Subito ad id (the digits before .htm in an ad URL), the full URL or the urn.
- `include_page_details` (boolean, optional, default false) — Also read the ad page: favourites, seller rating/reply time/badges, shop profile and TuttoSubito delivery options. One extra, larger request.
- `include_pii` (boolean, optional, default false) — Return private sellers' display names and the street address/exact coordinates some ads carry.
- `max_rotations` (integer, optional, default 3) — Upstream attempts on fresh exits before giving up.

**Returns:** listing{ad_id, urn, title, url, category_id, category, macro_category_id, ad_type, ad_type_label, price, currency, is_free, price_not_published, price_looks_placeholder, published_or_renewed_at, expires_at, location{region_id, region, province_id, province, province_code, town_id, town, zone_id, zone, latitude, longitude, coordinates_precision, address, address_withheld}, seller{type, seller_id, name, name_withheld, is_company, shop_id, shop_name, vat_number}, condition, condition_label, shipping{shippable, tuttosubito, method, cost, currency, package_size, carriers[]}, is_urgent, in_vetrina, is_sold, image_count, images[], has_360_images, description, attributes[]{key, label, value, values[], value_id}, is_possible_repost, repost_of, matches_query_words, vehicle{} | property{}, page_details{favorites_count, availability, seller_profile{display_name, on_subito_since, published_ads_total, badges[], rating_score, rating_scale, rating_count, reply_time, last_active_at}, shop{shop_id, name, logo}, tuttosubito_shipping{to_door{cost, cost_before_discount}, to_door_days{min, max}, to_pickup_point{…}, couriers[]}}}

### POST /subito/v1/categories — 1 credit
Subito's category tree (macro categories and their categories, with ids and the ad types each accepts) - the ids the search actions take.

**Parameters:**
- `max_rotations` (integer, optional, default 3) — Upstream attempts on fresh exits before giving up.

**Returns:** categories[]{category_id, name, slug, macro_category_id, ad_types[]}, count

### POST /subito/v1/locations — 1 credit
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.

**Parameters:**
- `query` (string, optional) — Town or province name, at least 2 letters.
- `region` (string, optional) — A region name or id: list its provinces.
- `max_rotations` (integer, optional, default 3) — Upstream attempts on fresh exits before giving up.

**Returns:** locations[]{region_id, region, province_id, province, province_code, town_id, town, has_zones}, count

### POST /subito/v1/suggest — 1 credit
Subito's own search suggestions for what a user is typing, each with the category Subito predicts and its probability.

**Parameters:**
- `query` (string, required) — The text typed so far.
- `max_rotations` (integer, optional, default 3) — Upstream attempts on fresh exits before giving up.

**Returns:** suggestions[]{query, category_id, category, probability}, count

**Example request body:**
```json
{
  "query": "bici"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=subito
- Human docs page: https://reefapi.com/docs/subito
- Overview page: https://reefapi.com/subito-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt