# Spain Property Auctions API - BOE Subastas in English (`webdata_labs/spain-boe-subastas-api`) Actor

\[💵 $2.00 / 1K] Subastas judiciales e inmobiliarias del BOE: valoración, puja mínima, cargas y referencia catastral. Clean English schema for international investors - appraisal, minimum bid, deposit, discount vs appraisal, address & encumbrances. Not a subastas.boe.es dump.

- **URL**: https://apify.com/webdata\_labs/spain-boe-subastas-api.md
- **Developed by:** [WebData Labs](https://apify.com/webdata_labs) (community)
- **Categories:** Real estate, Lead generation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 auction records

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

## Spain Property Auctions API - BOE Subastas in English

**One clean English row for every Spanish property (and asset) auction.** Filter by province, asset type and status, or pass specific auction IDs, and get analysis-ready investor leads from Spain's official BOE auction portal (`subastas.boe.es`): appraisal value, minimum bid, deposit, bid increment, the **discount vs appraisal**, full address, cadastral reference, registry ID, and encumbrances - decoded from the raw Spanish legal text, money format, and HTML entities into one consistent schema.

Spain's official auction data (Agencia Tributaria, judicial, notarial and administrative auctions, published on `subastas.boe.es`) is a Spanish-only legal dump: money is formatted `371.469,55 €` (dot thousands, comma decimal); accents arrive as raw bytes or HTML entities; the asset type, auction type and possession status are Spanish legal phrases; the property is buried in a registral-text soup spread across tabs; and the single number an investor actually wants - **how far below appraisal the minimum bid sits** - is never given. Most "BOE scrapers" hand you that raw Spanish dump. This Actor does the hard part: it cracks the portal's stateful search, parses both detail tabs, normalizes money and dates, decodes every label to **English**, derives the `discountPctVsAppraisal` signal, and returns **one consistent row** per auction with the full asset list preserved.

### ✅ What you get / ❌ what this isn't

| This Actor gives you | This Actor is not |
|---|---|
| One normalized row per auction, English-labeled, identical shape every time | Not a raw Spanish `subastas.boe.es` dump |
| Economics decoded: appraisal, minimum bid, deposit, bid increment, debt claimed | Not affiliated with or endorsed by the BOE, the Agencia Tributaria or any court |
| The derived `discountPctVsAppraisal` investor signal | Not investment, legal, or bidding advice |
| Property fields: address, cadastral reference, registry ID (IDUFIR), encumbrances | Not a guarantee that every auction exposes every field |
| Search by province / asset type / status, or fetch specific auction IDs | Not real-time - reflects the BOE auction-portal publication cadence |
| Multi-lot auctions: every asset preserved in `assets[]` | Not a bidding or escrow service - you bid through the official portal |

### 🔎 Why use this Actor

- Source below-market property deals by filtering on appraisal, minimum bid, and discount.
- Build a fresh, structured feed of live and upcoming Spanish auctions for a region.
- Get **English** auction leads for an international pipeline instead of Spanish-only legal text.
- Skip the cadastral reference straight into Catastro for deeper due diligence.
- Feed normalized auction data into a CRM, dashboard, model, or LLM workflow.
- Skip the plumbing - stateful search, Spanish money/date parsing, multi-tab merge, and the discount math are done.

### 👥 Who it's for

- Property investors, flippers, and buy-to-let buyers hunting distressed and below-appraisal assets.
- Real-estate lead-gen agencies and portals serving Spanish auction buyers.
- Funds and brokers tracking judicial, tax-agency, and notarial auctions by region.
- Proptech and data teams building Spanish auction alerts or dashboards.
- Anyone who wants one tidy English schema instead of a `subastas.boe.es` parsing project.

### 🗂️ What data you get

One row per auction (primary asset flattened for the table view, all assets in `assets[]`):

| Field | Type | Description |
|---|---|---|
| `auctionId`, `auctionUrl` | string | BOE auction ID and the official detail URL |
| `auctionType`, `auctionTypeEs` | string | `TAX_AGENCY` / `JUDICIAL` / `NOTARIAL` / ... (+ Spanish) |
| `status`, `statusEs` | string | `LIVE` / `UPCOMING` / `SUSPENDED` / `CANCELLED` / `CONCLUDED` |
| `boeAnnouncementId` | string | The linked BOE bulletin announcement (`BOE-B-...`) |
| `startDate`, `endDate` | string | Auction open and close timestamps (ISO 8601) |
| `appraisalValue` | number | Tasación - the official appraisal in EUR |
| `auctionValue` | number | Valor de subasta in EUR |
| `minimumBid` | number | Puja mínima in EUR (`null` when "sin puja mínima") |
| `bidIncrement` | number | Tramos entre pujas in EUR |
| `deposit` | number | Required deposit (Importe del depósito) in EUR |
| `amountClaimed` | number | Cantidad reclamada - the debt behind a judicial auction |
| `discountPctVsAppraisal` | number | Derived: how far the minimum bid sits below appraisal |
| `assetType`, `assetSubtype` | string | `REAL_ESTATE` / `VEHICLE` / `MOVABLE` + English subtype |
| `address`, `postalCode`, `city`, `province` | string | Structured location of the primary asset |
| `cadastralReference` | string | Referencia catastral (links straight into Catastro) |
| `encumbrances`, `totalEncumbrances` | number | Cargas on the primary asset and across all lots |
| `possessionStatus` | string | `WITH_POSSESSION` / `WITHOUT_POSSESSION` / `UNKNOWN` |
| `lotCount`, `assetCount`, `assets[]` | number / array | Lot/asset counts and the full per-asset records |

### Example tasks

- [Find live property auctions in Madrid below appraisal](https://apify.com/webdata_labs/spain-boe-subastas-api/examples/madrid-live-property-auctions)
- [Track live property auctions on the Costa del Sol (Málaga)](https://apify.com/webdata_labs/spain-boe-subastas-api/examples/malaga-costa-del-sol-property-auctions)
- [Build English lead records for specific BOE auction IDs](https://apify.com/webdata_labs/spain-boe-subastas-api/examples/auction-leads-by-id)

### ⚙️ How to pull auction data

1. Open the Actor on Apify.
2. Set `province` (name or INE code), `assetType` (real estate / vehicles / movable), and `status` (live / upcoming / ...). Or paste specific `auctionIds`.
3. Optionally set `city`, `maxResults`, and toggle `includeRaw`.
4. Run the Actor and open the `Auctions` dataset view.
5. Export JSON, CSV, Excel, HTML, or XML, or call the Actor through the Apify API.

### 📥 Input

```json
{
  "province": "Madrid",
  "assetType": "real-estate",
  "status": "live",
  "maxResults": 100,
  "includeRaw": false
}
```

### 📤 Output

```json
{
  "recordType": "auction",
  "auctionId": "SUB-AT-2026-26R2886001022",
  "auctionUrl": "https://subastas.boe.es/detalleSubasta.php?idSub=SUB-AT-2026-26R2886001022",
  "auctionType": "TAX_AGENCY",
  "status": "LIVE",
  "boeAnnouncementId": "BOE-B-2026-21934",
  "startDate": "2026-06-30T18:00:00+02:00",
  "endDate": "2026-07-20T18:00:00+02:00",
  "currency": "EUR",
  "appraisalValue": 371469.55,
  "minimumBid": 37146.96,
  "deposit": 18573.47,
  "bidIncrement": 2000.0,
  "discountPctVsAppraisal": 90.0,
  "assetType": "REAL_ESTATE",
  "assetSubtype": "Dwelling",
  "address": "CL ARACNE 29 A1 05 D",
  "postalCode": "28022",
  "city": "MADRID",
  "province": "Madrid",
  "cadastralReference": "0274202VK5707C0221BD",
  "encumbrances": 0.0,
  "possessionStatus": "UNKNOWN",
  "lotCount": 0,
  "assetCount": 1
}
```

### 💵 How much does it cost?

The launch price is about `$2.00 / 1,000 auctions`, tier-discounted for higher Apify plans. One auction row is one charged result. A run returning 80 auctions is 80 results. Failed lookups are not charged.

### 🔁 Run it on the Apify platform

Schedule a recurring run to keep a regional auction feed fresh (new auctions, status changes), call it from the Apify API, export to CSV/JSON/Excel, or connect the dataset to Make, Zapier, webhooks, a warehouse, a CRM, or an LLM pipeline.

### ⚠️ Limits and caveats

- This Actor reads the **public BOE auction portal** (`subastas.boe.es`). It is not affiliated with the BOE, the Agencia Tributaria, or any court, and returns only data already public there.
- **Not investment or legal advice.** Encumbrances, possession status, and registral details are reproduced from the source; verify every lot before bidding.
- **Field coverage varies by auction type.** Judicial auctions may have no minimum bid ("sin puja mínima", returned as `null`) and expose `amountClaimed`; tax-agency auctions usually carry a minimum.
- **Status is required for search.** Pick one of live / upcoming / suspended / cancelled / concluded; for direct `auctionIds` the status filter is ignored.
- Data reflects the BOE auction-portal publication cadence, not real time.

### 🧩 Related Actors

- EU Tenders API - normalized TED public procurement in one English schema.
- Brazil CNPJ Company API - clean English firmographics for any Brazil CNPJ.
- US Building Permits API - normalized construction permits and contractor leads.
- Sanctions Screening API - OFAC, EU, UK and UN watchlist screening with explained matches.

### ❓ FAQ

#### What is BOE Subastas?

`subastas.boe.es` is Spain's official electronic auction portal, run by the Agencia Estatal Boletín Oficial del Estado. It publishes tax-agency, judicial, notarial, and administrative auctions of real estate, vehicles, and other assets. This Actor turns those auctions into clean, English-labeled investor leads.

#### What is `discountPctVsAppraisal`?

It is the gap between the official appraisal (`Tasación`) and the minimum bid (`Puja mínima`), as a percentage. A 90% discount means the floor price is 10% of appraisal. It is the fastest way to surface below-market opportunities; always verify the lot, encumbrances, and possession before acting.

#### Can it search the whole country?

Yes. Leave `province` empty to search all of Spain, or set a province name or INE code (01-52) to narrow it. You can also add a `city` filter.

#### Does it handle multi-lot auctions?

Yes. Every asset is preserved in `assets[]`, and the primary asset is flattened onto the row for the table view. `assetCount` and `lotCount` tell you how many.

#### Why is the cadastral reference useful?

The `cadastralReference` (Referencia catastral) links straight into Spain's Catastro, so you can pull plot, surface, and use details for due diligence beyond what the auction notice shows.

#### Does it need a proxy?

No. BOE Subastas is a public official source served reliably to datacenter IPs. Enable Apify Proxy only for very large batches.

### 🇪🇸 En español

**Extrae subastas judiciales e inmobiliarias del portal oficial BOE Subastas (subastas.boe.es)** en un esquema limpio y estructurado: valoración, puja mínima, depósito, descuento sobre la valoración, dirección, referencia catastral y cargas - listo para Excel, CSV o JSON.

- **Filtra por provincia o ciudad** (por ejemplo Madrid, Barcelona, Valencia) o busca en toda España.
- **Cada lote se conserva** en `assets[]`, con el activo principal aplanado en la fila.
- **La referencia catastral** enlaza directamente con el Catastro para la due diligence.
- Los importes se normalizan a números (sin formato de texto legal), y los campos se traducen al inglés para inversores internacionales - si necesitas etiquetas en español, los códigos originales del BOE se conservan en cada fila.

¿Falta un campo o algo no funciona? Abre un issue del Actor con la URL de la ejecución y te respondemos normalmente en un día.

### 🛠️ Support

For bugs, missing fields, or a feature request, open an Actor issue with the run URL, the filters or auction IDs used, and the field or behavior you expected.

### ⭐ Rate this Actor

If this Actor saved you time, please take 30 seconds to leave a review on the **Reviews** tab of [Spain Property Auctions API - BOE Subastas in English](https://apify.com/webdata_labs/spain-boe-subastas-api) - reviews are the main trust signal other users see, and they directly decide which features get built next. If something is broken or a field is missing, please [open an issue](https://apify.com/webdata_labs/spain-boe-subastas-api/issues) first - we typically respond within a day and would love the chance to fix it before you rate.

# Actor input Schema

## `province` (type: `string`):

Spanish province to search (name or INE code). Examples: 'Madrid', 'Barcelona', 'Valencia', '28', '08'. Leave empty to search the whole country.

## `assetType` (type: `string`):

What kind of asset is being auctioned.

## `status` (type: `string`):

Live = currently open for bids (Celebrandose). Upcoming = announced, not yet open. Suspended / Cancelled / Concluded for the rest.

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

Optional free-text locality filter, e.g. 'Marbella'. Combined with province.

## `auctionIds` (type: `string`):

Fetch specific auctions directly instead of searching. One or more BOE auction IDs (e.g. 'SUB-AT-2026-26R2886001022'), separated by comma, space or new line. When set, the search filters above are ignored.

## `maxResults` (type: `integer`):

Safety cap on how many auctions to return in one run. Each auction is two light HTTP requests.

## `includeRaw` (type: `boolean`):

Attach the original Spanish label/value pairs under 'raw' for auditing. Off by default to keep rows clean.

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

Optional. BOE Subastas is a public official source and works without a proxy; enable Apify Proxy only for very large batches.

## Actor input object example

```json
{
  "province": "Madrid",
  "assetType": "real-estate",
  "status": "live",
  "maxResults": 100,
  "includeRaw": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `OUTPUT` (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 = {
    "province": "Madrid"
};

// Run the Actor and wait for it to finish
const run = await client.actor("webdata_labs/spain-boe-subastas-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 = { "province": "Madrid" }

# Run the Actor and wait for it to finish
run = client.actor("webdata_labs/spain-boe-subastas-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 '{
  "province": "Madrid"
}' |
apify call webdata_labs/spain-boe-subastas-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=webdata_labs/spain-boe-subastas-api",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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