# SpotAHome Scraper | Fast & Reliable (`fatihtahta/spotahome-scraper`) Actor Extract Spotahome rental listings at scale with rich property detail, availability data, landlord signals, media, booking context, and flexible market filters. Built for enterprise-grade rental intelligence, market monitoring, and automated analytics pipelines. - **URL**: https://apify.com/fatihtahta/spotahome-scraper.md - **Developed by:** [Fatih Tahta](https://apify.com/fatihtahta) (community) - **Categories:** Real estate, Automation, Agents - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $0.70 / 1,000 property listings This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 ## Spotahome Scraper **Slug:** `fatihtahta/spotahome-scraper` ### Overview Spotahome Scraper collects structured rental listing data from Spotahome, including listing identity, title, description, price, availability, location, property details, booking signals, media references, landlord metadata, and source context. [Spotahome](https://www.spotahome.com) is a furnished rental marketplace where public listing data is useful for understanding rental supply, pricing, availability, and market composition across supported cities. The actor turns rental search results into repeatable JSON records that can be used in analytics, enrichment, monitoring, and operational reporting workflows. It is designed for automated, recurring data acquisition where consistent inputs and normalized outputs are important. Results reflect the publicly available data returned for the selected search scope at run time. ### Why Use This Actor - **Market research and analytics teams:** collect normalized rental listing data for market intelligence, price analysis, availability tracking, and location-level reporting. - **Product and content teams:** enrich internal rental catalogs, city pages, comparison experiences, or content workflows with current public listing attributes. - **Developers and data engineering teams:** feed structured extraction output into downstream systems, warehouses, search indexes, and scheduled data acquisition pipelines. - **Lead generation and enrichment teams:** identify relevant rental properties, landlords, property formats, and public listing attributes for enrichment pipelines. - **Monitoring and competitive tracking teams:** track supply, pricing, listing quality signals, and availability changes across target rental markets. ### Common Use Cases - **Market intelligence:** monitor rental supply, monthly pricing, availability dates, location coverage, property mix, and listing quality indicators. - **Lead generation:** build targeted lists of public rental listings and associated landlord identifiers for follow-up workflows. - **Competitive monitoring:** compare listing volume, pricing, amenities, property types, and trust signals across cities or rental segments. - **Catalog and directory building:** populate internal real estate databases with structured public listing records. - **Data enrichment:** add current public rental attributes to CRM, BI, analytics, or inventory datasets. - **Recurring reporting:** schedule periodic runs for dashboards, alerts, trend analysis, and operational reporting. ### Quick Start 1. Enter the `location` you want to search, such as a city, neighborhood, or rental market supported by Spotahome. 2. Optionally add filters such as `min_price`, `max_price`, `property_type`, `amenities`, `suitability`, included bills, dates, or listing quality signals. 3. Set a small `limit` for the first validation run, such as 25 or 50 records. 4. Run the actor in Apify Console. 5. Inspect the first dataset records to confirm that the fields, identifiers, and nested objects match your use case. 6. Increase the `limit`, adjust filters, or schedule recurring runs once the output is verified. ### Input Parameters The actor requires one search `location`; all other fields are optional filters, sorting controls, or collection limits. | Parameter | Type | Description | Default | | --- | --- | --- | --- | | `location` | string | Required search location, such as a city, neighborhood, or supported rental market. Example: `Barcelona`. | – | | `min_price` | integer | Minimum monthly rental price to save. Use EUR as the practical pricing unit for Spotahome listings. | – | | `max_price` | integer | Maximum monthly rental price to save. Use EUR as the practical pricing unit for Spotahome listings. | – | | `bed_type` | array of strings | Bed arrangements to include. Allowed values: `single_bed`, `double_bed`, `twin_beds`. Leave empty to include all bed setups. | – | | `property_type` | array of strings | Rental formats to include. Allowed values: `apartments`, `studios`, `rooms_shared`, `student_residences`. Leave empty to include all supported property types. | – | | `amenities` | array of strings | Amenities that matching listings should include. Allowed values: `air_conditioning`, `heating`, `washing_machine`, `oven`, `dishwasher`, `with_desk`, `balcony`, `elevator`. | – | | `suitability` | array of strings | Renter profile or household suitability signals. Allowed values: `couples`, `pets`, `students`, `professionals`. | – | | `included_bills` | array of strings | Bills or services that should be included in the rental cost. Allowed values: `wifi`, `electricity`, `water`, `gas`. | – | | `checkin_date_day` | string | Desired move-in date. Accepted formats: `YYYY-MM-DD` or `DD/MM/YYYY`. Used with `checkout_date_day`. | – | | `checkout_date_day` | string | Desired move-out date. Applies when `checkin_date_day` is also set. Accepted formats follow the same date style as check-in. | – | | `availability_variance` | string | Optional date flexibility around both check-in and check-out dates. Allowed values: `1_week`, `2_week`, `3_week`. Ignored unless both dates are set. | – | | `sort_by` | string | Result ordering before records are saved. Allowed values: `best_match`, `lowest_price`, `newest`. | `best_match` | | `private_bathroom` | boolean | Only save listings that indicate a private bathroom. | `false` | | `spotahome_checked` | boolean | Only save listings marked as checked by Spotahome. | `false` | | `no_deposit` | boolean | Only save listings that do not require a security deposit. | `false` | | `limit` | integer | Maximum number of listings to save for the run. Leave empty to collect as many matching listings as available within the run scope. | – | ### Choosing Inputs Start with a clear `location`, because it defines the rental market and the overall result scope. Use price, property type, bed type, amenity, suitability, included bill, bathroom, deposit, and Spotahome-checked filters when you need a targeted dataset; leave optional filters empty when the goal is broader discovery. Availability dates should be supplied as a pair: set both `checkin_date_day` and `checkout_date_day`, then add `availability_variance` only when date flexibility matters. Use `sort_by` to align collection with your workflow, such as best-match discovery, lowest-price review, or recently listed monitoring. Begin with a small `limit` to validate the output shape, then increase it once the dataset matches your expectations. ### Example Inputs #### Broad Discovery In Barcelona ```json { "location": "Barcelona", "property_type": ["rooms_shared"], "sort_by": "best_match", "limit": 50 } ```` #### Budget-Conscious Apartment Search ```json { "location": "Madrid", "min_price": 700, "max_price": 1400, "property_type": ["apartments", "studios"], "amenities": ["washing_machine", "heating"], "sort_by": "lowest_price", "limit": 75 } ``` #### Student-Friendly Availability Search ```json { "location": "Valencia", "property_type": ["rooms_shared", "student_residences"], "suitability": ["students"], "included_bills": ["wifi", "water"], "checkin_date_day": "2026-09-01", "checkout_date_day": "2027-01-31", "availability_variance": "2_week", "limit": 100 } ``` ### Output #### Output Destination The actor writes results to an Apify dataset as JSON records. The dataset is designed for direct consumption by analytics tools, ETL pipelines, and downstream APIs with minimal post-processing. When multiple entity types or record shapes exist, this README documents each shape separately based on the provided Example Output. The provided output contains one primary record shape: a Spotahome rental listing. #### Record Envelope And Stable Identifiers Each record represents one public Spotahome rental listing with top-level listing identity and nested objects for pricing, availability, location, property details, booking signals, media, landlord information, attributes, and source context. The recommended idempotency key is `listing_id`; if your system requires a URL-backed key, use `url` as a secondary stable identifier. For repeated runs, use `listing_id` to deduplicate records, upsert existing listings, and preserve historical changes in pricing, availability, and listing metadata. Stable identifiers make records easier to merge, deduplicate, and sync across warehouses, CRMs, search indexes, and monitoring systems. `source_context.fingerprint` is also included as a run-level record fingerprint that can help compare saved records across repeated collections. #### Examples ##### Example: Spotahome Rental Listing ```json { "listing_id": "1289069", "url": "https://www.spotahome.com/barcelona/for-rent:rooms/1289069", "title": "Rooms for rent in 7-bedroom apartment in Barcelona", "description": "Looking for the ideal place to stay in the vibrant El Gotic area of Barcelona? Discover this fully furnished room in a shared seven-bedroom apartment, equipped with essential features such as an equipped kitchen, balcony, washing machine, and oven. The property has been personally checked by Spotahome, ensuring quality and trust for your next residence. All utilities including electricity, water, gas, and WiFi are covered for convenience. Unfortunately, pets and overnight guests are not allowed, and smoking is prohibited. Situated in El Gotic, one of Barcelona's most historically rich neighborhoods, you'll enjoy proximity to various landmarks and attractions. The apartment is located within walking distance from numerous points of interest, such as the famous Barshelona and Plaça de La Mercè. Additional nearby attractions include La Gamba and Barcelona Segway Glides, among others, making this property ideal for immersing yourself in the city's lively cultural scene.", "property_type": "room_shared", "pricing": { "display_price": 675, "minimum_price": 675, "currency": "EUR", "bills_included": "all", "offers": [ { "discount_type": "percentage", "discount_value": 3 }, { "discount_type": "percentage", "discount_value": 7 } ] }, "availability": { "first_available_date": "2026-08-31T00:00:00+00:00" }, "location": { "street": "Carrer Ample", "postal_code": "08002", "city": "Barcelona", "market_city": "barcelona", "coordinates": { "longitude": 2.180184226738277, "latitude": 41.37974249565961 }, "address_coordinates": { "longitude": 2.18039, "latitude": 41.37978 } }, "property": { "area_sqm": 95, "room_area_sqm": 0, "bathrooms": 2, "bedrooms": 7 }, "booking": { "spotahome_checked": true, "instant_booking": false, "no_security_deposit": false, "deposit_protection": false, "permanent_contract_allowed": false, "best_choice": false, "favorite": false }, "media": { "main_photo_url": "https://photos.spotahome.com/smw_768/d506ca2e374b6572ae27031745e5bbdb430ed1738015e1dee1963a1e.jpg", "photo_ids": [ "d506ca2e374b6572ae27031745e5bbdb430ed1738015e1dee1963a1e", "a0d323c7ee2baf3105fe740287e6b0337de05cbdf09cf0010a99d04e", "3b911d027ecefbebfcf455334ffc6fb989261e51c3deba8d66ac55f9", "61e8304816f16180265c8e026b1a3c62c0c4ad09fd6b424d4291fb2b", "2e5f4b9ccfd8d8bd4ffcb406c638dc861aec5586ac88b0b82bd3549c" ], "other_property_photo_ids": [ "608eb3bb7062da02b9459dddb046536ea4add2bc0ea536ad36962033", "b62d1eb6a1019d7b95d575b778499586b2906a6d271fee928609dd40", "5fc3f5633388a443d081ed56b34f9cfd0d181ddd3e5a51302844381d", "a06f05552140f0cbf185d5bb681aadc7839d14e66df4c611a543a4d9", "a7e434dbbdbf3e26a7bcb0ce8131d96a92fef630443a61bd7a0f7474", "6968106c3fdf78ee5844d3086107471d235b41f63e5b366d01f1fc89", "bb0fe0f3e0670b20fd1292435d25365671a4f8d44c8994b142c1028e", "38a386f620f5006a5f33d0bdbbd9b79aaafa92f5d8f4378f66b199d5", "a1a86a91bdb9d0244a9aa421edfd70274d64fe7422becfa92a716327", "46103ed8165c11e27fd1ce1cff1d01c059a095b7784111de44f6800a", "28f7f14746bbcd22ef39e4a21e69f1d18ebd2a698c3d8f6618295111", "3bac35b4b0114bb63e9e8f68b575cf618a1fdce60894ea0830d039f4", "bd6760923c3ee7a63d7589638c1e762a4f385a66eb56fa4cdf1afc95", "68650a0fca8c7c83dbc4837697b052e2c25b2bf97b75fe33e8e4e56a", "89ea46245dd105723bcc77b1e115538ec43e3f8f16ac33fba88a7d48", "7bebf702d727815fb6ceeb9124df53f33a2dfc94e077fa493b6099ff", "f9e7d4a3a5e608fed2000cc31b02fa04ba98aafaec9e87894b08f12f", "2a4a4e5b2466f83614424ebe8b2a7a978d51dd4fecf6deb2864da9de", "b0fbcecfd6c54972ce405bca6bccc01806e9b677bc2cf68bc69b2e81", "4b8ed4e2ccbf0845f0171989f9b7bad973a721dab8d22b72497a160c", "c01353c7b448e5f66fe5212e1b131a236d2196db18d949aa4cbb6247", "306555fd98369eb5ec29553997f5c77d94d04bee0799aebc71ad4277", "a7d9cf59fdb6b260e640080161b2ef24c5a7328bc0fb7fdca089e933", "50e36716d1cbe48a9bb6782ffc673bd5f4568b386839fd0ac06a78df", "48f35ee28e042475aa5ed916a8b42a37f41dff870578c0f6cc7859b6", "1855c7677e6ee4f8f8e19f8c9769aaf3fededb57f399e44abccbc698", "cce68e9aec424266aeed2b4c5be35638849f24c120386c69dd4d17ac", "e2c913dac361ba3530f5d911672e1c7061488ad7c04d30dd975677c8", "9c0dbc9becd2371f6007e9095c3f60b707b74e9a70ee93db8074bf66", "fef384959fd23dac794058ef4be0b98660f25652f8e7be33d79111dc", "7441cf8d47c1132233675c672542e6d0fd8899a44964f611ab569159", "312453c408677d7c30e249d974a9324e00ba360560f9df609b8ecb74", "f4b5a61f3a001456f5352849a11deb630bf1fd6f40e754567033a24b", "6031efb62f69d2bb1f48b8dbd5edc8cf399b0f5719096d98deca660d", "827b9cba387765cef470c46edde02cecc1f8beb7cd972bb3e5214fdb", "dd6cadace6079e8348a11ef237a577e74c0821b59f5c0cdf36695775", "dd9956c35a8d8f6976b6fda993eef292351b0ee1a6996697fd33f300", "377fe7c74afda3bf61d4d8f7cd2f08c0915874b7c8ba7f2d473b7fde", "0c4d4d89a403a99102bdc20103882052adbc2910868cdbdcca678a6f", "549bbd58f4685c81a1a7c82694b707553b1cbccb26ed73015baeb3b3", "6b4ca4c8b81a0c1e70ebd0853d0a778d46782ef19827b25224dded10" ] }, "landlord": { "landlord_id": "70d4b9c8-7cfe-4c95-9ab8-534ff393b5f2", "scoring": { "score": 380, "total_bookings_closed": 665 } }, "attributes": { "feature_flags": [ "Any", "Professionals", "Students", "Furnished", "Exterior", "Equipped kitchen", "Balcony or terrace", "Oven", "Desk", "Chest of drawers", "Shelving", "Independent key", "Built-in wardrobe", "Window", "Electricity", "Water", "Gas", "Wifi", "Double Bed" ], "unmapped_feature_flags": { "3024": true }, "search_marker": { "instant_booking": false, "minimum_price": 675 } }, "source_context": { "total_markers": 4608, "source_url": "https://www.spotahome.com/s/barcelona--spain/for-rent:rooms", "seed_id": "8307012beefb3073198e", "seed_type": "search", "seed_value": "Barcelona", "page_index": 1, "fingerprint": "e37d0fc261d810d66c12" } } ``` ### Field Reference #### Spotahome Rental Listing **listing\_id** *(string, required)*: Stable Spotahome listing identifier. **url** *(string, required)*: Public Spotahome listing URL. **title** *(string, optional)*: Listing title. **description** *(string, optional)*: Public listing description. **property\_type** *(string, optional)*: Rental format, such as `room_shared`. **pricing.display\_price** *(number, optional)*: Displayed monthly rental price. **pricing.minimum\_price** *(number, optional)*: Minimum monthly rental price. **pricing.currency** *(string, optional)*: Price currency, such as `EUR`. **pricing.bills\_included** *(string, optional)*: Included-bills indicator, such as `all`. **pricing.offers** *(array, optional)*: Available discount or promotional offers. **pricing.offers\[].discount\_type** *(string, optional)*: Offer type, such as `percentage`. **pricing.offers\[].discount\_value** *(number, optional)*: Offer value. **availability.first\_available\_date** *(string, optional)*: First available rental date in ISO 8601 format. **location.street** *(string, optional)*: Public street-level location. **location.postal\_code** *(string, optional)*: Postal code. **location.city** *(string, optional)*: City name. **location.market\_city** *(string, optional)*: Normalized market city value. **location.coordinates.longitude** *(number, optional)*: Listing longitude. **location.coordinates.latitude** *(number, optional)*: Listing latitude. **location.address\_coordinates.longitude** *(number, optional)*: Address-level longitude when available. **location.address\_coordinates.latitude** *(number, optional)*: Address-level latitude when available. **property.area\_sqm** *(number, optional)*: Total property area in square meters. **property.room\_area\_sqm** *(number, optional)*: Room area in square meters when provided. **property.bathrooms** *(number, optional)*: Number of bathrooms. **property.bedrooms** *(number, optional)*: Number of bedrooms. **booking.spotahome\_checked** *(boolean, optional)*: Whether the listing is marked as checked by Spotahome. **booking.instant\_booking** *(boolean, optional)*: Whether instant booking is indicated. **booking.no\_security\_deposit** *(boolean, optional)*: Whether no security deposit is indicated. **booking.deposit\_protection** *(boolean, optional)*: Whether deposit protection is indicated. **booking.permanent\_contract\_allowed** *(boolean, optional)*: Whether a permanent contract is indicated as allowed. **booking.best\_choice** *(boolean, optional)*: Whether the listing is marked as a best choice. **booking.favorite** *(boolean, optional)*: Whether the listing is marked as a favorite in the source context. **media.main\_photo\_url** *(string, optional)*: Main public photo URL. **media.photo\_ids** *(array, optional)*: Photo identifiers associated with the listing. **media.other\_property\_photo\_ids** *(array, optional)*: Additional property-level photo identifiers. **landlord.landlord\_id** *(string, optional)*: Public landlord identifier when available. **landlord.scoring.score** *(number, optional)*: Landlord score value when available. **landlord.scoring.total\_bookings\_closed** *(number, optional)*: Total closed bookings associated with the landlord score. **attributes.feature\_flags** *(array, optional)*: Public listing features, amenities, suitability signals, and bill indicators. **attributes.unmapped\_feature\_flags** *(object, optional)*: Additional feature flags not mapped to a descriptive label. **attributes.search\_marker.instant\_booking** *(boolean, optional)*: Instant-booking signal from the search record. **attributes.search\_marker.minimum\_price** *(number, optional)*: Minimum price from the search record. **source\_context.total\_markers** *(number, optional)*: Total matching markers reported for the source search context. **source\_context.source\_url** *(string, optional)*: Public source search URL associated with the record. **source\_context.seed\_id** *(string, optional)*: Stable identifier for the input seed used in the run. **source\_context.seed\_type** *(string, optional)*: Seed type, such as `search`. **source\_context.seed\_value** *(string, optional)*: Seed value supplied for collection, such as the input location. **source\_context.page\_index** *(number, optional)*: Result page index associated with the saved record. **source\_context.fingerprint** *(string, optional)*: Record fingerprint useful for repeated-run comparison and secondary deduplication. ### Data Quality, Guarantees, And Handling - **Structured records:** results are normalized into predictable JSON objects for downstream use. - **Best-effort extraction:** fields may vary by region, session, availability, listing type, or source-side presentation changes. - **Optional fields:** null-check optional values in downstream code, especially media, landlord, availability, and detailed property attributes. - **Deduplication:** use `listing_id` as the primary stable key; `url` and `source_context.fingerprint` can support validation or secondary matching. - **Freshness:** results reflect the publicly available data at run time. - **Repeated runs:** use the recommended idempotency key when syncing data into warehouses, CRMs, search indexes, or monitoring systems. ### Tips For Best Results - Start with a small `limit` to validate the output shape before scaling up. - Use one location or rental segment per run when you need cleaner reporting and easier comparison. - Leave optional filters empty when the goal is broad discovery. - Add filters gradually to understand how each field changes coverage. - Set both availability dates together when move-in and move-out timing matters. - Use `sort_by: "newest"` for recently listed monitoring and `sort_by: "lowest_price"` for budget analysis. - Store results using `listing_id` to deduplicate repeated runs over time. ### How To Run On Apify 1. Open the actor in Apify Console. 2. Configure the available input fields for the target location and rental scope. 3. Set the maximum number of outputs to collect with `limit`. 4. Click **Start** and wait for the run to finish. 5. Open the dataset preview and inspect the first records. 6. Download results in JSON, CSV, Excel, or other supported formats. ### Scheduling & Automation #### Scheduling ##### Automated Data Collection Use Apify schedules to run the actor periodically and keep rental datasets fresh for monitoring, reporting, and enrichment workflows. - Navigate to **Schedules** in Apify Console - Create a new schedule, such as daily, weekly, or custom cron - Configure input parameters - Enable notifications for run completion - Add webhooks for automated processing #### Integration Options - **BI dashboards:** monitor rental pricing, availability, property mix, and location coverage over time. - **Data warehouses:** load normalized listing records into historical tables for trend analysis and reporting. - **Webhooks:** trigger validation, notification, or ingestion workflows after each completed run. - **CRM enrichment:** sync public listing, landlord, location, and property attributes into account or lead records. - **Google Sheets or Airtable:** review smaller rental datasets, validate segments, and share operational extracts with non-technical teams. - **ETL and data enrichment pipelines:** combine Spotahome listing data with internal market, geography, or inventory datasets. ### Export Formats And Downstream Use Apify datasets can be exported from the platform or consumed by downstream systems for reporting, analysis, and operational workflows. - **JSON:** for APIs, applications, and data pipelines - **CSV or Excel:** for spreadsheet workflows and manual review - **API access:** for automated ingestion into internal systems - **BI and warehouses:** for reporting, dashboards, and historical analysis ### Performance Estimated run times: - **Small runs (< 1,000 outputs):** ~3–5 minutes - **Medium runs (1,000–5,000 outputs):** ~5–15 minutes - **Large runs (5,000+ outputs):** ~15–30 minutes Execution time varies based on filters, result volume, and how much information is returned per record. Highly filtered runs can finish faster, while broad discovery or detail-rich records may take longer. ### Limitations - Availability depends on what [Spotahome](https://www.spotahome.com) publicly exposes at run time. - Some optional fields may be missing on sparse listings or in specific markets. - Very broad searches may take longer or require higher `limit` values. - Source-side changes can affect field availability, naming, or completeness. - Regional, account, or availability differences may change visible results. - Date and price filters depend on matching public listings being available for the selected location. ### Troubleshooting - **No results returned:** check filter combinations, location spelling, date range, and whether Spotahome has matching public listings for the selected market. - **Fewer results than expected:** broaden filters, raise `limit`, or verify that the target location contains enough matching public records. - **Some fields are empty:** optional fields depend on what each listing publicly provides. - **Run takes longer than expected:** reduce scope, lower `limit` for validation, or split broad collection into smaller location or property-type segments. - **Output changed:** compare the current output with the field reference and include a small sample if support is needed. ### FAQ #### What data does this actor collect? It collects public Spotahome rental listing records, including listing identity, URL, title, description, property type, pricing, availability, location, property details, booking signals, media references, landlord metadata, attributes, and source context. #### Can I filter by location, category, date, price, or other criteria? Yes. The actor requires `location` and supports filters for monthly price, bed type, property type, amenities, suitability, included bills, availability dates, bathroom requirements, Spotahome-checked status, deposit requirements, sorting, and result limit. #### Why did I receive fewer results than my limit? The `limit` is a maximum, not a guarantee. You may receive fewer records when the selected location and filters return fewer matching public listings at run time. #### Can I schedule recurring runs? Yes. Use Apify schedules to run the actor daily, weekly, or on a custom cadence for monitoring, reporting, and enrichment workflows. #### How do I avoid duplicates across runs? Use `listing_id` as the primary idempotency key when storing or syncing records. `url` and `source_context.fingerprint` can help with secondary validation. #### Can I export the data to CSV, Excel, or JSON? Yes. Apify datasets support exports in JSON, CSV, Excel, and other platform-supported formats. #### Does this actor collect private data? No. The actor is intended to collect publicly available Spotahome listing information. Users are responsible for using the data lawfully and in accordance with applicable requirements. #### What should I include when reporting an issue? Include the input used, the run ID, expected versus actual behavior, and a small output sample if it helps illustrate the issue. Redact any sensitive internal notes before sharing. ### Compliance & Ethics #### Responsible Data Collection This actor collects publicly available rental listing information from [Spotahome](https://www.spotahome.com) for legitimate business purposes, including: - **Real estate** research and market analysis - **Rental pricing and availability monitoring** - **Data enrichment for operational reporting and analytics** This section is informational and not legal advice. Users are responsible for ensuring that their use of collected data complies with applicable laws, regulations, and platform terms. #### Best Practices - Use collected data in accordance with applicable laws, regulations, and the target site's terms - Respect individual privacy and personal information - Use data responsibly and avoid disruptive or excessive collection - Do not use this actor for spamming, harassment, or other harmful purposes - Follow relevant data protection requirements where applicable, such as GDPR and CCPA ### Support For help, use the actor page or Issues section. Include the input used, with sensitive values redacted; the run ID; expected versus actual behavior; and a small output sample when useful. Avoid sharing private credentials, personal notes, or unrelated internal data. # Actor input Schema ## `location` (type: `string`): Enter one search location, such as Barcelona, Madrid, Valencia, or a supported local market. The actor uses this location as the starting point for collection. ## `min_price` (type: `integer`): Only save listings with a monthly price at or above this amount. ## `max_price` (type: `integer`): Only save listings with a monthly price at or below this amount. ## `property_type` (type: `array`): Select one or more property types to include. Leave empty to keep all supported property types in scope. ## `bed_type` (type: `array`): Only save listings that match one or more selected bed arrangements. Leave empty to keep all bed setups in scope. ## `private_bathroom` (type: `boolean`): Only save listings that indicate a private bathroom. ## `spotahome_checked` (type: `boolean`): Only save listings marked as checked by Spotahome. ## `no_deposit` (type: `boolean`): Only save listings that do not require a security deposit. ## `amenities` (type: `array`): Only save listings that include the selected amenities. Selecting more amenities makes the search more targeted. ## `included_bills` (type: `array`): Only save listings where the selected bills are included. Leave empty to include listings regardless of bill coverage. ## `suitability` (type: `array`): Only save listings that match the selected suitability signals. Leave empty if renter profile is not part of your criteria. ## `checkin_date_day` (type: `string`): Enter the desired move-in date. Accepted formats: YYYY-MM-DD or DD/MM/YYYY. ## `checkout_date_day` (type: `string`): Enter the desired move-out date. This field only applies when a check-in date is also set. ## `availability_variance` (type: `string`): Optionally broaden the search around both dates. This setting is ignored unless both check-in and check-out dates are set. ## `sort_by` (type: `string`): Order matching listings by best match, lowest price, or newest listed before records are saved. ## `limit` (type: `integer`): Set the maximum number of listings to save for this run. Leave empty to collect as many matching listings as available within the run scope. ## Actor input object example ```json { "location": "Barcelona", "private_bathroom": false, "spotahome_checked": false, "no_deposit": false, "sort_by": "best_match", "limit": 100 } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "location": "Barcelona", "limit": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("fatihtahta/spotahome-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "location": "Barcelona", "limit": 100, } # Run the Actor and wait for it to finish run = client.actor("fatihtahta/spotahome-scraper").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 '{ "location": "Barcelona", "limit": 100 }' | apify call fatihtahta/spotahome-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=fatihtahta/spotahome-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "SpotAHome Scraper | Fast & Reliable", "description": "Extract Spotahome rental listings at scale with rich property detail, availability data, landlord signals, media, booking context, and flexible market filters. Built for enterprise-grade rental intelligence, market monitoring, and automated analytics pipelines.", "version": "0.0", "x-build-id": "pUagL2oZiCoV6hG0Z" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fatihtahta~spotahome-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fatihtahta-spotahome-scraper", "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/fatihtahta~spotahome-scraper/runs": { "post": { "operationId": "runs-sync-fatihtahta-spotahome-scraper", "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/fatihtahta~spotahome-scraper/run-sync": { "post": { "operationId": "run-sync-fatihtahta-spotahome-scraper", "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", "required": [ "location" ], "properties": { "location": { "title": "Choose Search Location", "type": "string", "description": "Enter one search location, such as Barcelona, Madrid, Valencia, or a supported local market. The actor uses this location as the starting point for collection." }, "min_price": { "title": "Set Minimum Monthly Price", "minimum": 0, "type": "integer", "description": "Only save listings with a monthly price at or above this amount." }, "max_price": { "title": "Set Maximum Monthly Price", "minimum": 0, "type": "integer", "description": "Only save listings with a monthly price at or below this amount." }, "property_type": { "title": "Choose Property Types", "uniqueItems": true, "type": "array", "description": "Select one or more property types to include. Leave empty to keep all supported property types in scope.", "items": { "type": "string", "enum": [ "apartments", "studios", "rooms_shared", "student_residences" ], "enumTitles": [ "Apartments", "Studios", "Rooms in shared apartment", "Student residences" ] } }, "bed_type": { "title": "Choose Bed Types", "uniqueItems": true, "type": "array", "description": "Only save listings that match one or more selected bed arrangements. Leave empty to keep all bed setups in scope.", "items": { "type": "string", "enum": [ "single_bed", "double_bed", "twin_beds" ], "enumTitles": [ "Single bed", "Double bed", "Twin beds" ] } }, "private_bathroom": { "title": "Require Private Bathroom", "type": "boolean", "description": "Only save listings that indicate a private bathroom.", "default": false }, "spotahome_checked": { "title": "Require Spotahome Checked Listings", "type": "boolean", "description": "Only save listings marked as checked by Spotahome.", "default": false }, "no_deposit": { "title": "Require No Deposit", "type": "boolean", "description": "Only save listings that do not require a security deposit.", "default": false }, "amenities": { "title": "Choose Amenities", "uniqueItems": true, "type": "array", "description": "Only save listings that include the selected amenities. Selecting more amenities makes the search more targeted.", "items": { "type": "string", "enum": [ "air_conditioning", "heating", "washing_machine", "oven", "dishwasher", "with_desk", "balcony", "elevator" ], "enumTitles": [ "Air conditioning", "Heating", "Washing machine", "Oven", "Dishwasher", "Desk", "Balcony", "Elevator" ] } }, "included_bills": { "title": "Choose Included Bills", "uniqueItems": true, "type": "array", "description": "Only save listings where the selected bills are included. Leave empty to include listings regardless of bill coverage.", "items": { "type": "string", "enum": [ "wifi", "electricity", "water", "gas" ], "enumTitles": [ "Wi-Fi", "Electricity", "Water", "Gas" ] } }, "suitability": { "title": "Choose Suitability Options", "uniqueItems": true, "type": "array", "description": "Only save listings that match the selected suitability signals. Leave empty if renter profile is not part of your criteria.", "items": { "type": "string", "enum": [ "couples", "pets", "students", "professionals" ], "enumTitles": [ "Couples | suitable for couples", "Pet-friendly | pets allowed", "Students | suitable for students", "Professionals | suitable for professionals" ] } }, "checkin_date_day": { "title": "Set Check-In Date", "type": "string", "description": "Enter the desired move-in date. Accepted formats: YYYY-MM-DD or DD/MM/YYYY." }, "checkout_date_day": { "title": "Set Check-Out Date", "type": "string", "description": "Enter the desired move-out date. This field only applies when a check-in date is also set." }, "availability_variance": { "title": "Choose Date Flexibility", "enum": [ "1_week", "2_week", "3_week" ], "type": "string", "description": "Optionally broaden the search around both dates. This setting is ignored unless both check-in and check-out dates are set." }, "sort_by": { "title": "Choose Sort Order", "enum": [ "best_match", "lowest_price", "newest" ], "type": "string", "description": "Order matching listings by best match, lowest price, or newest listed before records are saved.", "default": "best_match" }, "limit": { "title": "Set Maximum Results", "minimum": 1, "type": "integer", "description": "Set the maximum number of listings to save for this run. Leave empty to collect as many matching listings as available within the run scope." } } }, "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 } } } } } } } } } } ```