# Subito.it Scraper & API: Italy Listings and Prices (`clover_engineer/subito-it-scraper`) Actor

Subito.it scraper and API: search Italian classifieds (annunci) by keyword, region, category and price, or paste a search URL. Get price, condition, comune, province, seller type, photos and attributes as JSON, CSV or Excel. Pay only per listing: empty or blocked runs are free.

- **URL**: https://apify.com/clover_engineer/subito-it-scraper.md
- **Developed by:** [Clover](https://apify.com/clover_engineer) (community)
- **Categories:** E-commerce, Real estate, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 listing (basic)s

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Subito.it Scraper & API: Italy Listings and Prices

Subito.it scraper and API: get listings (annunci) from **Subito.it**, Italy's largest classifieds site, by keyword or by pasting a search URL. You get title, price in EUR, condition, town, province and region, seller type, photos, category-specific attributes and the full listing link, as clean JSON, CSV or Excel.

**You pay only for listings delivered.** Runs that find nothing or get blocked cost nothing, and there is no start fee.

### How to scrape Subito.it

1. Enter one or more **search queries** (e.g. `iphone 13`, `bici da corsa`), or paste **Subito.it search URLs** copied from your browser.
2. Optionally pick a **region**, **category**, **ad type**, **price range**, **sort order** and **seller type**.
3. Set **Max listings** and click **Start**.
4. Download the listings as **JSON, CSV or Excel**, or read them through the API.

### What it does

- **Searches** Subito.it the way you would in the browser: keyword plus region, category, ad type (for sale, for rent, wanted, giveaway), price range and sort order.
- **Accepts Subito search URLs** copied from your browser, keeping their filters.
- **Pages through results** automatically: 30 per page, up to Subito's own limit of 3,000 per search.
- **Removes duplicates** across pages and searches.
- **Filters** by seller type (private or company) after download, and you pay only for the listings kept.
- **Reads** the data Subito's own search page loads. No browser, so runs are fast: 30 listings in about 1 s, 70 in about 3 s in our tests.

### Use cases

- **Price research:** what do used iPhones, bikes or sofas really sell for in your region?
- **Deal alerts:** schedule a run sorted by newest and get new listings under your price.
- **Market monitoring for dealers and shops:** track competitors' listings and prices by category.
- **Datasets:** classifieds data for price models, resale-value studies and regional comparisons.

### Input

| Field | Default | Description |
|---|---|---|
| `queries` | `["iphone 13"]` (prefill) | Keywords, one search each. |
| `startUrls` | none | Subito.it search URLs, e.g. `https://www.subito.it/annunci-lombardia/vendita/telefonia/?q=iphone`. |
| `region` | `italia` | Whole country or one of the 20 regions. |
| `category` | `usato` (all) | e.g. `telefonia`, `auto`, `appartamenti`, `biciclette`, `arredamento-casalinghi`. |
| `adType` | `vendita` | `vendita`, `affitto`, `cerco`, `regalo`. |
| `minPrice` / `maxPrice` | none | Price range in EUR. Pick a category too: on "All categories" Subito ignores price filters, so the actor filters pages itself (slower, but you pay only for listings in range). |
| `sort` | `datedesc` | `datedesc`, `relevance`, `priceasc`, `pricedesc`. |
| `sellerType` | `all` | `all`, `private`, `company`. |
| `titleOnly` | `false` | Match keywords in the title only. |
| `shippableOnly` | `false` | Only listings with shipping. |
| `maxItems` | `100` | Total cap (0 = no cap). |
| `maxItemsPerSearch` | `0` | Cap per search. |
| `mode` | `basic` | `basic` or `enhanced` (see pricing). |
| `autoUpgradeOnBlock` | `true` | Switch to enhanced if Subito blocks basic mode. |
| `proxyConfiguration` | none | Your own proxy URLs (billed at the basic price). |

Example:

```json
{
  "queries": ["bici da corsa"],
  "region": "lombardia",
  "category": "biciclette",
  "minPrice": 300,
  "maxPrice": 1500,
  "sort": "priceasc",
  "maxItems": 70
}
```

### Output

One item per listing. A real item from our final test run (description shortened):

```json
{
  "id": "664647056",
  "url": "https://www.subito.it/telefonia/iphone-13-pro-max-256gb-parma-664647056.htm",
  "title": "iphone 13 Pro Max 256gb",
  "description": "Condizioni ottime \nStato batteria 91% (sostituita a gennaio 2026 originale in ce...",
  "price": 390,
  "currency": "EUR",
  "priceText": "390 €",
  "condition": "Ottimo - poco usato e ben conservato",
  "shippable": false,
  "category": "Telefonia",
  "categoryId": "12",
  "adType": "In vendita",
  "publishedAt": "2026-10-15T14:50:08",
  "town": "Parma",
  "province": "Parma",
  "provinceCode": "PR",
  "region": "Emilia-Romagna",
  "sellerType": "private",
  "sellerName": null,
  "images": ["https://images.sbito.it/api/v1/sbt-ads-images-pro/images/bb/bb933abb-ce96-40f1-b997-60b863523440?rule=gallery-desktop-1x-auto"],
  "attributes": {
    "Disponibile alla spedizione": "No",
    "Tipologia telefoni": "Cellulari e Smartphone",
    "Condizione": "Ottimo - poco usato e ben conservato"
  },
  "search": "iphone 13",
  "page": 1,
  "scrapedAt": "2026-10-15T13:07:52.758Z",
  "fetchMode": "basic",
  "charged": true
}
```

- **Overview view:** a compact table of title, price, condition, town, seller, date and link.
- **Run summary:** each run also writes a `RUN_SUMMARY` record. It holds the listings per pricing tier, whether the run switched to enhanced mode or was blocked, and what to do next.

### Use it via API, Python or n8n

Run it from any language through the Apify API, and get the results as JSON, CSV or Excel. Replace `<YOUR_USERNAME>` with the Apify username that publishes this actor, and `<TOKEN>` with your Apify API token.

```bash
curl -X POST "https://api.apify.com/v2/acts/<YOUR_USERNAME>~subito-it-scraper/run-sync-get-dataset-items?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"queries": ["iphone 13"], "region": "lombardia", "maxItems": 100}'
```

```python
from apify_client import ApifyClient

client = ApifyClient("<TOKEN>")
run = client.actor("<YOUR_USERNAME>/subito-it-scraper").call(run_input={"queries": ["iphone 13"], "region": "lombardia", "maxItems": 100})
for item in client.dataset(run["default_dataset_id"]).iterate_items():
    print(item)
```

In **n8n**, **Make** or **Zapier**, use the Apify integration and pick this actor. Schedule runs in Apify Console to get fresh data every day.

### Pricing: Basic vs Enhanced

| Tier | Price | When it's used |
|---|---|---|
| **Basic** (`result`) | **$1 per 1,000 listings** | Direct requests, or your own proxy. Works for most runs. |
| **Enhanced** (`result-enhanced`) | **$3 per 1,000 listings** | Through Apify residential proxy in Italy. The price includes the proxy cost. |

- **Auto-upgrade (on by default).** If Subito blocks basic mode, the actor retries twice, then continues through residential proxy.
  - Listings fetched before the switch stay at $1/1k; only those after it cost $3/1k.
  - The run's status message says when the switch happened, and every item's `fetchMode` shows its tier.
- **Never pay the enhanced price:** turn `autoUpgradeOnBlock` off. A blocked run then stops early, ends as succeeded with a "BLOCKED" message, and you pay only for listings already delivered.
- **What's free:** no start fee, nothing for empty results, retries or failed requests.

Other Subito actors charge $1–2.5 per 1,000 plus up to $0.005 per run start.

### Limits

- Subito shows at most 3,000 listings (100 pages) per search. Split big searches by region or price range.
- With a price range on "All categories", Subito ignores the range, so the actor filters the pages it reads. In our test (bicicletta, 200–400 €), it read 17 pages to deliver 60 matching listings; with category "biciclette" it took 2 pages.
- Data comes from search results. Phone numbers and the full seller profile are not collected.
- Private sellers' names are hidden by Subito in results, so `sellerName` is set only for shops.
- Subito can change its site at any time. If a run returns errors, please open an issue.

### FAQ

**My run says "BLOCKED". What do I do?**
Subito refused basic requests and auto-upgrade was off, or residential proxy wasn't available. You paid only for listings delivered. Turn on "Auto-upgrade when blocked", or set mode to `enhanced`, and run again.

**Why did some listings cost $3/1k?**
Subito blocked basic mode during your run and auto-upgrade switched to residential proxy. Check `fetchMode` on each item, or `RUN_SUMMARY`.

**Can I scrape a specific category page?**
Yes. Open it on subito.it, set your filters, copy the URL into `startUrls`.

**Do I need a proxy?**
Not usually. In our tests basic mode returned data without any blocks.

**How fresh is the data?**
Live: each run reads Subito at that moment.

**Is it legal to scrape Subito.it?**
This actor reads only public listing data that Subito.it shows to any visitor without logging in: title, price, location and photos. It does not collect phone numbers, e-mail addresses or private sellers' names, and it does not log in. Scraping public data is generally lawful in the EU, but how you use the data is up to you: respect Subito.it's terms and the GDPR if you store or process anything that relates to people. If in doubt, ask a lawyer.

# Actor input Schema

## `queries` (type: `array`):

Keywords to search, one search per line, e.g. "iphone 13" or "bici da corsa". Uses the region, category and filters below.

## `startUrls` (type: `array`):

Alternatively, paste search URLs copied from your browser, e.g. https://www.subito.it/annunci-lombardia/vendita/telefonia/?q=iphone. Their own filters are kept; the price, sort and shipping filters below are added on top.

## `region` (type: `string`):

Region for keyword searches. "italia" = whole country.

## `category` (type: `string`):

Subito category slug for keyword searches. "usato" = all categories. Examples: telefonia, informatica, auto, moto-e-scooter, appartamenti, arredamento-casalinghi, biciclette, libri-riviste, elettrodomestici, abbigliamento-accessori.

## `adType` (type: `string`):

For sale (vendita), for rent (affitto), wanted (cerco) or free giveaway (regalo).

## `minPrice` (type: `integer`):

Only listings priced at or above this. Works best with a specific category: on "All categories" Subito ignores price filters, so the actor filters the downloaded pages itself (slower, more pages read, but you still pay only for listings in range).

## `maxPrice` (type: `integer`):

Only listings priced at or below this. Same note as Min price.

## `sort` (type: `string`):

Order of results.

## `sellerType` (type: `string`):

Keep only private sellers or only companies (shops, dealers). Filtering happens after download, so you pay only for listings kept.

## `titleOnly` (type: `boolean`):

Search the title only, not the description (fewer false matches).

## `shippableOnly` (type: `boolean`):

Only listings that offer shipping.

## `maxItems` (type: `integer`):

Stop after this many listings in total. 0 = no limit (Subito serves at most 3,000 listings per search).

## `maxItemsPerSearch` (type: `integer`):

Stop each search after this many listings. 0 = no per-search limit.

## `mode` (type: `string`):

Basic ($1 per 1,000 listings): direct requests, works for most runs. Enhanced ($3 per 1,000): every request goes through Apify residential proxy in Italy, for when Subito blocks basic mode.

## `autoUpgradeOnBlock` (type: `boolean`):

If Subito blocks basic mode, continue the run through residential proxy and charge the listings fetched after the switch at the enhanced price ($3 instead of $1 per 1,000). Listings already fetched stay at the basic price. Turn off to never pay the enhanced price; a blocked run then stops early and you pay only for listings delivered.

## `proxyConfiguration` (type: `object`):

Optional. Your own proxy URLs are used in basic mode and billed at the basic price. Choosing Apify Proxy here is the same as enhanced mode.

## Actor input object example

```json
{
  "queries": [
    "iphone 13",
    "playstation 5"
  ],
  "startUrls": [
    {
      "url": "https://www.subito.it/annunci-lombardia/vendita/telefonia/?q=iphone"
    }
  ],
  "region": "italia",
  "category": "usato",
  "adType": "vendita",
  "sort": "datedesc",
  "sellerType": "all",
  "titleOnly": false,
  "shippableOnly": false,
  "maxItems": 30,
  "maxItemsPerSearch": 0,
  "mode": "basic",
  "autoUpgradeOnBlock": true
}
```

# Actor output Schema

## `results` (type: `string`):

All listings as JSON, one item per listing.

## `overview` (type: `string`):

Compact table: title, price, location, seller type, date and link.

## `runSummary` (type: `string`):

Counts per pricing tier, whether the run switched to enhanced mode or was blocked, and what to do next.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        "iphone 13"
    ],
    "maxItems": 30
};

// Run the Actor and wait for it to finish
const run = await client.actor("clover_engineer/subito-it-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "queries": ["iphone 13"],
    "maxItems": 30,
}

# Run the Actor and wait for it to finish
run = client.actor("clover_engineer/subito-it-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    "iphone 13"
  ],
  "maxItems": 30
}' |
apify call clover_engineer/subito-it-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clover_engineer/subito-it-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/FDTOlGr4KkoNDF0oF/builds/dfs8SX3bsuy262L6r/openapi.json