# FincaRaiz Colombia Scraper — Delta Mode + Estrato Filter (`don.eich/fincaraiz-colombia-scraper`) Actor

Extract Colombia real estate listings with price/m², stratum filter (1-6),
WhatsApp flag, and incremental delta to detect new listings and price changes.

- **URL**: https://apify.com/don.eich/fincaraiz-colombia-scraper.md
- **Developed by:** [Erick Bonilla](https://apify.com/don.eich) (community)
- **Categories:** Real estate, Developer tools, Open source
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.60 / 1,000 property result (basic fields)s

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## FincaRaiz Colombia Scraper — Delta Mode & Estrato Filter

**99%+ success rate · Maintained weekly · Delta mode (NEW/UPDATED/REMOVED)**

Extract property listings from fincaraiz.com.co with price-per-m² calculated,
stratum filter (1-6), agent WhatsApp flag, and incremental delta monitoring
to detect new listings and price changes between runs.

***

## FincaRaiz Colombia Scraper — Modo Delta y Filtro de Estrato

Extrae propiedades de fincaraiz.com.co con precio/m² calculado, filtro por
estrato socioeconómico (1-6), flag de WhatsApp del agente, y modo delta
incremental para detectar propiedades nuevas y cambios de precio entre corridas.

***

### Modos de operación

#### searchAndScrape (default)

Busca con los filtros del input y extrae propiedades. Ideal para datasets estáticos,
análisis de mercado, o alimentar un CRM con propiedades recientes.

#### monitorDelta

Compara el inventario actual con la corrida anterior y emite solo las propiedades
que cambiaron: `NEW`, `UPDATED` (precio o fecha de actualización cambió), `REMOVED`.

El estado se persiste en un Named Key-Value Store de Apify entre corridas.
La primera corrida es la línea de base: todas las propiedades se clasifican como `NEW`.

**Casos de uso del modo delta:**

- Alertas de bajada de precio en propiedades monitoreadas
- Feed de propiedades nuevas hacia un CRM (HubSpot, Salesforce) vía webhook
- Tracking semanal de inventario por ciudad y estrato
- Monitoreo de competencia: qué agencias publican más propiedades nuevas

#### scrapeUrls

Recibe una lista de URLs directas de propiedades o páginas de búsqueda de FincaRaiz.
Útil para re-scraping de listas específicas o integración con otras herramientas.

***

### Campos del output

#### Siempre disponibles (~30 campos)

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `listingId` | string | ID numérico interno de FincaRaiz |
| `listingUrl` | string | URL canónica de la propiedad |
| `operationType` | string | `sale` / `rent` / `project` |
| `propertyType` | string | `apartment` / `house` / `lot` / etc. |
| `price` | number | Precio en COP |
| `priceUsd` | number | Precio en USD (conversión de FincaRaiz) |
| `pricePerSqm` | number | Precio por m² en COP (calculado) |
| `pricePerSqmUsd` | number | Precio por m² en USD (calculado) |
| `areaSqm` | number | Área en m² |
| `bedrooms` | number | Habitaciones |
| `bathrooms` | number | Baños |
| `latitude` | number | Latitud GPS |
| `longitude` | number | Longitud GPS |
| `address` | string | Dirección |
| `neighborhood` | string | Barrio |
| `city` | string | Ciudad |
| `department` | string | Departamento |
| `agentName` | string | Nombre del anunciante |
| `thumbnail` | string | URL de imagen principal |
| `listingViews` | number | Visitas al listing |
| `listingInquiries` | number | Consultas recibidas |
| `scrapedAt` | string | Timestamp UTC de extracción |

#### Con `includeDetails: true` (120+ campos adicionales)

| Campo | Descripción |
|-------|-------------|
| `stratum` | Estrato socioeconómico (1-6) |
| `adminFee` | Cuota de administración mensual en COP |
| `adminFeeUsd` | Cuota de administración en USD |
| `totalMonthlyUsd` | Costo mensual total en USD (solo arriendo) |
| `garages` | Número de garajes |
| `floor` | Piso de la unidad |
| `floorsCount` | Total de pisos del edificio |
| `constructionYear` | Año de construcción |
| `constructionState` | `new` / `off_plan` / `under_construction` / `used` |
| `amenities` | Lista de amenidades con grupo y nombre |
| `amenityNames` | Array de nombres de amenidades |
| `images` | URLs de todas las imágenes |
| `imageCount` | Número total de imágenes |
| `agentType` | `inmobiliaria` / `particular` / `constructora` |
| `agentPhone` | Teléfono enmascarado del anunciante |
| `agentHasWhatsapp` | Si el anunciante tiene WhatsApp registrado |
| `hasVideo` | Si tiene video disponible |
| `hasTour3d` | Si tiene tour 3D |
| `financingAvailable` | Si ofrece financiación |
| `barterAvailable` | Si acepta permuta |

#### Solo en modo `monitorDelta`

| Campo | Descripción |
|-------|-------------|
| `deltaStatus` | `NEW` / `UPDATED` / `REMOVED` / `UNCHANGED` |
| `deltaChanges` | Array de `{field, previousValue, currentValue}` para UPDATED |
| `deltaDetectedAt` | Timestamp del cambio detectado |

***

### Precios (Pay per Event)

| Escenario | Costo |
|-----------|-------|
| 100 resultados básicos | ~$0.06 |
| 100 resultados con detalle | ~$0.18 |
| 1,000 resultados básicos | ~$0.60 |
| Run de monitoreo delta | $0.0005 + cambios×$0.0006 |

El precio por resultado básico ($0.0006) es hasta 88% más bajo que otros actores de FincaRaiz.

***

### Configuración del proxy

FincaRaiz no requiere proxy para volúmenes bajos (<5,000 requests/día).
Para runs masivos, activar Apify Proxy con grupos residenciales colombianos:

```json
{
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "CO"
  }
}
```

***

### Modo delta — Primera corrida

La primera corrida de `monitorDelta` no tiene snapshot previo.
Todas las propiedades se clasifican como `NEW` y se guarda el snapshot como línea de base.
La corrida siguiente ya puede detectar cambios.

***

### Advertencias de uso

- Los datos de contacto del agente (teléfono, WhatsApp) son públicos en el sitio.
  El uso de esos datos es responsabilidad del usuario final.
- El modo delta sin filtros de ciudad puede generar snapshots de >5 MB.
  Se recomienda filtrar por ciudad y/o tipo de propiedad.
- El `__NEXT_DATA__` de Next.js puede cambiar su estructura con deploys del sitio.
  Si ocurre, el actor retorna los campos básicos de la Capa A con un warning en el log,
  sin crashear. Un test de regresión horario detecta cambios de estructura.

# Actor input Schema

## `mode` (type: `string`):

searchAndScrape: busca con filtros y extrae propiedades. monitorDelta: compara con corrida anterior y emite solo NEW/UPDATED/REMOVED. scrapeUrls: scrapes URLs específicas provistas.

## `operationType` (type: `string`):

Tipo de operación a filtrar.

## `propertyTypes` (type: `array`):

Tipos de inmueble a incluir. Dejar vacío para todos.

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

Lista de slugs de ciudad (ej: bogota-dc, medellin). Dejar vacío para todo el país. Usar el slug que aparece en la URL de FincaRaiz.

## `stratum` (type: `array`):

Filtro por estrato socioeconómico (1-6). Múltiple selección. Dejar vacío para todos. Se traduce a ?stratum\[]=N en la URL de búsqueda.

## `priceMin` (type: `integer`):

Precio mínimo en COP (pesos colombianos). Ej: 200000000 para $200M COP.

## `priceMax` (type: `integer`):

Precio máximo en COP. Ej: 600000000 para $600M COP.

## `bedroomsMin` (type: `integer`):

Número mínimo de habitaciones (dormitorios). Se mapea al path filter de FincaRaiz (ej: /2-o-mas-habitaciones).

## `areaMin` (type: `integer`):

Área mínima en metros cuadrados.

## `areaMax` (type: `integer`):

Área máxima en metros cuadrados.

## `constructionState` (type: `string`):

Estado de la construcción. Se mapea al path filter de FincaRaiz.

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

Solo en modo scrapeUrls: lista de URLs de FincaRaiz (propiedades individuales o páginas de búsqueda). En modos searchAndScrape y monitorDelta este campo es ignorado.

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

Número máximo de propiedades a retornar. El actor para cuando llega a este límite. No tiene efecto en modo monitorDelta (emite todos los cambios detectados).

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

Si es true, visita la página de cada propiedad para obtener campos completos: estrato, cuota de administración, amenidades, ficha técnica, todas las fotos, datos del anunciante incluyendo WhatsApp. Aumenta el tiempo de ejecución y el costo. Si es false, retorna solo los campos disponibles en el listing de búsqueda (~30 campos).

## `sectionAdvanced` (type: `boolean`):

Proxy, concurrencia, modo delta y configuración de almacenamiento.

## `deltaEmitFilter` (type: `string`):

Solo en modo monitorDelta: qué tipos de registros emitir al dataset. 'changes' es el default: emite todo lo que cambió, omite UNCHANGED. Usar 'all' para exportar snapshot completo con status.

## `deltaStoreId` (type: `string`):

Solo en modo monitorDelta: ID o nombre del named Key-Value Store donde persiste el estado entre corridas. Por defecto el actor genera un nombre a partir de los parámetros de búsqueda (ej: FINCARAIZ-DELTA-venta-apartamentos-bogota-dc). Especificar manualmente si querés controlar qué store se usa.

## `proxyConfiguration` (type: `object`):

Configuración de proxy. FincaRaiz no requiere proxy para volúmenes bajos. Para runs masivos (>10k requests/día) activar Apify Proxy con grupos residenciales colombianos.

## `maxConcurrency` (type: `integer`):

Requests concurrentes máximos. El default de 6 es seguro para evitar rate limiting. No aumentar por encima de 10 sin proxy residencial.

## `requestDelayMs` (type: `integer`):

Pausa en milisegundos entre requests al mismo dominio. Default 500ms es suficiente con maxConcurrency=6.

## Actor input object example

```json
{
  "mode": "searchAndScrape",
  "operationType": "sale",
  "propertyTypes": [],
  "cities": [
    "bogota-dc"
  ],
  "stratum": [],
  "constructionState": "",
  "startUrls": [
    {
      "url": "https://www.fincaraiz.com.co/venta/apartamentos/bogota-dc/"
    }
  ],
  "maxItems": 20,
  "includeDetails": false,
  "sectionAdvanced": false,
  "deltaEmitFilter": "changes",
  "deltaStoreId": "",
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "maxConcurrency": 6,
  "requestDelayMs": 500
}
```

# 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 = {
    "cities": [
        "bogota-dc"
    ],
    "startUrls": [
        {
            "url": "https://www.fincaraiz.com.co/venta/apartamentos/bogota-dc/"
        }
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("don.eich/fincaraiz-colombia-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 = {
    "cities": ["bogota-dc"],
    "startUrls": [{ "url": "https://www.fincaraiz.com.co/venta/apartamentos/bogota-dc/" }],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("don.eich/fincaraiz-colombia-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 '{
  "cities": [
    "bogota-dc"
  ],
  "startUrls": [
    {
      "url": "https://www.fincaraiz.com.co/venta/apartamentos/bogota-dc/"
    }
  ],
  "maxItems": 20
}' |
apify call don.eich/fincaraiz-colombia-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=don.eich/fincaraiz-colombia-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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