Subito APIsubito.it ↗
Search and browse Subito.it listings by keyword, category, location, and price. Fetch listing details, real estate ads, dealer inventories, and seller phone numbers.
What is the Subito API?
The Subito.it API covers Italy's largest classifieds marketplace across 7 endpoints, giving programmatic access to listings, real estate ads, dealer inventories, and seller contact details. The search_listings endpoint accepts filters for keyword, category, region, city, and price range, returning paginated ad objects with titles, descriptions, images, location data, and advertiser info. A dedicated get_real_estate_listings endpoint adds sale/rent filtering and price-range bounds specific to property searches.
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'
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
Search and Browse Listings
The search_listings endpoint accepts up to eight optional parameters: query (keyword), category (numeric ID), region, city, town (numeric ISTAT code), price_max, limit, and offset. Results come back as an ads array where each object carries a urn, subject (title), body (description), category, geo, advertiser, features, images, and urls. The count_all field exposes the total result count, and start provides the next pagination offset. Category IDs and location IDs can be discovered in advance using get_categories and get_locations respectively.
Real Estate and Dealer Endpoints
get_real_estate_listings is a focused variant that adds price_min, price_max, and a listing_type parameter (s for sale, a for rent). Sub-category IDs cover Appartamenti (7), Ville (29), Terreni (30), and others under the Real Estate macro-category (6). get_dealer_listings accepts a user_id (found in any listing's advertiser.user_id field) and returns paginated results scoped to that advertiser — useful for monitoring a specific agency or private seller's active inventory.
Listing Details and Seller Contact
get_listing_details takes a numeric ad_id or full URN and returns the complete listing object including all features (price, condition, shipping), the full body description, all images with CDN URLs, and geo broken down to region, city, and town. get_seller_phone takes a listing URN and returns the seller's phone_number string. The endpoint returns a 404-style upstream error when no phone number is attached to the listing — this is common for private sellers and less common for business/dealer accounts.
Categories and Locations
get_categories returns the full category tree with no required inputs. Each entry includes a numeric key (used as the category parameter elsewhere), a value display name, a friendly_name URL slug, a weight sort order, and an optional macrocategory_id linking sub-categories to their parent. get_locations accepts a query string (e.g. "Milano" or "Bari") and returns matching region, province, and comune objects with the numeric IDs needed by the location parameters across all search endpoints.
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 used-car listings by filtering
search_listingswith category ID 2 and a city or region ID - Monitor real estate listings for rent in a specific province using
get_real_estate_listingswithlisting_type=aand acityID - Track a dealer's full active inventory over time by polling
get_dealer_listingswith theiruser_id - Build a price-comparison tool for electronics by querying
search_listingswith a keyword andprice_maxacross multiple categories - Enrich a CRM with seller phone numbers by passing listing URNs from search results to
get_seller_phone - Populate a location picker by resolving Italian city and region names to numeric IDs via
get_locations - Audit listing freshness and category distribution by iterating paginated results with
offsetand inspectingcount_all
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Subito.it offer an official developer API?+
What does `get_listing_details` return beyond what search results include?+
body description, the complete features array (which can include price, condition, and shipping details), all image objects with both base_url and cdn_base_url, and a urls object with desktop and mobile links. Search results include a subset of these fields; the detail endpoint is needed for the complete feature list and all images.Are seller phone numbers available for all listings?+
get_seller_phone returns a phone_number string when one is associated with the listing. Private sellers frequently omit phone numbers; business and dealer accounts more commonly include them. The endpoint returns an upstream 404 error when no phone is available, so callers should handle that response explicitly.Does the API expose listing analytics such as view counts or save counts?+
Can I filter search results by condition (new vs. used) or shipping availability?+
search_listings endpoint does not currently accept condition or shipping as input filters. Those attributes appear as fields inside the features array of returned listing objects and in get_listing_details, so filtering must be done client-side after retrieval. You can fork this API on Parse and revise it to add those as server-side filter parameters.