# Subito — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse listings on Subito.it, Italy's leading classifieds marketplace. Filter by keyword, category, location, and price. Retrieve listing details, real estate listings, dealer inventories, and seller contact information.

**Category:** Marketplaces | **Website:** [subito.it/](https://subito.it/) | **Docs:** [parse.bot/marketplace/01b8d429-40aa-4b9d-9645-d2701e278bdb/subito-it-api](https://parse.bot/marketplace/01b8d429-40aa-4b9d-9645-d2701e278bdb/subito-it-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-subito-it-api-01b8d429/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_categories

Get the full category and sub-category tree for Subito.it. Each category has a key (ID), value (display name), friendly_name (URL slug), weight (sort order), and optional macrocategory_id indicating its parent macro-category. Top-level entries without macrocategory_id are macro-categories themselves.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-subito-it-api-01b8d429/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_dealer_listings

Fetch all listings from a specific advertiser/dealer by their user ID. Returns paginated results. The user_id can be found in search results or listing details under the advertiser object.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results to return per page. |
| `offset` | integer | No | Pagination offset (start index). |
| `user_id` | string | Yes | The advertiser's numeric user ID (found in search results or listing details under advertiser.user_id). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-subito-it-api-01b8d429/get_dealer_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","user_id":"<string>"}'
```

### get_listing_details

Get full details for a single listing by its numeric ID. Returns the complete listing object including description, all images, all features (price, condition, shipping), advertiser info, and location. The ad_id can be a numeric listing ID (from the end of listing URLs) or a full URN from search results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ad_id` | string | Yes | Numeric listing ID (found at the end of listing URLs) or a full listing URN. If a URN is passed, the numeric ID is extracted automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-subito-it-api-01b8d429/get_listing_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ad_id":"<string>"}'
```

### get_real_estate_listings

Fetch real estate listings with optional sub-category, location, and price filters. Defaults to the Real Estate macro-category (ID 6). Returns paginated results sorted by recency.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Real estate category or sub-category ID: '6' (all Real Estate), '7' (Appartamenti), '29' (Ville), '30' (Terreni), '31' (Garage e box), '32' (Loft/mansarde), '33' (Case vacanza), '8' (Uffici e Locali commerciali), '43' (Camere/Posti letto). |
| `city` | string | No | City/Provincia ID (numeric). |
| `limit` | integer | No | Number of results to return per page. |
| `listing_type` | string | No | Listing type: 's' for sale, 'a' for rent. |
| `offset` | integer | No | Pagination offset (start index). |
| `price_max` | string | No | Maximum price filter (numeric string). |
| `price_min` | string | No | Minimum price filter (numeric string). |
| `region` | string | No | Region ID (numeric). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-subito-it-api-01b8d429/get_real_estate_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","city":"<string>","limit":"<integer>","listing_type":"<string>","offset":"<integer>","price_max":"<string>","price_min":"<string>","region":"<string>"}'
```

### get_seller_phone

Reveal the seller's phone number for a specific listing using its URN. Not all listings have phone numbers — private sellers often omit them; business/dealer listings typically include one. Returns stale_input when no phone is available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `urn` | string | Yes | The listing URN (e.g. 'id:ad:db386d21-15cd-40a0-9032-b7349f725010:list:649692973'), found in search_listings or get_listing_details results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-subito-it-api-01b8d429/get_seller_phone \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urn":"<string>"}'
```

### search_listings

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.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `advertiser_type` | string | No | Advertiser type: '0' for private, '1' for business. |
| `category` | string | No | Category ID (e.g. '6' for Real Estate, '2' for Cars, '12' for Telefonia). Use get_categories to discover all IDs. |
| `city` | string | No | City/Provincia ID (numeric). |
| `limit` | integer | No | Number of results to return per page. |
| `listing_type` | string | No | Listing type: 's' for sale (vendita), 'a' for rent (affitto). |
| `offset` | integer | No | Pagination offset (start index). |
| `price_max` | string | No | Maximum price filter (numeric string). |
| `price_min` | string | No | Minimum price filter (numeric string). |
| `query` | string | No | Search keyword. |
| `region` | string | No | Region ID (numeric). |
| `town` | string | No | Town/Comune ID (numeric ISTAT code). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-subito-it-api-01b8d429/search_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_type":"<string>","category":"<string>","city":"<string>","limit":"<integer>","listing_type":"<string>","offset":"<integer>","price_max":"<string>","price_min":"<string>","query":"<string>","region":"<string>","town":"<string>"}'
```