# StayYield Intelligence (`ayrtondavoli97/italy-bnb-revenue-intelligence`) Actor

Premium Italian real estate intelligence for short-term rental investors. Analyze listings, estimate BnB potential, ROI, yield, payback period, and risk signals to discover the best investment opportunities faster.

- **URL**: https://apify.com/ayrtondavoli97/italy-bnb-revenue-intelligence.md
- **Developed by:** [Francesco Ayrton Davoli](https://apify.com/ayrtondavoli97) (community)
- **Categories:** AI, Automation, Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## StayYield Intelligence

Premium Italian real estate intelligence for BnB and short-term rental investment opportunities.

StayYield Intelligence collects real property listings, estimates short-term rental economics, applies risk checks, and ranks opportunities using an investor-oriented score.

It helps investors, hosts, agencies, and analysts screen Italian properties faster by combining listing data, ROI estimates, payback, yield, location signals, and risk flags in one structured dataset.

---

### What you get

Each run produces a structured dataset of real listings with:

- source listing URL and image
- city, province, region and coordinates when available
- purchase price and price per square meter
- surface, rooms, bathrooms and guest-capacity estimate
- distance-to-sea estimate and source of that estimate
- short-term rental revenue assumptions
- gross and net annual revenue
- gross yield, net yield and payback period
- pessimistic and optimistic scenarios
- legal, renovation and property-use risk flags
- risk-adjusted investment score
- final investor-oriented rank score
- final recommendation and ranking notes

The production pipeline currently uses the most stable validated source to ensure repeatable output on Apify.

---

### Best use cases

This actor is useful for:

- BnB investors screening Italian cities
- short-term rental operators looking for acquisition targets
- real estate scouts building lead lists
- agencies preparing data-driven opportunity reports
- analysts comparing locations, yields and risk profiles
- local operators validating whether a property is worth deeper due diligence

---

### Why it is different

Most real estate datasets stop at listing data: price, surface, photos and location.

StayYield Intelligence adds an investment layer:

1. It estimates total capital required, including renovation cost.
2. It estimates short-term rental revenue based on market assumptions.
3. It computes gross yield, net yield and payback.
4. It flags problematic assets such as auctions, deposits, land, rural special assets and heavy renovation cases.
5. It creates a final ranking designed to surface the strongest BnB-style opportunities first.

The result is a dataset that is easier to evaluate than raw listings.

---

### Recommended input

For a stable premium run, start with Puglia:

```json
{
  "runMode": "investment_dataset",
  "regions": ["puglia"],
  "sources": ["wikicasa"],
  "maxItems": 500,
  "wikicasaApiLimit": 25,
  "wikicasaMaxOffsetsPerCity": 10,
  "minApiItemsBeforeCrawler": 1,
  "useBrowserFallback": false,
  "useApifyProxy": false,
  "expectedNightlyRate": 120,
  "expectedOccupancyRate": 0.55,
  "financingMode": "cash",
  "renovationLevel": "medium",
  "propertyCondition": "good"
}
````

***

### Important output fields

| Field | Meaning |
|---|---|
| `portfolio_rank` | Final position in the ranked dataset |
| `final_rank_score` | Investor-oriented ranking score, 0-100 |
| `final_recommendation` | Final label: STRONG\_BUY, BUY, WATCH, HIGH\_RISK or AVOID |
| `final_rank_notes` | Explanation of bonuses/penalties used in the final ranking |
| `adjusted_investment_score` | Risk-adjusted base investment score |
| `net_yield_pct` | Estimated annual net yield after operating costs |
| `payback_years` | Estimated simple payback period |
| `distance_to_sea_km` | Estimated distance from the sea |
| `distance_to_sea_source` | Whether the sea distance came from city baseline or listing text |
| `property_use_risk` | Residential/use risk: LOW, MEDIUM or HIGH |
| `legal_risk` | Legal/auction/conformity risk: LOW, MEDIUM or HIGH |
| `renovation_risk` | Renovation risk: LOW, MEDIUM or HIGH |
| `listing_quality_flags` | Human-readable warning flags |

***

### Example output record

```json
{
  "portfolio_rank": 1,
  "title": "Bilocale in Via delle Perle, Gallipoli",
  "city": "Gallipoli",
  "province": "Lecce",
  "purchase_price_eur": 60000,
  "surface_sqm": 28,
  "distance_to_sea_km": 0.1,
  "distance_to_sea_source": "text_100m_sea",
  "net_yield_pct": 19.38,
  "payback_years": 5.16,
  "property_use_risk": "LOW",
  "legal_risk": "LOW",
  "renovation_risk": "LOW",
  "final_rank_score": 100,
  "final_recommendation": "STRONG_BUY",
  "final_rank_notes": [
    "bonus_high_net_yield",
    "bonus_fast_payback",
    "bonus_text_verified_sea_distance"
  ]
}
```

***

### Ranking logic

StayYield Intelligence keeps two levels of scoring:

- `adjusted_investment_score`: conservative quality and risk score.
- `final_rank_score`: portfolio ranking score used to order the dataset.

The final ranking rewards:

- high net yield
- short payback period
- verified closeness to the sea
- low risk flags
- strong tourism-market fit

It penalizes:

- legal/auction/conformity risk
- heavy renovation risk
- non-residential or unclear asset use
- rural special assets that require deeper due diligence
- weak payback or weak yield
- very small units with limited guest capacity

***

### Source strategy

The production pipeline currently uses the most stable validated source to ensure repeatable output on Apify. Reliability is prioritized over noisy multi-source scraping attempts that can burn compute and return empty output.

Future versions may add more sources when they can be integrated with the same level of stability.

***

### Limitations

This actor provides analytical estimates, not financial or real estate advice.

Verify manually before buying any property:

- exact address and real distance from the sea
- legal and urban-planning compliance
- short-term rental rules in the municipality
- building condition and renovation quotes
- condominium rules
- actual occupancy and nightly-rate data
- taxation and licensing requirements

Use the output as a screening layer, not as a final investment decision.

# Actor input Schema

## `runMode` (type: `string`):

Choose Source scan for a quick extraction quality check, or Premium investment dataset for the full ranked ROI output.

## `regions` (type: `array`):

Select the market to analyze. Puglia is the validated premium baseline.

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

Maximum number of real listings to collect and rank. Use 100 for quick tests, 500 for a premium dataset run.

## `cities` (type: `array`):

Optional city names to narrow the run. Leave empty to use the built-in premium city set for the selected region.

## `expectedNightlyRate` (type: `number`):

Fallback nightly rate used when the actor estimates revenue. City/tourism adjustments may still be applied by the internal model.

## `expectedOccupancyRate` (type: `number`):

Fallback annual occupancy rate. Example: 0.55 means 55% occupancy.

## `financingMode` (type: `string`):

Choose whether returns are calculated as a cash acquisition or with mortgage assumptions when supported.

## `renovationLevel` (type: `string`):

Default renovation assumption when the listing does not clearly state the condition. Listings with renovation-risk text are automatically upgraded to heavier assumptions.

## `propertyCondition` (type: `string`):

Default property condition used by ROI when source text does not contain stronger condition signals.

## `minInvestmentScore` (type: `integer`):

Optional filter on the risk-adjusted base score. Keep 0 to export the full ranked dataset.

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

Optional minimum listing price. Use 0 to disable.

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

Optional maximum listing price. Use 0 to disable.

## `minSurfaceSqm` (type: `integer`):

Optional minimum surface in square metres. Use 0 to disable.

## `otaFeeRate` (type: `number`):

Estimated OTA/platform commission rate. Example: 0.15 means 15%.

## `cleaningCostPerBookedNight` (type: `number`):

Estimated cleaning cost allocated to each booked night.

## `utilitiesRate` (type: `number`):

Estimated utilities cost as a share of gross revenue.

## `maintenanceReserveRate` (type: `number`):

Estimated maintenance reserve as a share of gross revenue.

## `insuranceRate` (type: `number`):

Estimated insurance cost as a share of gross revenue.

## `taxRate` (type: `number`):

Rough analytical tax reserve, not tax advice.

## `managementFeeRate` (type: `number`):

Estimated property management fee as a share of gross revenue. Use 0 if self-managed.

## `sources` (type: `array`):

Production source. Keep Wikicasa selected for stable Apify runs.

## `wikicasaApiLimit` (type: `integer`):

Number of Wikicasa API items requested per offset. Default 25 is stable.

## `wikicasaMaxOffsetsPerCity` (type: `integer`):

How many offsets/pages to request per configured city/locality.

## `minApiItemsBeforeCrawler` (type: `integer`):

Browser fallback starts only if Wikicasa API returns fewer than this number of listings. Use 1 to disable fallback when API returns anything.

## `useBrowserFallback` (type: `boolean`):

Optional fallback only. Production Wikicasa API runs normally do not need browser fallback.

## `useApifyProxy` (type: `boolean`):

Not required for the validated Wikicasa API flow. Enable only for fallback experiments.

## `apifyProxyGroups` (type: `array`):

Proxy groups used only if proxy is enabled.

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

Optional specific Wikicasa URLs. Usually not needed for premium runs.

## `propertiesJson` (type: `string`):

Advanced fallback. Paste a JSON array of property objects if you already have listing data.

## Actor input object example

```json
{
  "runMode": "investment_dataset",
  "regions": [
    "puglia"
  ],
  "maxItems": 500,
  "expectedNightlyRate": 120,
  "expectedOccupancyRate": 0.55,
  "financingMode": "cash",
  "renovationLevel": "medium",
  "propertyCondition": "good",
  "minInvestmentScore": 0,
  "minPrice": 0,
  "maxPrice": 0,
  "minSurfaceSqm": 0,
  "otaFeeRate": 0.15,
  "cleaningCostPerBookedNight": 18,
  "utilitiesRate": 0.08,
  "maintenanceReserveRate": 0.06,
  "insuranceRate": 0.02,
  "taxRate": 0.1,
  "managementFeeRate": 0,
  "sources": [
    "wikicasa"
  ],
  "wikicasaApiLimit": 25,
  "wikicasaMaxOffsetsPerCity": 10,
  "minApiItemsBeforeCrawler": 1,
  "useBrowserFallback": false,
  "useApifyProxy": false,
  "apifyProxyGroups": [
    "RESIDENTIAL"
  ]
}
```

# Actor output Schema

## `dataset` (type: `string`):

Complete Apify dataset containing all ranked investment records.

## `top_ranked_json` (type: `string`):

Open the full dataset as JSON. Sort by portfolio\_rank ascending to review the best opportunities first.

## `csv_export` (type: `string`):

CSV export for spreadsheet analysis, client reports or lead prioritization workflows.

## `xlsx_export` (type: `string`):

Excel export for premium opportunity review and manual due diligence.

## `key_fields` (type: `string`):

Main premium output columns: portfolio\_rank, final\_rank\_score, final\_recommendation, final\_rank\_notes, purchase\_price\_eur, total\_investment\_eur, net\_yield\_pct, payback\_years, distance\_to\_sea\_km, legal\_risk, renovation\_risk, property\_use\_risk, listing\_quality\_flags, source\_url.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("ayrtondavoli97/italy-bnb-revenue-intelligence").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("ayrtondavoli97/italy-bnb-revenue-intelligence").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{}' |
apify call ayrtondavoli97/italy-bnb-revenue-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=ayrtondavoli97/italy-bnb-revenue-intelligence",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "StayYield Intelligence",
        "description": "Premium Italian real estate intelligence for short-term rental investors. Analyze listings, estimate BnB potential, ROI, yield, payback period, and risk signals to discover the best investment opportunities faster.",
        "version": "0.0",
        "x-build-id": "blq9VqCTtcgZzCrRt"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/ayrtondavoli97~italy-bnb-revenue-intelligence/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-ayrtondavoli97-italy-bnb-revenue-intelligence",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/ayrtondavoli97~italy-bnb-revenue-intelligence/runs": {
            "post": {
                "operationId": "runs-sync-ayrtondavoli97-italy-bnb-revenue-intelligence",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/ayrtondavoli97~italy-bnb-revenue-intelligence/run-sync": {
            "post": {
                "operationId": "run-sync-ayrtondavoli97-italy-bnb-revenue-intelligence",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "runMode": {
                        "title": "Run mode",
                        "enum": [
                            "investment_dataset",
                            "source_scan"
                        ],
                        "type": "string",
                        "description": "Choose Source scan for a quick extraction quality check, or Premium investment dataset for the full ranked ROI output.",
                        "default": "investment_dataset"
                    },
                    "regions": {
                        "title": "Target region",
                        "type": "array",
                        "description": "Select the market to analyze. Puglia is the validated premium baseline.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "puglia",
                                "sicilia",
                                "campania",
                                "toscana",
                                "lazio",
                                "lombardia",
                                "veneto",
                                "liguria",
                                "sardegna",
                                "emilia_romagna",
                                "calabria",
                                "piemonte",
                                "umbria",
                                "marche",
                                "abruzzo",
                                "friuli_venezia_giulia",
                                "trentino_alto_adige",
                                "basilicata",
                                "all_italy"
                            ],
                            "enumTitles": [
                                "Puglia - validated",
                                "Sicilia",
                                "Campania",
                                "Toscana",
                                "Lazio",
                                "Lombardia",
                                "Veneto",
                                "Liguria",
                                "Sardegna",
                                "Emilia-Romagna",
                                "Calabria",
                                "Piemonte",
                                "Umbria",
                                "Marche",
                                "Abruzzo",
                                "Friuli-Venezia Giulia",
                                "Trentino-Alto Adige",
                                "Basilicata",
                                "All Italy"
                            ]
                        },
                        "default": [
                            "puglia"
                        ]
                    },
                    "maxItems": {
                        "title": "Max listings to analyze",
                        "minimum": 10,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "Maximum number of real listings to collect and rank. Use 100 for quick tests, 500 for a premium dataset run.",
                        "default": 500
                    },
                    "cities": {
                        "title": "Optional city filter",
                        "type": "array",
                        "description": "Optional city names to narrow the run. Leave empty to use the built-in premium city set for the selected region.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "expectedNightlyRate": {
                        "title": "Fallback nightly rate (€)",
                        "minimum": 20,
                        "maximum": 1000,
                        "type": "number",
                        "description": "Fallback nightly rate used when the actor estimates revenue. City/tourism adjustments may still be applied by the internal model.",
                        "default": 120
                    },
                    "expectedOccupancyRate": {
                        "title": "Fallback occupancy rate",
                        "minimum": 0.1,
                        "maximum": 0.95,
                        "type": "number",
                        "description": "Fallback annual occupancy rate. Example: 0.55 means 55% occupancy.",
                        "default": 0.55
                    },
                    "financingMode": {
                        "title": "Financing mode",
                        "enum": [
                            "cash",
                            "mortgage"
                        ],
                        "type": "string",
                        "description": "Choose whether returns are calculated as a cash acquisition or with mortgage assumptions when supported.",
                        "default": "cash"
                    },
                    "renovationLevel": {
                        "title": "Default renovation level",
                        "enum": [
                            "light",
                            "medium",
                            "heavy"
                        ],
                        "type": "string",
                        "description": "Default renovation assumption when the listing does not clearly state the condition. Listings with renovation-risk text are automatically upgraded to heavier assumptions.",
                        "default": "medium"
                    },
                    "propertyCondition": {
                        "title": "Default property condition",
                        "enum": [
                            "excellent",
                            "good",
                            "average",
                            "poor"
                        ],
                        "type": "string",
                        "description": "Default property condition used by ROI when source text does not contain stronger condition signals.",
                        "default": "good"
                    },
                    "minInvestmentScore": {
                        "title": "Minimum base investment score",
                        "minimum": 0,
                        "maximum": 100,
                        "type": "integer",
                        "description": "Optional filter on the risk-adjusted base score. Keep 0 to export the full ranked dataset.",
                        "default": 0
                    },
                    "minPrice": {
                        "title": "Minimum purchase price (€)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Optional minimum listing price. Use 0 to disable.",
                        "default": 0
                    },
                    "maxPrice": {
                        "title": "Maximum purchase price (€)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Optional maximum listing price. Use 0 to disable.",
                        "default": 0
                    },
                    "minSurfaceSqm": {
                        "title": "Minimum surface (sqm)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Optional minimum surface in square metres. Use 0 to disable.",
                        "default": 0
                    },
                    "otaFeeRate": {
                        "title": "OTA commission rate",
                        "minimum": 0,
                        "maximum": 0.5,
                        "type": "number",
                        "description": "Estimated OTA/platform commission rate. Example: 0.15 means 15%.",
                        "default": 0.15
                    },
                    "cleaningCostPerBookedNight": {
                        "title": "Cleaning cost per booked night (€)",
                        "minimum": 0,
                        "maximum": 250,
                        "type": "number",
                        "description": "Estimated cleaning cost allocated to each booked night.",
                        "default": 18
                    },
                    "utilitiesRate": {
                        "title": "Utilities cost rate",
                        "minimum": 0,
                        "maximum": 0.5,
                        "type": "number",
                        "description": "Estimated utilities cost as a share of gross revenue.",
                        "default": 0.08
                    },
                    "maintenanceReserveRate": {
                        "title": "Maintenance reserve rate",
                        "minimum": 0,
                        "maximum": 0.5,
                        "type": "number",
                        "description": "Estimated maintenance reserve as a share of gross revenue.",
                        "default": 0.06
                    },
                    "insuranceRate": {
                        "title": "Insurance rate",
                        "minimum": 0,
                        "maximum": 0.5,
                        "type": "number",
                        "description": "Estimated insurance cost as a share of gross revenue.",
                        "default": 0.02
                    },
                    "taxRate": {
                        "title": "Tax reserve rate",
                        "minimum": 0,
                        "maximum": 0.7,
                        "type": "number",
                        "description": "Rough analytical tax reserve, not tax advice.",
                        "default": 0.1
                    },
                    "managementFeeRate": {
                        "title": "Management fee rate",
                        "minimum": 0,
                        "maximum": 0.5,
                        "type": "number",
                        "description": "Estimated property management fee as a share of gross revenue. Use 0 if self-managed.",
                        "default": 0
                    },
                    "sources": {
                        "title": "Data source",
                        "type": "array",
                        "description": "Production source. Keep Wikicasa selected for stable Apify runs.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "wikicasa"
                            ],
                            "enumTitles": [
                                "Wikicasa.it - stable source"
                            ]
                        },
                        "default": [
                            "wikicasa"
                        ]
                    },
                    "wikicasaApiLimit": {
                        "title": "Wikicasa API page size",
                        "minimum": 1,
                        "maximum": 50,
                        "type": "integer",
                        "description": "Number of Wikicasa API items requested per offset. Default 25 is stable.",
                        "default": 25
                    },
                    "wikicasaMaxOffsetsPerCity": {
                        "title": "Wikicasa offsets per city",
                        "minimum": 1,
                        "maximum": 100,
                        "type": "integer",
                        "description": "How many offsets/pages to request per configured city/locality.",
                        "default": 10
                    },
                    "minApiItemsBeforeCrawler": {
                        "title": "Minimum API items before fallback",
                        "minimum": 0,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Browser fallback starts only if Wikicasa API returns fewer than this number of listings. Use 1 to disable fallback when API returns anything.",
                        "default": 1
                    },
                    "useBrowserFallback": {
                        "title": "Use browser fallback",
                        "type": "boolean",
                        "description": "Optional fallback only. Production Wikicasa API runs normally do not need browser fallback.",
                        "default": false
                    },
                    "useApifyProxy": {
                        "title": "Use Apify proxy",
                        "type": "boolean",
                        "description": "Not required for the validated Wikicasa API flow. Enable only for fallback experiments.",
                        "default": false
                    },
                    "apifyProxyGroups": {
                        "title": "Apify proxy groups",
                        "type": "array",
                        "description": "Proxy groups used only if proxy is enabled.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "RESIDENTIAL",
                                "AUTO"
                            ],
                            "enumTitles": [
                                "Residential",
                                "Auto / datacenter"
                            ]
                        },
                        "default": [
                            "RESIDENTIAL"
                        ]
                    },
                    "startUrls": {
                        "title": "Extra start URLs",
                        "type": "array",
                        "description": "Optional specific Wikicasa URLs. Usually not needed for premium runs.",
                        "items": {
                            "type": "object",
                            "required": [
                                "url"
                            ],
                            "properties": {
                                "url": {
                                    "type": "string",
                                    "title": "URL of a web page",
                                    "format": "uri"
                                }
                            }
                        }
                    },
                    "propertiesJson": {
                        "title": "Manual fallback JSON",
                        "type": "string",
                        "description": "Advanced fallback. Paste a JSON array of property objects if you already have listing data."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
