HammerMap: Spanish court auctions and State sales

Search current Spanish court auctions (BOE section IV) and State/public-body sales (BOE section V-B). Use it first to find listings by province, town, type, asset type, starting price or dates; then call get_listing with an id for the full record. Returns total count, paging (limit/offset) and short records: id, title in 5 languages, approximate place, seller, starting price in EUR when the notice gives one, publication date, deadline, HammerMap risk light and links (HammerMap page, official channel, BOE notice). Coverage: Spain only. Data are updated once per working day; attribution.data_updated and attribution.latest_boe_publication show how fresh they are. Court auction notices in BOE open data have no price, description or closing date (those are on the official portal). All filters are optional and combine with AND.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Free text, accent-insensitive, matched in title, seller, town, province and lot description, e.g. \"vivienda\" or \"Puerto de Valencia\""
    },
    "country": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 country code. Only ES (Spain) has data; any other value returns 0 results.",
      "default": "ES"
    },
    "province": {
      "type": "string",
      "description": "Spanish province, exact name, accent-insensitive, e.g. Madrid, Valencia, Illes Balears. Call get_facets for the list."
    },
    "municipality": {
      "type": "string",
      "description": "Town, exact name: the court's town for court auctions, the asset's town for State sales"
    },
    "type": {
      "type": "string",
      "enum": [
        "court_auction",
        "state_sale"
      ],
      "description": "court_auction = judicial auction (BOE IV); state_sale = sale by the State or a public body (BOE V-B)"
    },
    "procedure": {
      "type": "string",
      "enum": [
        "apremio",
        "voluntaria",
        "concursal",
        "estado",
        "tgss"
      ],
      "description": "apremio = enforcement for debt, voluntaria = voluntary court sale, concursal = insolvency, estado = State sale, tgss = Social Security (TGSS) auction"
    },
    "asset_type": {
      "type": "string",
      "enum": [
        "vivienda",
        "local",
        "garaje",
        "solar",
        "rustica",
        "inmueble",
        "vehiculo",
        "otros",
        "unknown"
      ],
      "description": "vivienda = home, local = commercial premises, garaje = parking, solar = building plot, rustica = rural land, inmueble = other real estate, vehiculo = vehicle, otros = other goods, unknown = not stated in the notice"
    },
    "min_price": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum starting price in EUR. Only listings with a known price match."
    },
    "max_price": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum starting price in EUR. Only listings with a known price match."
    },
    "published_from": {
      "type": "string",
      "format": "date",
      "description": "BOE publication date from (YYYY-MM-DD)"
    },
    "published_to": {
      "type": "string",
      "format": "date",
      "description": "BOE publication date to (YYYY-MM-DD)"
    },
    "deadline_from": {
      "type": "string",
      "format": "date",
      "description": "Bid deadline from; only listings with a known deadline match (YYYY-MM-DD)"
    },
    "deadline_to": {
      "type": "string",
      "format": "date",
      "description": "Bid deadline to; only listings with a known deadline match (YYYY-MM-DD)"
    },
    "sort": {
      "type": "string",
      "enum": [
        "published_desc",
        "deadline_asc",
        "deadline_desc",
        "price_asc",
        "price_desc",
        "risk_asc",
        "risk_desc"
      ],
      "default": "published_desc",
      "description": "published_desc = newest first (default), deadline_asc / deadline_desc = closing soonest / latest (no deadline last), price_asc / price_desc = by starting price (no price last), risk_asc / risk_desc = by HammerMap risk light green < yellow < red"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Results per page, 1-100"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "default": 0,
      "description": "Number of results to skip, for paging"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "total": {
      "type": "integer",
      "description": "Number of matching listings"
    },
    "limit": {
      "type": "integer"
    },
    "offset": {
      "type": "integer"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "Short listing records"
    },
    "attribution": {
      "type": "object",
      "additionalProperties": true
    },
    "licence": {
      "type": "string"
    }
  },
  "required": [
    "total",
    "items",
    "attribution"
  ]
}

Full record for one listing by id from search_listings (SUB-… for court auctions, BOE-B-… for State sales from the BOE, TGSS-… for Social Security (TGSS) auctions): lots with starting price and deposit, bid deadline, auction session date, bidding mode, approximate place, HammerMap's general risk analysis with legal basis (not legal advice), corrections, official BOE and portal links, and data freshness (attribution.data_updated). Returns an error if the id is not listed any more. Bids and payments happen only on the official channel in urls / bidding.where.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^(?:SUB-[A-Z0-9-]{4,40}|BOE-B-\\d{4}-\\d{1,7}|TGSS-[A-Z0-9-]{4,40})$",
      "description": "Listing id exactly as returned by search_listings, e.g. SUB-JA-2026-267510 or BOE-B-2026-35250"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "listing": {
      "type": "object",
      "additionalProperties": true
    },
    "attribution": {
      "type": "object",
      "additionalProperties": true
    },
    "licence": {
      "type": "string"
    }
  },
  "required": [
    "listing",
    "attribution"
  ]
}

Counts of current listings by type, procedure, asset type and province, the starting-price range, covered countries, and data freshness (data_updated, latest_boe_publication, update_frequency). Use it to discover valid filter values for search_listings or to answer "how many / how fresh" questions. No arguments.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "facets": {
      "type": "object",
      "additionalProperties": true
    },
    "attribution": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "required": [
    "facets",
    "attribution"
  ]
}