# Santander Imóveis API (`brasil-scrapers/santander-imoveis-api`)

API para busca de imóveis do Santander com diversos filtros personalizáveis.

- **URL**: https://beta-securitybyobscurity.apify.com/brasil-scrapers/santander-imoveis-api.md
- **Developed by:** [Brasil Scrapers](https://beta-securitybyobscurity.apify.com/brasil-scrapers) (community)
- **Categories:** Real estate, Automation
- **Stats:** 15 total users, 3 monthly users, 100.0% runs succeeded, 3 bookmarks
- **User rating**: No ratings yet

## Pricing

$20.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.
You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

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

# README

## Santander Imóveis API

API para busca de imóveis do Santander com diversos filtros personalizáveis.

### Filtros Disponíveis

#### Localização

##### Estado (`state`)

- Tipo: String
- Descrição: Estado onde deseja buscar imóveis
- Formato: Sigla do estado (2 letras)
- Valores possíveis: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, PR, RJ, RN, RO, RR, RS, SC, SE, SP, TO
- Valor padrão: "SP"

##### Cidade (`city`)

- Tipo: String
- Descrição: Cidade onde deseja buscar imóveis
- Formato: Nome da cidade
- Valor padrão: "SAO PAULO"
- Exemplo: "PORTO ALEGRE"

#### Características do Imóvel

##### Categoria (`category`)

- Tipo: Array de strings
- Descrição: Categorias de imóveis para busca
- Valores possíveis:
  - `comercial`: Imóveis comerciais
  - `residencial`: Imóveis residenciais
  - `industrial`: Imóveis industriais
  - `rural`: Imóveis rurais

##### Situação (`situation`)

- Tipo: Array de strings
- Descrição: Status de ocupação do imóvel
- Valores possíveis:
  - `ocupado`: Imóvel ocupado
  - `desocupado`: Imóvel vazio
  - `locado`: Imóvel alugado

##### Tipo de Imóvel (`type`)

- Tipo: Array de strings
- Descrição: Tipos específicos de imóveis
- Valores possíveis:
  - `apartamento`: Apartamento
  - `galpao`: Galpão
  - `casa`: Casa
  - `loja`: Loja
  - `casacom`: Casa em condomínio
  - `salacomer`: Sala Comercial
  - `chacara`: Chácara
  - `lote`: Lote
  - `fazenda`: Fazenda
  - `lotecom`: Lote em condomínio

#### Preço

##### Preço Máximo (`maxPrice`)

- Tipo: Inteiro
- Descrição: Valor máximo do imóvel em reais
- Valor mínimo: 0
- Exemplo: 100000 (para R$ 100.000,00)

##### Preço Mínimo (`minPrice`)

- Tipo: Inteiro
- Descrição: Valor mínimo do imóvel em reais
- Valor mínimo: 0
- Exemplo: 50000 (para R$ 50.000,00)

#### Configurações de Scraping

##### Número de Páginas (`numberOfPages`)

- Tipo: Inteiro
- Descrição: Quantidade de páginas que serão extraídas
- Valor padrão: 1
- Valor máximo: 1000

##### Delay entre Domínios (`sameDomainDelaySecs`)

- Tipo: Inteiro
- Descrição: Tempo de espera (em segundos) entre requisições ao mesmo domínio
- Valor padrão: 1

##### Concorrência Mínima (`minConcurrency`)

- Tipo: Inteiro
- Descrição: Número mínimo de páginas para extrair simultaneamente

##### Concorrência Máxima (`maxConcurrency`)

- Tipo: Inteiro
- Descrição: Número máximo de páginas para extrair simultaneamente

#### Configuração de Proxy

##### Proxy (`proxy`)

- Tipo: Objeto
- Descrição: Configurações de proxy para as requisições
- Propriedades:
  - `useApifyProxy`: Boolean (padrão: false)
- Observação: Permite definir um proxy para passar os dados através dele

### Exemplo de Uso

```json
{
  "state": "RS",
  "city": "PORTO ALEGRE",
  "category": ["residencial"],
  "situation": ["desocupado"],
  "type": ["apartamento", "casa"],
  "minPrice": 200000,
  "maxPrice": 500000,
  "numberOfPages": 5,
  "sameDomainDelaySecs": 2,
  "minConcurrency": 1,
  "maxConcurrency": 3,
  "proxy": {
    "useApifyProxy": false
  }
}
```

Este exemplo buscará imóveis residenciais desocupados (apartamentos e casas) em Porto Alegre/RS, com valores entre R$ 200.000 e R$ 500.000, extraindo 5 páginas de resultados.

### Dados de Saída (Output)

A API retorna informações detalhadas sobre cada imóvel encontrado. Abaixo está a descrição de cada campo retornado:

#### Informações Básicas

- `url`: URL completa do anúncio do imóvel
- `codigo`: Código identificador único do imóvel (ex: "Cód. 02.20592")
- `titulo`: Título do anúncio
- `endereco`: Endereço completo do imóvel, incluindo CEP

#### Valores e Condições

- `valorAvaliado`: Valor de avaliação do imóvel
- `valorVenda`: Valor de venda atual
- `desagio`: Percentual de desconto em relação ao valor avaliado
- `dataLeilao`: Data e hora do leilão (quando aplicável)
- `condominio`: Valor do condomínio (quando aplicável)
- `iptu`: Valor do IPTU

#### Status e Documentação

- `ocupacao`: Status de ocupação do imóvel
- `matriculas`: Número da matrícula do imóvel
- `rgi`: Registro Geral do Imóvel
- `inscricaoPrefeitura`: Número de inscrição na prefeitura

#### Áreas

- `areaDescription`: Descrição textual das áreas
- `categorizedAreas`: Objeto contendo áreas específicas:
  - `areaTotal`: Área total
  - `areaTerreno`: Área do terreno
  - `areaPrivativa`: Área privativa
  - `areaUtil`: Área útil
  - `areaConstruida`: Área construída
  - `areaComum`: Área comum

#### Informações do Leilão

- `leiloeiro`: Nome da empresa leiloeira
- `telefone`: Telefone para contato
- `urlLeiloeiro`: Link para o site do leiloeiro
- `condicoesPagamento`: Condições disponíveis para pagamento
- `consideracoes`: Observações importantes sobre o imóvel

#### Mídia

- `imageUrls`: Array com URLs das imagens do imóvel

### Exemplo de Output

```json
{
  "url": "https://www.santanderimoveis.com.br/venda/imovel/casa-exemplo",
  "valorAvaliado": "R$ 1.350.000",
  "valorVenda": "R$ 602.640",
  "desagio": "55%",
  "codigo": "Cód. 02.20592",
  "titulo": "Casa na Estrada Exemplo",
  "endereco": "Estrada Exemplo, 123, Bairro, Cidade - UF",
  "ocupacao": "Ocupado",
  "areaDescription": "1435 m² de área terreno, 275 m² de área construída",
  "leiloeiro": "Exemplo Leilões",
  "condicoesPagamento": "À vista ou Financiamento em até 420 meses"
}
```

### Observações Importantes

- Os valores monetários são retornados no formato brasileiro (R$ X.XXX,XX)
- As datas são retornadas no formato dd/mm/yyyy
- As áreas são retornadas em metros quadrados (m²)
- Alguns campos podem retornar `null` quando a informação não estiver disponível
- As URLs das imagens são temporárias e podem expirar

# Actor input Schema

## `state` (type: `string`):

State to search for

## `city` (type: `string`):

City to search for

## `category` (type: `array`):

category My multiselect field

## `situation` (type: `array`):

situation My multiselect field

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

type My multiselect field

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

Set the maximum price for the properties (e.g., 100000).

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

Set the min price

## `numberOfPages` (type: `integer`):

Select the number of pages to scrape

## `sameDomainDelaySecs` (type: `integer`):

Delay between requests to the same domain

## `minConcurrency` (type: `integer`):

Minimum number of pages to scrape concurrently

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

Maximum number of pages to scrape concurrently

## `proxy` (type: `object`):

Define proxy to pass data through

## Actor input object example

```json
{
  "state": "SP",
  "city": "SAO PAULO",
  "numberOfPages": 1,
  "sameDomainDelaySecs": 1,
  "proxy": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "numberOfPages": 1,
    "proxy": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("brasil-scrapers/santander-imoveis-api").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 = {
    "numberOfPages": 1,
    "proxy": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("brasil-scrapers/santander-imoveis-api").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 '{
  "numberOfPages": 1,
  "proxy": {
    "useApifyProxy": false
  }
}' |
apify call brasil-scrapers/santander-imoveis-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=brasil-scrapers/santander-imoveis-api",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Santander Imóveis API",
        "description": "API para busca de imóveis do Santander com diversos filtros personalizáveis.",
        "version": "0.1",
        "x-build-id": "4eed1b1P9UeAIzlQJ"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/brasil-scrapers~santander-imoveis-api/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-brasil-scrapers-santander-imoveis-api",
                "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/brasil-scrapers~santander-imoveis-api/runs": {
            "post": {
                "operationId": "runs-sync-brasil-scrapers-santander-imoveis-api",
                "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/brasil-scrapers~santander-imoveis-api/run-sync": {
            "post": {
                "operationId": "run-sync-brasil-scrapers-santander-imoveis-api",
                "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",
                "properties": {
                    "state": {
                        "title": "state",
                        "enum": [
                            "AC",
                            "AL",
                            "AM",
                            "AP",
                            "BA",
                            "CE",
                            "DF",
                            "ES",
                            "GO",
                            "MA",
                            "MG",
                            "MS",
                            "MT",
                            "PA",
                            "PB",
                            "PE",
                            "PI",
                            "PR",
                            "RJ",
                            "RN",
                            "RO",
                            "RR",
                            "RS",
                            "SC",
                            "SE",
                            "SP",
                            "TO"
                        ],
                        "type": "string",
                        "description": "State to search for",
                        "default": "SP"
                    },
                    "city": {
                        "title": "city",
                        "type": "string",
                        "description": "City to search for",
                        "default": "SAO PAULO"
                    },
                    "category": {
                        "title": "category",
                        "type": "array",
                        "description": "category My multiselect field",
                        "items": {
                            "type": "string",
                            "enum": [
                                "comercial",
                                "residencial",
                                "industrial",
                                "rural"
                            ],
                            "enumTitles": [
                                "comercial",
                                "residencial",
                                "industrial",
                                "rural"
                            ]
                        }
                    },
                    "situation": {
                        "title": "situation",
                        "type": "array",
                        "description": "situation My multiselect field",
                        "items": {
                            "type": "string",
                            "enum": [
                                "ocupado",
                                "desocupado",
                                "locado"
                            ],
                            "enumTitles": [
                                "ocupado",
                                "desocupado",
                                "locado"
                            ]
                        }
                    },
                    "type": {
                        "title": "type",
                        "type": "array",
                        "description": "type My multiselect field",
                        "items": {
                            "type": "string",
                            "enum": [
                                "apartamento",
                                "galpao",
                                "casa",
                                "loja",
                                "casacom",
                                "salacomer",
                                "chacara",
                                "lote",
                                "fazenda",
                                "lotecom"
                            ],
                            "enumTitles": [
                                "Apartamento",
                                "Galpão",
                                "Casa",
                                "Loja",
                                "Casa em condominio",
                                "Sala Comercial",
                                "Chácara",
                                "Lote",
                                "Fazenda",
                                "Lote em condominio"
                            ]
                        }
                    },
                    "maxPrice": {
                        "title": "Maximum Price",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Set the maximum price for the properties (e.g., 100000)."
                    },
                    "minPrice": {
                        "title": "Min Price",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Set the min price"
                    },
                    "numberOfPages": {
                        "title": "numberOfPages",
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Select the number of pages to scrape"
                    },
                    "sameDomainDelaySecs": {
                        "title": "sameDomainDelaySecs",
                        "type": "integer",
                        "description": "Delay between requests to the same domain",
                        "default": 1
                    },
                    "minConcurrency": {
                        "title": "minConcurrency",
                        "type": "integer",
                        "description": "Minimum number of pages to scrape concurrently"
                    },
                    "maxConcurrency": {
                        "title": "maxConcurrency",
                        "type": "integer",
                        "description": "Maximum number of pages to scrape concurrently"
                    },
                    "proxy": {
                        "title": "Proxy",
                        "type": "object",
                        "description": "Define proxy to pass data through",
                        "default": {
                            "useApifyProxy": false
                        }
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
