# Fincaraiz Search API Documentation Scrappa's `GET /api/fincaraiz/search` returns Colombian property listings for sale (`operacion=venta`) or for rent (`operacion=arriendo`) as structured JSON, instead of the HTML you would otherwise have to scrape. ## What you get One request returns a page of listings plus the platform's own match count in `total`. That count comes from the platform's search index and is the only number on this API that reflects the full result set — the totals on the enrichment endpoints do not, and the pagination fields are derived from this one. Each listing is returned essentially as the platform publishes it: `id`, `title`, `description`, `price` (`amount` and `currency`), `bedrooms`, `bathrooms`, `area`, `address`, `typeID`, `facilities`, `latitude`/`longitude`, `created_at`, `sold`, `soldDate`, and the full nested `locations` tree. On top of that, `images` is a flat list of image URLs, `image_count` and `has_images` describe them, and `active` tells you whether the listing is currently live. Titles are published with double spaces and are returned exactly as written. ## Geography Use `locations`, not a city name. Colombia uses two unrelated id vocabularies on this platform: search geography is a UUID, while the numbered estate ids used by the location vocabulary do not work here at all. Get the right value from `/api/fincaraiz/location-autocomplete?term=medellin`, which returns each match together with the exact `id` and `type` pair to pass back. Each location needs both an id and a type, for example `locations[0][id]=...&locations[0][type]=CITY`. Omitting the type is rejected. ## Filters that silently do nothing This platform accepts a set of parameter names and ignores them completely: you get a normal `200` with a correct-looking result set and an unchanged `total`. Rather than pass that on, this API **rejects** them with a `422`, along with any name it does not support. So a request that returns `200` has had every filter you asked for applied. The `fair_active` flag is separately rejected under any spelling: it is an internal allowlist switch that reduces a corpus of more than 180,000 listings to roughly 130. ## Ranges and units Prices are whole Colombian pesos and are large — a typical apartment is in the hundreds of millions. Supply them as plain integers. Area is in square metres. Filters intersect: a minimum and maximum price narrow the result together rather than one replacing the other. ## What this API does not cover This is read-only listing data. There is no account access, no messaging or contact-form submission, and no listing creation. The platform publishes no reviews or ratings and no price history, so neither appears here. Sold and expired listings are not reachable through a filter: the platform has no lifecycle filter, so `active`, `sold`, and `soldDate` are per-listing flags you read rather than filter on. - **Documentation:** [https://scrappa.co/docs/fincaraiz-api/fincaraiz_search](https://scrappa.co/docs/fincaraiz-api/fincaraiz_search) - **API group:** Fincaraiz API - **Endpoint:** `GET https://scrappa.co/api/fincaraiz/search` ## Authentication Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `operation_type_id` | integer | No | 1 for sale (venta, the default) or 2 for rent (arriendo). | | `property_type_id` | integer | No | One or more of 1 house, 2 apartment, 3 lot, 4 commercial premises. Repeatable, or comma-separated. | | `minPrice` | integer | No | Minimum price in Colombian pesos, as a whole number (e.g. 200000000). | | `maxPrice` | integer | No | Maximum price in Colombian pesos. | | `m2Min` | integer | No | Minimum area in square metres. | | `m2Max` | integer | No | Maximum area in square metres. | | `bedrooms` | integer | No | Minimum number of bedrooms (a count, not an id). Repeatable. | | `bathrooms` | integer | No | Minimum number of bathrooms. Repeatable. | | `rooms` | integer | No | Minimum number of rooms. Repeatable. | | `stratum` | integer | No | Neighbourhood wealth bracket, 1-6. Repeatable. | | `locations` | string | No | One or more location objects, each with an id and a type, both required. Ids come from location-autocomplete. Format: locations[0][id]=UUID&locations[0][type]=CITY. | | `order` | integer | No | Result ordering code. This sorts results and never changes the total. | | `owner_id` | integer | No | Restrict results to one agency's inventory. | | `privateOwner` | boolean | No | Restrict results to private (non-agency) sellers. | | `rows` | integer | No | Listings per page, 1-200 (default 20). | | `page` | integer | No | Result page, 1-based. A page past the end returns a valid but empty page, not an error. | ## Example request ```bash #!/bin/bash curl -X GET \ -H "x-api-key: YOUR_API_KEY_HERE" \ "https://scrappa.co/api/fincaraiz/search?operation_type_id=1&property_type_id=2&maxPrice=400000000&bedrooms=3&rows=10" ``` ## Example response ```json { "success": true, "total": 83191, "page": 1, "rows": 10, "returned": 10, "total_pages": 8320, "applied_filters": { "operation_type_id": 1, "property_type_id": [ 2 ], "maxPrice": 400000000, "bedrooms": [ 3 ] }, "property_types": { "1": "casa", "2": "apartamento", "3": "lote", "4": "local" }, "listings": [ { "id": 191347339, "title": "Apartamento en Venta en Manga, Cartagena", "price": { "amount": 880000000, "currency": "COP" }, "bedrooms": 3, "bathrooms": 2, "area": 120, "typeID": 2, "active": true, "sold": false, "soldDate": null, "image_count": 12, "has_images": true, "images": [ "https://cdn4.fincaraiz.com.co/repo/img/example.jpg" ], "latitude": 10.4236, "longitude": -75.5478 } ], "meta": { "billable": true, "endpoint_family": "search", "attempts": 1 } } ``` ## Errors | Status | Error | Description | | --- | --- | --- | | 422 | Unsupported Filter | A filter name this API does not support, or one the platform accepts and silently ignores, was supplied (`unknown_filter`, `blocked_filter`). Non-billable. | | 422 | Validation Error | A query parameter failed validation. Non-billable. | | 503 | Upstream Unavailable | The upstream request failed or could not be parsed after retries. Retryable and never billed. Clients are never rate limited. | | 503 | Unreadable Response | Fincaraiz answered 200 with a body this endpoint cannot read (`parser_drift`). Nothing is charged for it; an empty or reshaped upstream payload is reported rather than published as an empty result. Retryable. | ## Frequently asked questions ### Does Fincaraiz offer an official API? No. Fincaraiz publishes no developer API. Scrappa provides a documented read-only API over its public listing surfaces and returns normalized JSON with API key authentication. ### Why does my filter get rejected when the website accepts it? Several parameter names the platform accepts have no effect: the response is a normal 200 with an unchanged total, so the filter would silently do nothing. Those names, plus fair_active, are rejected with a 422 instead. Any request that returns 200 has had all of its filters applied. ### Are empty results charged? A 200 response with zero listings is a valid answer and is billed. Failures — rejected filters, validation errors, and upstream outages — never consume credits. ### Can I search by city name? Not directly. Pass ids and types from the location-autocomplete endpoint. The numbered estate ids from the location vocabulary are a different set and return no results in search. ## Related endpoints - [Listing Details](https://scrappa.co/docs/fincaraiz-api/fincaraiz_property) - [Location Autocomplete](https://scrappa.co/docs/fincaraiz-api/fincaraiz_location_autocomplete) - [Map Pins](https://scrappa.co/docs/fincaraiz-api/fincaraiz_map_pins) ## More Scrappa resources - [API documentation](https://scrappa.co/docs) - [Full LLM-readable API reference](https://scrappa.co/llms-full.txt) - [OpenAPI specification](https://scrappa.co/docs/api.json) - [Pricing](https://scrappa.co/pricing)