Subito APIsubito.it ↗
Search and retrieve Italian classified listings from Subito.it. Filter by keyword, category, location, and price. Access listing details, real estate, dealer inventory, and seller contacts.
What is the Subito API?
The Subito.it API covers Italy's largest classifieds marketplace across 6 endpoints, returning structured listing data including titles, descriptions, images, geo-location, features, and advertiser details. The search_listings endpoint accepts keyword, category, region, city, and price range filters to return paginated ad results, while get_listing_details delivers the complete record for any single listing by its numeric ID or URN.
curl -X GET 'https://api.parse.bot/scraper/e626a4f7-5ad6-47bb-93ad-28426d5a7b09/search_listings?city=4&town=058091&limit=5&query=iPhone&offset=0®ion=4&category=2&price_max=5000&price_min=100&listing_type=s&advertiser_type=0' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace subito-it-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Subito.it SDK — search listings, drill into details, contact sellers."""
from parse_apis.subito_it_api import Subito, ListingType, RealEstateCategory, AdvertiserType, ListingNotFound
client = Subito()
# Browse all categories to discover IDs for filtering
for cat in client.categories.list(limit=5):
print(cat.key, cat.value, cat.friendly_name)
# Search for iPhones in the Telefonia category (business sellers only)
listing = client.listings.search(
query="iPhone", category="12", advertiser_type=AdvertiserType.BUSINESS, limit=1
).first()
if listing:
print(listing.subject, listing.urn)
print(listing.geo.city.value, listing.advertiser.user_id)
# Get full details for this listing by its ID
try:
detail = client.listings.get(ad_id=listing.urn)
print(detail.subject, detail.body[:100])
for feat in detail.features:
print(feat.label, feat.values[0].value)
except ListingNotFound as exc:
print(f"Listing gone: {exc}")
# Reveal the seller's phone number (instance method)
phone_info = listing.phone()
print(phone_info.phone_number)
# Browse all listings from this seller
for ad in listing.advertiser.listings(limit=3):
print(ad.subject, ad.category.value)
# Search real estate: apartments for sale in Lombardia
for prop in client.listings.search_real_estate(
category=RealEstateCategory.APARTMENTS,
listing_type=ListingType.SALE,
region="4",
limit=3,
):
print(prop.subject, prop.urls.default)
print("exercised: categories.list / listings.search / listings.get / listing.phone / advertiser.listings / listings.search_real_estate")
Search for listings on Subito.it with various filters including keyword, category, location, and price range. Returns paginated results sorted by recency. At least one filter (query, category, region, city) is recommended to narrow results; calling with no filters returns all listings site-wide.
| Param | Type | Description |
|---|---|---|
| city | string | City/Provincia ID (numeric). |
| town | string | Town/Comune ID (numeric ISTAT code). |
| limit | integer | Number of results to return per page. |
| query | string | Search keyword. |
| offset | integer | Pagination offset (start index). |
| region | string | Region ID (numeric). |
| category | string | Category ID (e.g. '6' for Real Estate, '2' for Cars, '12' for Telefonia). Use get_categories to discover all IDs. |
| price_max | string | Maximum price filter (numeric string). |
| price_min | string | Minimum price filter (numeric string). |
| listing_type | string | Listing type: 's' for sale (vendita), 'a' for rent (affitto). |
| advertiser_type | string | Advertiser type: '0' for private, '1' for business. |
{
"type": "object",
"fields": {
"ads": "array of listing objects with urn, subject, body, category, geo, advertiser, features, images, urls",
"start": "integer — next pagination offset",
"count_all": "integer — total number of matching results"
},
"sample": {
"data": {
"ads": [
{
"geo": {
"city": {
"value": "Foggia"
},
"region": {
"value": "Puglia"
}
},
"urn": "id:ad:fa3f5a36-3178-4685-a962-7bbc98d41f93:list:648890873",
"body": "Vendo iphone 15 pro max senza il minimo segno di usura",
"urls": {
"default": "https://www.subito.it/telefonia/iphone-15-pro-max-256-gb-foggia-648890873.htm"
},
"images": [
{
"cdn_base_url": "https://images.sbito.it/api/v1/sbt-ads-images-pro/images/eb/ebe51287-66ae-448c-a522-e6a6602bc126"
}
],
"subject": "Iphone 15 pro max 256 Gb",
"category": {
"key": "12",
"value": "Telefonia"
},
"features": [
{
"uri": "/price",
"label": "Prezzo",
"values": [
{
"key": "600",
"value": "600 €"
}
]
}
],
"advertiser": {
"company": false,
"user_id": "110378471"
}
}
],
"start": 5,
"count_all": 69070
},
"status": "success"
}
}About the Subito API
Searching and Browsing Listings
The search_listings endpoint is the primary entry point for querying Subito.it. It accepts a query keyword, a numeric category ID, region, city, and price_max to filter results. Responses include an ads array — each object containing urn, subject, body, category, geo, advertiser, features, images, and urls — plus count_all for the total match count and start for the next pagination offset. Use get_categories first to resolve the full category tree, which returns each category's key (ID), value (display name), friendly_name (URL slug), and optional macrocategory_id for hierarchy.
Real Estate and Dealer Inventory
get_real_estate_listings targets the Real Estate macro-category (ID 6) and adds price_min, price_max, and a listing_type filter (s for sale, a for rent) on top of the standard location filters. Sub-categories include Appartamenti (7), Ville (29), and Terreni (30). get_dealer_listings fetches all active ads from a single advertiser using their numeric user_id, which is exposed in the advertiser object of any search result or listing detail response. Both endpoints follow the same paginated ads / start / count_all shape.
Listing Details and Seller Contact
get_listing_details accepts either a numeric listing ID (extracted from the listing URL) or a full URN and returns the complete listing object: full body description, all image objects with base_url and cdn_base_url, the complete features array (price, condition, shipping, and more), and advertiser info including user_id, name, and a company flag. get_seller_phone takes a listing URN and returns the seller's phone_number when available. The endpoint returns stale_input when no phone number is on record — common for private sellers, less common for business or dealer accounts.
The Subito API is a managed, monitored endpoint for subito.it — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when subito.it changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official subito.it API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate Italian automotive classifieds by filtering
search_listingswith category ID 2 and a city or region to build a regional car price index - Monitor real estate asking prices in a specific Italian city by polling
get_real_estate_listingswithlisting_type=sand acityID - Build a dealer profile page by fetching all active ads from a specific advertiser via
get_dealer_listingsusing theiruser_id - Enrich a listing record with the seller's phone number using
get_seller_phoneafter retrieving a URN fromsearch_listings - Resolve human-readable category names and IDs before constructing search queries by calling
get_categoriesto inspect the full hierarchy - Track listing availability and price changes by periodically calling
get_listing_detailson a known ad ID and comparing thefeaturesarray
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Subito.it have an official developer API?+
What does `get_listing_details` return beyond what appears in search results?+
get_listing_details returns the full body text description, the complete features array (which can include condition, shipping options, and item-specific attributes), all image objects with both base_url and cdn_base_url, and the advertiser object with a company flag. Search results may return truncated body text and a subset of features.Is location filtering by town (comune) supported, and how does it differ from city filtering?+
search_listings and get_real_estate_listings both accept a town parameter using a numeric ISTAT code for comune-level filtering, which is more granular than the city parameter (provincia-level). The region parameter is the broadest geographic filter. You can combine region, city, or town, but providing at least one is recommended — omitting all location filters returns all national listings.Does the API expose saved searches, user watchlists, or listing history?+
Are all listings guaranteed to have a phone number via `get_seller_phone`?+
get_seller_phone returns a phone_number string only when the seller has added one. When no number is available — common for private sellers — the endpoint returns stale_input. Business and dealer listings are more likely to include a phone number. If contact data coverage is important, retrieving the advertiser.user_id first and cross-referencing with get_dealer_listings can indicate whether the poster is a dealer.