API Scraper Immobiliare manual

What it does

• Queries the Immobiliare.it search endpoint specified in the code through the requests library.
• Uses the sale contract code when tipo is exactly vendita; for any other value it sends the rental contract code.
• Uses a six-city mapping to choose a region: Milano, Roma, Torino, Napoli, Bologna, and Firenze.
• Requests no more than five pages, with 50 requested results per page, and waits one second after each processed page.
• Collects an id, title, price, square metres, rooms, area, city, floor, URL, source, and scraping date for each result.
• Creates a UTF-8 CSV when at least one listing is collected and prints basic statistics in the terminal.
• Calculates the listing count, average, minimum and maximum price, average square metres, and an average ratio of available total prices to available total square metres.

What it does not do

• It does not query Idealista or Casa.it: the operational code calls only Immobiliare.it.
• It does not truly filter by municipality: the city parameter chooses a region in the mapping and is written to the CSV.
• It does not generate a JSON file, including the annunci.csv and annunci.json names stated in the README.
• It does not include code to export to or authenticate with Google Sheets.
• It does not perform historical searches, deduplication, automated scheduling, notifications, or property valuations.
• It does not guarantee endpoint availability, completeness, recency, accuracy, or the lawfulness of data reuse.

Requirements

• Extracted archive: Extract the ZIP and keep immobiliare-scraper.py and requirements.txt together. The README files are reference guides.
• Python 3.9 or later: The script uses annotations such as list[Annuncio], which require Python 3.9 or later. The package check was performed with Python 3.12.3.
• Terminal and virtual environment: These are needed to install the dependency without mixing it with other Python projects.
• Internet connection: It is needed only when you run the script because the script sends HTTPS requests to the service named in the code.
• Python requests dependency: This is the only declared dependency, version 2.31 or later; the installation command installs it with its technical dependencies.
• Permitted portal access and a lawful basis for data use: Before use, check site terms, robots.txt where applicable, rate limits, any permissions, and GDPR obligations. The package does not require an account, token, or API key.
• Text editor: You need one to edit the scraper.search call in the last section of immobiliare-scraper.py.

Step-by-step setup

1. 1. Extract the package. Unzip the delivered file to a working folder of your choice. Check that immobiliare-scraper.py, requirements.txt, README.md, and README.en.md are in the same folder.
2. 2. Read the delivered documentation. README.md is the original Italian guide. README.en.md is an informational English translation and says that the Italian original remains authoritative. Read the rules of the portal you intend to query before proceeding.
3. 3. Open a terminal in the extracted folder. In a terminal, move to the folder containing the script. The command below shows the expected contents. Replace the path with your real folder path.
4. 4. Check Python and create an isolated environment. Confirm that Python is available and create a virtual environment named .venv. If python does not work on your system, use the command you normally use to start Python, provided that it is Python 3.9 or later.
5. 5. Activate the virtual environment. On macOS or Linux, activate the environment before installing the dependency. Your terminal prompt normally shows .venv after successful activation.
6. 6. Install the declared dependency. Install exactly what is listed in requirements.txt. Installation needs an Internet connection and may use the Python package repository configured on your system.
7. 7. Open the script’s initial configuration. Open immobiliare-scraper.py and find the final block beginning with if __name__ == "__main__". The scraper.search line contains the four parameters to adapt: city, type, maximum price, and minimum square metres.
8. 8. Set realistic filters and check the mapping. Use vendita for sale and affitto for rental. The cities explicitly mapped are milano, roma, torino, napoli, bologna, and firenze, without case sensitivity. For any other text, the script uses lombardia as the region and still saves your chosen text in the city column, so do not assume municipality-level filtering.
9. 9. Run the script once for the first check. After checking permissions, portal terms, robots.txt where applicable, and portal request limits, run the script from the same folder. Keep the terminal open until you see the count and, when results exist, the statistics.
10. 10. Check the actual output. If the script finds at least one listing, it creates a CSV named immobiliare_milano_YYYYMMDD.csv, even if you changed the city. Open it with a spreadsheet or editor that supports UTF-8. If the count is zero, the code creates no CSV. Do not expect a JSON file or Google Sheets synchronisation: they are not implemented in this delivery.

Daily use

Review filters and permission before every run

Check city, type, maximum price, and minimum square metres in the final call. Reconfirm that your use is permitted by the portal and proportionate to its rules.

Run from the script folder

Run the command in the folder containing immobiliare-scraper.py. This ensures that any CSV is created in the expected folder and is easy to find.

Watch the terminal

At startup, the script prints a fixed message about Milano and sale; it does not update when you edit the filters. Use your configured parameters and the CSV instead to interpret the run.

Check the CSV before analysing it

Inspect headers, URLs, area, city, and missing fields. The scraping date is when the script created that row, not the listing publication date.

Interpret the summary cautiously

The terminal summary is calculated only from records collected in that run. Always compare individual rows, applied filters, and missing values before using it in analysis.

Keep runs separately

The CSV filename includes the date but not the time; multiple runs on the same day with the same prefix can overwrite the file. Rename or archive each CSV after checking it.

Practical cases

Preliminary review of Lombardy sale listings

A person studying the property market wants to inspect in a spreadsheet the listings returned with a price and area threshold.

1. Leave citta set to milano, understanding that the request uses the Lombardy region.
2. Set tipo to vendita and choose positive prezzo_max and mq_min thresholds.
3. Run the script only where the portal allows your use and at a responsible frequency.
4. Open the generated CSV and compare the area, price, surface, and URL in individual rows.

You obtain a local CSV of listings returned in that run, suitable for manual exploratory analysis.

Review of rental listings associated with Rome

A small office wants to inspect a set of rental listings associated with the roma value in the code mapping, without treating it as a precise municipality filter.

1. Replace the first argument with roma and the second argument with affitto.
2. Choose thresholds that fit the review you want to perform.
3. Update the output prefix if you want the CSV filename to indicate Rome.
4. Run the script and check the areas and URLs in the produced file.

You obtain data to review manually, with roma written in the CSV city field and the request set to the Lazio region.

Manual comparison of two runs

An analyst wants to qualitatively compare results from two different filters while keeping a record of the output files.

1. Perform a first permitted search with one filter combination.
2. Rename the resulting CSV to include the date, time, and filters in a name you choose.
3. Change only one threshold or the contract type in the scraper.search call.
4. Run again in compliance with the portal’s rules and compare the columns in both CSV files.

You obtain two local exports with documented context to assess without treating differences as complete or definitive data.

Learning the Python-to-CSV flow

Someone learning Python wants to examine a simple example of a dataclass, HTTP request, data transformation, and CSV export.

1. Read the Annuncio dataclass and its eleven properties.
2. Inspect the search method and request parameters without running it.
3. See how to_csv uses asdict and csv.DictWriter.
4. Run only if authorised, then compare the CSV headers with the dataclass fields.

You obtain a concrete example to study and, where running it is permitted, a local CSV that shows the actual output structure.

Tips

• Start with the values already in the code to check installation and output format before changing several items at once.
• Use lowercase for mapped cities, even though the code also normalises the value for comparison.
• Treat a city value outside the six mapped names as a Lombardy search until you have changed and understood the _get_region_code function.
• Do not infer that the CSV contains only listings from one municipality: inspect the URL, area, and individual rows.
• Open the CSV as UTF-8 to preserve Italian characters in titles and areas.
• Do not arbitrarily increase pages, results per page, or frequency: the code already pauses for one second, but you must still respect terms, robots.txt, and service rate limits.
• If you change city, also change the immobiliare_milano_ filename prefix to avoid misleading labels.
• Archive CSV files with a note of the filters used, because their filenames do not contain the type, thresholds, or run time.
• Treat price, area, rooms, and floor as fields that may be missing or formatted by the service; verify records before further calculations.
• Do not share or publish information that may contain personal data without a lawful basis and an assessment of applicable obligations.

Troubleshooting

The python command is not found or reports an old version.

Python is not installed, is not on PATH, or is older than the list[Annuncio] syntax used by the script. Install or select Python 3.9 or later using your system’s normal procedure, then check the version again and recreate the virtual environment.

I see ModuleNotFoundError: No module named requests.

The dependency was not installed in the interpreter used to start the script, or the virtual environment is not active. Activate .venv and run pip install -r requirements.txt. Then start the script with the python from the same environment; do not edit requirements.txt unless you know why.

The run ends with a connection, timeout, or certificate error.

The script makes an HTTPS request with a 10-second timeout and the delivered code does not catch network exceptions. Check your connection, proxy, and local certificate setup. Also verify whether the portal permits your access; do not bypass blocks, rate limits, or protections.

The terminal says Trovati 0 annunci and no CSV is created.

The endpoint returned a non-success response, no results in the pages read, or filters incompatible with returned data. The code calls to_csv only when the list is not empty. Review terms and permissions, then revisit the four filters without trying to increase requests aggressively. Remember that city is translated to a region and an unmapped value uses Lombardy.

The CSV name says Milano even though I configured another city.

The immobiliare_milano_ prefix is written literally in the to_csv call in the final block. Change only that prefix to a consistent label before the run, or rename the file after creation. This change does not change the search.

I am looking for a JSON file but cannot find one.

The README mentions JSON, but the actual code includes only the to_csv method and calls only the CSV export. Use the produced CSV. Do not assume annunci.json will be created, and do not present an external conversion as a package feature.

I do not see data from Idealista, Casa.it, or Google Sheets.

The opening comment and README mention these possibilities, but the delivered executable flow uses only the Immobiliare.it base URL and has no Google Sheets code. Limit expectations to collection from Immobiliare.it and local CSV output. Any additional integration needs separate development and compliance with the relevant services’ rules.

The startup message still says Milano — vendita after I change parameters.

The startup print string is fixed in the final block and does not use the configured values. Do not use that message as confirmation of filters. Check the scraper.search line, then verify city, area, and URLs in the resulting CSV.

The statistics appear unrepresentative or some values are missing.

Statistics are calculated only from available price and area fields in collected results; they are not a property valuation and do not verify source data. Inspect the CSV row by row, note missing values, and use the figures only as a technical collection summary, not as the sole basis for economic decisions.

Limits to know

• The script depends on an external endpoint outside the package’s control; site changes, non-200 responses, unexpected formats, or access restrictions can stop it.
• The city filter is not a municipality filter: it is a region mapping for six names, while other names fall back to Lombardy.
• No more than five pages and 50 requested results per page are attempted, but the actual number depends on the external response and filters.
• Extracted data may be incomplete, incorrect, duplicated, removed, or outdated. Always verify the original listing through its URL.
• Respect terms of use, robots.txt where applicable, rate limits, database rights, GDPR, and every other applicable rule. Do not use the program to bypass controls or collect personal data without a lawful basis.
• Prices and statistics are technical information gathered by the script, not property, financial, legal, or tax advice.
• The package contains no API keys, credentials, email sending, notifications, scheduling, JSON output, or Google Sheets integration.

Frequently asked questions

Do I need to create an account or enter an API key?

No. The delivered files do not contain or request an account, token, password, or API key. This does not replace your duty to check whether the portal permits the type of access you intend to make.

Which sites are actually queried?

The operational code makes requests only to the Immobiliare.it base URL. There are no operational calls to Idealista, Casa.it, or Google Sheets.

Does the script really search in my chosen municipality?

Not demonstrably from the code. For six city names it chooses a region; for all other names it chooses Lombardy. The city text is also written to the CSV, but it is not passed as a municipality filter in the request.

Why do I not get annunci.json?

The delivered script does not implement JSON export. The README statement does not match the executable code, which saves only CSV when it finds results.

Where is the CSV saved and what is it called?

It is created in the folder from which you run the script, only when collection includes at least one listing. Its name follows immobiliare_milano_YYYYMMDD.csv, and the Milano prefix remains until you edit it in code.

How many listings does it collect?

The code tries to read pages 1 through 5 and requests 50 results per page. It may stop earlier when a response is not 200 or when no results are found; the number obtained is not guaranteed.

Can I use the statistics to decide on a purchase or investment?

No. They are simple calculations on data available in one run and do not replace listing checks or professional advice. Evaluate sources, missing fields, and risks before making any decision.