# Fincaraiz Similar Properties API Documentation

Scrappa's `GET /api/fincaraiz/similar-properties` returns comparable listings for a given property, as full listing objects with the same shape as search results.

This is the platform's own similarity engine. It returns whatever it considers comparable — which may include a different property type or price band than the original — so treat the result as a set of neighbours rather than an exact match on your own filters.

An empty list is a valid answer: some listings have no comparables, and that is not an error.

- **Documentation:** [https://scrappa.co/docs/fincaraiz-api/fincaraiz_similar_properties](https://scrappa.co/docs/fincaraiz-api/fincaraiz_similar_properties)
- **API group:** Fincaraiz API
- **Endpoint:** `GET https://scrappa.co/api/fincaraiz/similar-properties`

## 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 |
| --- | --- | --- | --- |
| `id` | string | Yes | Numeric listing id to find comparables for. |
| `rows` | integer | No | Maximum comparables to return, 1-50 (default 6). |
| `page` | integer | No | Result page, 1-based. |
| `is_project` | boolean | No | true to compare against projects rather than individual listings, false (default) for listings. This changes which records are compared, so it changes the result set. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/fincaraiz/similar-properties?id=191347339&rows=6"
```

## Example response

```json
{
    "success": true,
    "id": 191347339,
    "returned": 2,
    "listings": [
        {
            "id": 191347401,
            "title": "Apartamento en  Venta en Manga, Cartagena",
            "price": {
                "amount": 895000000,
                "currency": "COP"
            },
            "bedrooms": 3,
            "image_count": 9,
            "images": [
                "https://cdn4.fincaraiz.com.co/repo/img/example.jpg"
            ]
        }
    ],
    "meta": {
        "billable": true,
        "endpoint_family": "similar-properties",
        "attempts": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 503 | Upstream Unavailable | The upstream request failed after retries, or returned a response this endpoint cannot read (`upstream_unavailable`, `parser_drift`). Retryable and never billed. |
| 422 | Validation Error | A query parameter failed validation. Non-billable. |
| 503 | Unreadable Response | Fincaraiz answered 200 with a body this endpoint cannot read (`parser_drift`). Nothing is charged for it. Retryable. |

## Frequently asked questions

### Are similar listings guaranteed to match my filters?

No. These are the platform's own comparables and may differ in property type or price. Apply your own filters to the result if you need a narrower set.

## Related endpoints

- [Listing Details](https://scrappa.co/docs/fincaraiz-api/fincaraiz_property)
- [Search](https://scrappa.co/docs/fincaraiz-api/fincaraiz_search)

## 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)