# Fotocasa Spain Property Listings Scraper (`datascraperes/fotocasa-property-search-scraper`) Actor

Extract structured Fotocasa property listings across Spain. Filter by location, sale or rent, property type, price, size, rooms and bathrooms, then receive unique listings with prices, photos, agency details and source URLs in your Dataset.

- **URL**: https://apify.com/datascraperes/fotocasa-property-search-scraper.md
- **Developed by:** [DataScraperES](https://apify.com/datascraperes) (community)
- **Categories:** Real estate, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 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.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Fotocasa Spain Property Listings Scraper

Find and export public Fotocasa property listings across Spain. Search by a ready-made Fotocasa results URL or configure a location and filters directly in Apify. Receive clean, deduplicated listings ready for market research, investment analysis, agency workflows, or PropTech products.

### What you can do

- Search homes, commercial premises, garages, offices, storage rooms, land, and buildings.
- Find properties for sale, rent, or shared accommodation.
- Filter by location, price, surface area, rooms, bathrooms, property type, and sort order.
- Use an existing Fotocasa search URL to preserve its public filters, including neighbourhood-level searches.
- Collect up to 1,000 unique listings in a run.
- Export your results as CSV, Excel, JSON, JSONL, XML, RSS, or HTML.

### How to use

1. Open the **Input** tab.
2. Choose one of these search methods:
   - **Fotocasa search URLs** — recommended when you already have a search page with the exact area and filters you need.
   - **Location** — enter a city, province, region, district, or neighbourhood and choose the operation and property type.
3. Optionally set price, size, rooms, bathrooms, sorting, and the maximum number of listings.
4. Click **Start**. Your unique listings appear in the **Output** tab and can be downloaded in your preferred format.

### Recommended ways to search

#### Search with a Fotocasa URL

This is the best option for a specific neighbourhood or a combination of filters already configured on Fotocasa.

1. Open Fotocasa and set your preferred public filters.
2. Copy the resulting search page URL.
3. Paste it into **Fotocasa search URLs** in the Input tab.
4. Set the maximum number of listings and start the Actor.

#### Search by location and filters

Use this option when you want to start directly in Apify.

For example, search homes for sale in Madrid, set a price range, select the minimum number of rooms, choose the desired sort order, and set the number of listings to collect.

### JSON examples

The Input tab is the easiest way to configure a run. These examples are useful when calling the Actor through the Apify API.

#### Example input

Search homes for sale in Madrid, between €250,000 and €500,000, with at least two rooms:

```json
{
  "locationQuery": "Madrid",
  "locationLevel": "MUNICIPALITY",
  "operation": "buy",
  "propertyType": "homes",
  "minPrice": 250000,
  "maxPrice": 500000,
  "minRooms": 2,
  "sortBy": "latest",
  "maxItems": 100
}
```

#### Example output item

Each result is one property listing. Values vary according to what is publicly available on the listing.

```json
{
  "property_id": 123456789,
  "transaction_type": "SALE",
  "property_type": "HOMES",
  "property_subtype": "FLAT",
  "title": "Flat for sale in Madrid",
  "price": 385000,
  "price_drop": null,
  "surface_m2": 82,
  "rooms": 2,
  "bathrooms": 1,
  "location": {
    "address": "Madrid"
  },
  "coordinates": {
    "latitude": 40.4168,
    "longitude": -3.7038,
    "accuracy": 0
  },
  "description": "Public listing description when available.",
  "agency": {
    "name": "Example agency",
    "id": 12345,
    "reference": null
  },
  "photos": [
    "https://images.fotocasa.es/example-photo.jpg"
  ],
  "source_url": "https://www.fotocasa.es/es/comprar/vivienda/madrid-capital/123456789/d",
  "scraped_from": "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l"
}
```

### Data you receive

Every Dataset item is a unique public property listing. Fields are included when the listing makes them available.

| Field | Description |
| --- | --- |
| `property_id` | Fotocasa listing identifier. |
| `transaction_type` | Sale, rent, or shared accommodation. |
| `property_type` / `property_subtype` | Property category and subtype. |
| `title` | Listing title. |
| `price` / `price_drop` | Advertised price and published price reduction in EUR. |
| `surface_m2` | Advertised surface area in square metres. |
| `rooms` / `bathrooms` | Advertised rooms and bathrooms. |
| `location` / `coordinates` | Public location and coordinates when available. |
| `description` | Public listing description. |
| `agency` | Public advertiser or agency details. |
| `photos` | Public listing photo URLs. |
| `source_url` | Direct public URL of the listing. |
| `scraped_from` | Search URL that returned the listing. |

### Common use cases

#### Market research

Compare advertised prices, property sizes, and supply across cities, districts, or property categories.

#### Investment analysis

Build a current set of comparable listings for a target area and export it to Excel or your analysis workflow.

#### Agency and PropTech workflows

Create structured datasets for internal research, catalog enrichment, market reports, or downstream applications.

#### Property discovery

Collect the current public listings matching a specific budget, location, property type, and number of rooms.

### Results and exports

Results are delivered to the run's Dataset. Open the **Output** or **Storage** tab after the run to browse listings and download them as CSV, Excel, JSON, JSONL, XML, RSS, or HTML. You can also use the Apify API to consume the Dataset from your own application.

### Pricing

Pricing is **$1 per 1,000 delivered listings** ($0.001 per unique listing). A listing is charged only after it has been successfully saved to the Dataset. A minimum charge of $0.03 per run applies, equivalent to 30 listings.

### FAQ

#### Should I use a search URL or a location?

Use a **Fotocasa search URL** when you need exact public filters or a particular neighbourhood. Use **Location** when you want to configure a new search directly in Apify.

#### Are duplicate listings included?

No. The Actor keeps one result per unique listing identifier within a run.

#### Why can some fields be empty?

Fotocasa does not publish every field for every listing. Unavailable values are returned as empty values rather than guessed data.

#### Can I use the results outside Apify?

Yes. Download the Dataset in a supported export format or retrieve it through the Apify API.

#### What happens if fewer listings are available than requested?

The Actor returns the unique public listings available for the search. You only receive records that were successfully added to the Dataset.

### Responsible use

Use public listing data responsibly and ensure your use complies with applicable laws, data-protection requirements, and the source website's terms.

# Actor input Schema

## `searchUrls` (type: `array`):

One or more public Fotocasa search-result URLs. Use this for exact districts or multiple locations.

## `locationSlug` (type: `string`):

Optional Fotocasa URL location segment, e.g. madrid-capital. Ignored when searchUrls is set.

## `locationQuery` (type: `string`):

Optional location text resolved through Fotocasa public suggestions, e.g. Madrid or Valencia.

## `locationLevel` (type: `string`):

Preferred suggestion level when location text is ambiguous.

## `operation` (type: `string`):

Property transaction to search.

## `propertyType` (type: `string`):

Fotocasa property category.

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

Optional minimum advertised price.

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

Optional maximum advertised price.

## `minSurface` (type: `integer`):

Optional minimum advertised surface in square metres.

## `maxSurface` (type: `integer`):

Optional maximum advertised surface in square metres.

## `minRooms` (type: `integer`):

Optional minimum number of rooms.

## `maxRooms` (type: `integer`):

Optional maximum number of rooms.

## `minBathrooms` (type: `integer`):

Optional minimum number of bathrooms.

## `maxBathrooms` (type: `integer`):

Optional maximum number of bathrooms.

## `sortBy` (type: `string`):

Order supplied to Fotocasa search.

## `additionalQueryParameters` (type: `string`):

Optional JSON object written as text, e.g. {"featureIds":"1;2"}. Use it for public Fotocasa search parameters not represented above. Values must be text, numbers, or true/false. Structured fields above take priority.

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

Maximum unique listings in the Dataset. Minimum 30 results keeps the per-result price sustainable. Only successfully pushed unique listings trigger the listing-result event.

## Actor input object example

```json
{
  "searchUrls": [
    "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l?sortType=publicationDate"
  ],
  "locationLevel": "MUNICIPALITY",
  "operation": "buy",
  "propertyType": "homes",
  "sortBy": "rating",
  "maxItems": 30
}
```

# Actor output Schema

## `propertyListings` (type: `string`):

The complete, deduplicated set of property listings produced by this run, displayed with the Property listings dataset view.

# 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 = {
    "searchUrls": [
        "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l?sortType=publicationDate"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datascraperes/fotocasa-property-search-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "searchUrls": ["https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l?sortType=publicationDate"] }

# Run the Actor and wait for it to finish
run = client.actor("datascraperes/fotocasa-property-search-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 '{
  "searchUrls": [
    "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l?sortType=publicationDate"
  ]
}' |
apify call datascraperes/fotocasa-property-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datascraperes/fotocasa-property-search-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/CW1fIOl1J4ehoApbg/builds/OACMLM0z6oexuQY0u/openapi.json