# Fotocasa Property Listings Scraper (`fetch_cat/fotocasa-property-listings-scraper`) Actor

Extract public Fotocasa Spain property listings, prices, features, locations, media, and advertiser details from search and listing URLs.

- **URL**: https://apify.com/fetch\_cat/fotocasa-property-listings-scraper.md
- **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community)
- **Categories:** Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.19 / 1,000 listing exporteds

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 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 API & Property Listings Scraper

Use this Fotocasa API alternative to export public residential property listings from Fotocasa Spain into structured JSON, CSV, Excel, XML, or RSS. The Fotocasa scraper accepts search-result URLs to collect many homes or individual listing URLs for focused monitoring.

The Actor preserves Fotocasa data such as listing prices, descriptions, locations, coordinates, photos, property characteristics, and public advertiser details in one consistent dataset.

### Who is it for?

This Actor is built for property analysts, real estate teams, investors, researchers, and data engineers who need repeatable Fotocasa exports without manual copy-and-paste.

### Typical use cases

- Build a market dataset for a Spanish city or neighborhood
- Compare sale and rental prices over time
- Monitor newly published listings with scheduled runs
- Feed public property data into spreadsheets, BI tools, databases, or AI agents
- Research inventory, agencies, and property characteristics

### Input example

```json
{
  "startUrls": [
    { "url": "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l" }
  ],
  "maxListings": 100,
  "maxPages": 5,
  "changedSince": "2026-08-01T00:00:00Z"
}
```

### Output example

```json
{
  "id": "190235067",
  "url": "https://www.fotocasa.es/es/comprar/vivienda/madrid-capital/example/190235067/d",
  "title": "Flat in Madrid",
  "description": "Bright home with parking and storage.",
  "operation": "sale",
  "propertyType": "Flat",
  "price": 390000,
  "pricePerSquareMeter": 4875,
  "area": 80,
  "rooms": 2,
  "bathrooms": 1,
  "floor": "3",
  "address": "Madrid, 28022",
  "location": "Madrid",
  "latitude": 40.4241,
  "longitude": -3.6014,
  "features": ["Parking", "Lift"],
  "images": ["https://static.fotocasa.es/images/ads/example"],
  "imageCount": 12,
  "agencyName": "Example agency",
  "agencyPhone": "+34910000000",
  "energyRating": "C",
  "publishedAt": "2026-08-06T10:00:00Z",
  "sourceUrl": "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l",
  "pageNumber": 1,
  "scrapedAt": "2026-08-06T12:00:00Z",
  "changeStatus": "new"
}
```

Fields that Fotocasa does not expose for a particular listing are returned as `null`; arrays remain arrays.

### Input settings

| Field | Type | Description |
|---|---|---|
| `startUrls` | array | One or more public Fotocasa search-result or individual property URLs. |
| `maxListings` | integer | Global maximum number of unique listings to export. |
| `maxPages` | integer | Maximum result pages visited for each search URL. Individual property URLs use one page. |
| `changedSince` | ISO date/time | Optional timestamp used to label recently published records as `new`. |

### Output fields

| Field | Description |
|---|---|
| `id` | Fotocasa listing identifier. |
| `url` | Canonical public property URL. |
| `title` | Listing headline. |
| `description` | Public listing description. |
| `operation` | Sale or rent operation. |
| `propertyType` | Property type or subtype. |
| `price` | Advertised price in euros. |
| `pricePerSquareMeter` | Advertised or available price per square metre. |
| `area` | Property area when available. |
| `rooms` | Number of rooms or bedrooms. |
| `bathrooms` | Number of bathrooms. |
| `floor` | Floor label. |
| `address` | Public address or area label. |
| `location` | Municipality, district, neighborhood, or location label. |
| `latitude`, `longitude` | Public listing coordinates. |
| `features` | Public property features and amenities. |
| `images` | Public image URLs. |
| `imageCount` | Number of images. |
| `agencyName` | Public advertiser or agency name. |
| `agencyPhone` | Public advertiser phone number. |
| `energyRating` | Energy rating when available. |
| `publishedAt` | Publication or update timestamp when available. |
| `sourceUrl` | Input or pagination URL that produced the row. |
| `pageNumber` | Search page number. |
| `scrapedAt` | UTC extraction timestamp. |
| `changeStatus` | `new` when publication metadata is newer than `changedSince`; otherwise `current`. |

### Ready-to-run examples

Open a public example to inspect its input, run it, or reuse it as a task:

- [Export Barcelona Fotocasa Rentals](https://apify.com/fetch_cat/fotocasa-property-listings-scraper/examples/fotocasa-barcelona-homes-for-rent)
- [Export Madrid Fotocasa Homes for Sale](https://apify.com/fetch_cat/fotocasa-property-listings-scraper/examples/fotocasa-madrid-homes-for-sale)

#### Collect Madrid homes for sale

Use a Fotocasa Madrid sale-results URL with `maxListings: 100` and `maxPages: 5`.

#### Monitor rental inventory

Use a rental search URL, set `changedSince` to your prior collection timestamp, and schedule the Actor daily.

#### Export selected properties

Pass multiple individual listing URLs in `startUrls` and set `maxListings` to the number of URLs.

### Pricing

The Actor uses pay-per-event pricing: one start event and one result event per exported listing. Higher Apify plans receive volume discounts. See the live [Pricing tab](https://apify.com/fetch_cat/fotocasa-property-listings-scraper/pricing) for current rates. You can cap spend with `maxListings` and `maxPages`.

### API usage

**cURL**

```bash
curl -X POST "https://api.apify.com/v2/acts/fetch_cat~fotocasa-property-listings-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUrls":[{"url":"https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l"}],"maxListings":20,"maxPages":2}'
```

**JavaScript**

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/fotocasa-property-listings-scraper').call({
  startUrls: [{ url: 'https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l' }],
  maxListings: 20,
  maxPages: 2,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

**Python**

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('fetch_cat/fotocasa-property-listings-scraper').call(run_input={
    'startUrls': [{'url': 'https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l'}],
    'maxListings': 20,
    'maxPages': 2,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
```

### MCP and AI agents

Connect through [Apify MCP](https://mcp.apify.com?tools=fetch_cat/fotocasa-property-listings-scraper), or add it to Claude CLI:

```bash
claude mcp add apify --transport http "https://mcp.apify.com?tools=fetch_cat/fotocasa-property-listings-scraper"
```

Example MCP configuration:

```json
{
  "mcpServers": {
    "apify": {
      "type": "http",
      "url": "https://mcp.apify.com?tools=fetch_cat/fotocasa-property-listings-scraper"
    }
  }
}
```

Try asking these example prompts through MCP:

- “Run the Fotocasa scraper and export 20 Madrid sale listings from this Fotocasa URL.”
- “Use the Fotocasa API Actor to compare prices and floor area in this Fotocasa dataset.”
- “Scrape Fotocasa listings for rent from this Barcelona search URL and return CSV-ready rows.”

Provide an explicit Fotocasa URL and a conservative result limit.

### Tips and limits

- Start with a low `maxListings` value while validating a new URL.
- Use canonical public Fotocasa search or property URLs.
- Results reflect the public page at run time; removed or unavailable listings cannot be exported.
- Some optional fields differ by listing and may be `null`.
- Respect Fotocasa's terms, applicable law, and personal-data requirements. Do not use output for unsolicited contact.

### FAQ

#### How can I export Fotocasa listings?

Supply a public search URL, choose a result limit, and download the resulting dataset in JSON, CSV, Excel, XML, or RSS.

#### Is there a Fotocasa API for property data?

This Actor provides an API-accessible workflow for public Fotocasa property data through Apify clients, REST endpoints, schedules, integrations, and MCP.

#### How can I monitor Fotocasa prices?

Schedule repeat runs for the same search URL and compare the `price`, `pricePerSquareMeter`, and `changeStatus` fields over time.

#### Can I scrape rental and sale listings?

Yes. Supply the corresponding public Fotocasa search or listing URL.

#### Does it paginate search results?

Yes. `maxPages` bounds pages per search, while `maxListings` caps the total unique rows.

#### Can I run it on a schedule?

Yes. Create an Apify schedule and use `changedSince` to classify recently published listings when the source provides publication metadata.

#### Can I use the results through an API or MCP?

Yes. Every run can be started through the Apify API, JavaScript/Python clients, webhooks, integrations, or Apify MCP.

#### Why are some fields null?

Fotocasa does not expose every attribute for every property. The Actor preserves truthful source availability instead of inventing values.

#### Is this an official Fotocasa product?

No. This independent Actor extracts information available on public pages.

### Related actors

- [Idealista Scraper](https://apify.com/fetch_cat/idealista-scraper)
- [Zillow Scraper](https://apify.com/fetch_cat/zillow-scraper)
- [Google Maps Scraper](https://apify.com/fetch_cat/google-maps-scraper)
- [Google Search Results Scraper](https://apify.com/fetch_cat/google-search-results-scraper)
- [Airbnb Scraper](https://apify.com/fetch_cat/airbnb-scraper)

### Support

Open an issue from the Actor's Apify Console page with the failing public URL, expected result, and run ID. Do not include credentials or private personal data.

# Actor input Schema

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

Public Fotocasa search result or individual property URLs.

## `maxListings` (type: `integer`):

Global maximum number of unique property listings to save.

## `maxPages` (type: `integer`):

Maximum number of Fotocasa result pages visited for each search URL.

## `includeDetails` (type: `boolean`):

Reserved compatibility setting. Public fields already present in Fotocasa page data are always exported.

## `changedSince` (type: `string`):

Optional ISO date/time used to classify recently published listings as new.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l"
    }
  ],
  "maxListings": 10,
  "maxPages": 2,
  "includeDetails": false
}
```

# Actor output Schema

## `overview` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l"
        }
    ],
    "maxListings": 10,
    "maxPages": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetch_cat/fotocasa-property-listings-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 = {
    "startUrls": [{ "url": "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l" }],
    "maxListings": 10,
    "maxPages": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("fetch_cat/fotocasa-property-listings-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.fotocasa.es/es/comprar/viviendas/madrid-capital/todas-las-zonas/l"
    }
  ],
  "maxListings": 10,
  "maxPages": 2
}' |
apify call fetch_cat/fotocasa-property-listings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetch_cat/fotocasa-property-listings-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Uu5Ce2tc2O6ZjZrK7/builds/O96j1jO4SAHWRpcV1/openapi.json