# Subito.it Classifieds Search & Price Extractor (`vexaloom-labs/subito-it-classifieds-search-and-price-extractor`) Actor

Search Subito.it classifieds for cars, electronics, or general items by keyword, Italian region, and price range, and get price, location, seller, and listing details for each result.

- **URL**: https://apify.com/vexaloom-labs/subito-it-classifieds-search-and-price-extractor.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, E-commerce, Lead generation
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Classifieds Search & Price Extractor

Subito.it is Italy's largest classifieds marketplace, with millions of ads spanning cars, electronics, property, jobs and everyday second-hand goods. This actor searches Subito.it and returns one structured record per listing — price, full description, condition, location, seller, every photo, and the category-specific details buyers actually compare (km, year and fuel for cars; surface, rooms and energy class for property; sector and contract for jobs).

### What this actor does

- Searches all of Subito.it or narrows to cars, electronics, real estate, jobs, or general items for sale.
- Filters by any of the 45 Subito.it categories, all 20 Italian regions, price range, ad type, private/company seller, condition, shipping availability, title-only matching, and urgent-only ads.
- Sorts by relevance, newest, or price ascending/descending.
- Paginates up to 10,000 listings per query slice.
- Scrapes specific ad URLs and search-result URLs directly.
- Returns full descriptions and all image URLs without extra detail-page requests.
- Exposes every upstream listing feature through typed fields plus a generic `attributes` map, so niche categories are covered too.

### Modes

| Mode | What it searches |
|---|---|
| `searchAll` | Every category. Combine with `category` to target any of the 45 categories. |
| `searchItems` | General items for sale across all categories. |
| `searchCars` | Cars and vehicles (category `Auto`). |
| `searchElectronics` | The whole electronics tree (phones, computers, audio/video, gaming, cameras). |
| `searchRealEstate` | The whole property tree (apartments, villas, rooms, land, garages, holiday homes, offices). |
| `searchJobs` | Job offers. |
| `searchByUrls` | Specific Subito.it ad URLs and/or search-result URLs from `startUrls`. |

### Output per listing

| Field | Description |
|---|---|
| `adId` | Numeric Subito.it ad ID. |
| `title` | Listing title. |
| `description` | Full ad text. |
| `adType` / `adTypeKey` | Listing kind, e.g. `In vendita` / `s`, `In affitto` / `u`. |
| `price` | Numeric price in EUR, when the ad publishes one. |
| `priceText` | Price exactly as displayed, e.g. `600 €`. |
| `currency` | `EUR` when a price exists. |
| `condition` | Item/vehicle/building condition as labelled by Subito.it. |
| `category`, `categoryId`, `categorySlug`, `macroCategoryId` | Category hierarchy. |
| `publishedDate`, `publishedAt`, `expiresAt` | Display date, ISO publish timestamp, ISO expiry. |
| `city`, `province`, `region`, `regionId`, `regionSlug`, `location` | Location hierarchy. |
| `seller`, `sellerType`, `sellerId`, `shopId`, `shopName`, `isCompany` | Seller/shop metadata (`private` or `professional`). |
| `imageUrl`, `imageUrls`, `imageCount` | First photo, all photos, count. |
| `adUrl` | Canonical listing URL. |
| `attributes` | Every upstream feature label/value for the listing. |
| `shippable`, `shippingCost`, `shippingMethod`, `shippingCarriers` | Shipping details when offered. |
| `brand`, `model`, `year`, `mileageKm`, `fuel`, `gearbox`, `powerKw`, `powerHp`, `color`, `doors`, `seats`, `bodyType`, `pollutionClass`, `vehicleType`, `motoType`, `shipType`, `caravanType`, `bicycleType` | Vehicle fields when present. |
| `surfaceSqm`, `rooms`, `bathrooms`, `floor`, `totalFloors`, `furnished`, `elevator`, `balcony`, `garden`, `parking`, `heating`, `airConditioning`, `energyClass`, `buildingCondition`, `availableNow`, `holidayRental`, `lastFloor`, `reception`, `multiLevel`, `noAgency`, `roomType`, `officeType` | Property fields when present. |
| `jobSector`, `contractType`, `workHours`, `workLevel`, `educationLevel` | Job fields when present. |
| `urgent`, `availability`, `warrantyMonths`, `referenceCode`, `cin`, `size`, `registrationDate` | Other upstream flags and codes, when present. |
| `mode`, `scrapedAt` | Which mode produced the record and when it was fetched. |

Fields the source does not publish for a listing (for example a give-away with no price, or a private seller who hides their name) are omitted from that record — never filled with placeholders.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | Select | `searchItems` | Search scope; see the modes table. |
| `query` | String | – | Keyword. The prefill uses `iPhone`; leave empty to browse a category without a keyword. Ignored in `searchByUrls`. |
| `category` | Select | all | Any of the 45 Subito.it categories; overrides the mode's category. |
| `region` | Select | all Italy | One of the 20 Italian regions. |
| `priceMin`, `priceMax` | Integer | – | Price range in EUR. |
| `sort` | Select | `relevance` | Relevance, newest first, price low→high, price high→low. |
| `adType` | Select | all | For sale, for rent, give away, holiday rental, wanted. |
| `advertiserType` | Select | all | Private sellers or companies. |
| `condition` | Select | all | New, like new, excellent, good, damaged. |
| `shippableOnly` | Boolean | `false` | Only ads offering shipping. |
| `titleOnly` | Boolean | `false` | Match the keyword in titles only. |
| `urgentOnly` | Boolean | `false` | Only urgent ads (mainly jobs). |
| `startUrls` | Array | – | `(mode=searchByUrls)` Ad URLs (`...-123456789.htm`) and/or search URLs (`/annunci-lazio/vendita/auto/?q=bmw`). |
| `maxItems` | Integer | `20` | Maximum records to return (1–10,000). |

#### Example: cars in Lombardy under €20,000

```json
{
    "mode": "searchCars",
    "query": "BMW",
    "region": "lombardia",
    "priceMin": 5000,
    "priceMax": 20000,
    "sort": "priceasc",
    "maxItems": 50
}
```

#### Example: shippable like-new electronics

```json
{
    "mode": "searchElectronics",
    "query": "laptop",
    "condition": "20",
    "shippableOnly": true,
    "maxItems": 100
}
```

#### Example: apartments for rent in Lazio

```json
{
    "mode": "searchRealEstate",
    "query": "trilocale",
    "region": "lazio",
    "adType": "u",
    "maxItems": 50
}
```

#### Example: specific ads and a saved search

```json
{
    "mode": "searchByUrls",
    "startUrls": [
        { "url": "https://www.subito.it/telefonia/iphone-16-256-gb-udine-667511057.htm" },
        { "url": "https://www.subito.it/annunci-lazio/vendita/auto/?q=bmw&ps=5000&pe=20000" }
    ],
    "maxItems": 30
}
```

### Use cases

- **Price monitoring** — track a model or keyword and compare asking prices over time.
- **Reseller sourcing** — find private-seller cars or electronics below a threshold.
- **Market research** — measure listing volume and price bands by category and region.
- **Property and job boards** — pull structured listings into a sheet, CRM, or dashboard.
- **Deal alerts** — run frequently on `datedesc` and watch new ads for your saved searches.

### FAQ

**Do I need a Subito.it account?**
No. The actor reads public listings and needs no login, cookies, or API key.

**Do I need to configure a proxy?**
No. The actor picks its network route automatically.

**How many listings can I get in one run?**
Up to 10,000 per query slice. Subito.it stops serving results beyond 10,000 per search, so split broad searches by category, region, price band, or sort order to reach more.

**Why is `price` missing on some records?**
Some ads are give-aways, swaps, or "price on request". Subito.it publishes no price for them, so the field is omitted.

**Why are there no latitude/longitude fields?**
Subito.it does not publish coordinates in its public listing data. Use `city`, `province`, and `region` for location analysis.

**Why is `seller` empty for some ads?**
Private users can hide their name. Company sellers usually expose a shop name, which the actor returns.

**Does URL mode work with expired ads?**
Expired or removed ads are skipped; the run continues with the remaining URLs and reports how many were unavailable.

**Are all Subito.it categories covered?**
Yes — the `category` dropdown contains the full 45-entry taxonomy, from `Auto` to `Collezionismo`, plus property, job, and service categories.

**Is this affiliated with Subito.it?**
No. This is an independent tool that reads publicly available listings and is not affiliated with or endorsed by Subito.it.

# Actor input Schema

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

What to fetch from Subito.it. searchByUrls takes listing or search-result URLs in startUrls.

## `query` (type: `string`):

Keyword to search for, e.g. iPhone, divano, BMW. Leave empty to browse a category without a keyword. Ignored in searchByUrls mode.

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

Optional category filter. Overrides the category implied by the mode.

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

Italian region to filter by (friendly name). Leave empty to search all of Italy.

## `priceMin` (type: `integer`):

Minimum listing price in Euro.

## `priceMax` (type: `integer`):

Maximum listing price in Euro.

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

Result ordering.

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

Filter by listing kind: for sale, for rent, give away, holiday rental or wanted.

## `advertiserType` (type: `string`):

Filter by private sellers or companies.

## `condition` (type: `string`):

Item condition filter (most useful for goods and electronics).

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

Only listings that offer shipping.

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

Match the keyword against listing titles instead of title and description.

## `urgentOnly` (type: `boolean`):

Only listings marked urgent (mainly job ads).

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

(mode=searchByUrls) Subito.it ad URLs (...-123456789.htm) and/or search-result URLs (/annunci-lazio/vendita/auto/?q=bmw).

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

Maximum number of listings to return (1–10,000).

## Actor input object example

```json
{
  "mode": "searchItems",
  "query": "iPhone",
  "category": "",
  "region": "",
  "sort": "relevance",
  "adType": "",
  "advertiserType": "",
  "condition": "",
  "shippableOnly": false,
  "titleOnly": false,
  "urgentOnly": false,
  "maxItems": 3
}
```

# Actor output Schema

## `listings` (type: `string`):

Dataset containing all scraped Subito.it listings.

# 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 = {
    "mode": "searchItems",
    "query": "iPhone",
    "category": "",
    "region": "",
    "sort": "relevance",
    "adType": "",
    "advertiserType": "",
    "condition": "",
    "shippableOnly": false,
    "titleOnly": false,
    "urgentOnly": false,
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/subito-it-classifieds-search-and-price-extractor").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 = {
    "mode": "searchItems",
    "query": "iPhone",
    "category": "",
    "region": "",
    "sort": "relevance",
    "adType": "",
    "advertiserType": "",
    "condition": "",
    "shippableOnly": False,
    "titleOnly": False,
    "urgentOnly": False,
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/subito-it-classifieds-search-and-price-extractor").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 '{
  "mode": "searchItems",
  "query": "iPhone",
  "category": "",
  "region": "",
  "sort": "relevance",
  "adType": "",
  "advertiserType": "",
  "condition": "",
  "shippableOnly": false,
  "titleOnly": false,
  "urgentOnly": false,
  "maxItems": 3
}' |
apify call vexaloom-labs/subito-it-classifieds-search-and-price-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/subito-it-classifieds-search-and-price-extractor"
        }
    }
}
```

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/TnesfgqCgPfjeqcoR/builds/kb08eNncinzBQOc1Q/openapi.json