# Fincaraiz Market Data API Documentation

Scrappa's `GET /api/fincaraiz/market-data` returns platform-computed market aggregates for a filter: `count_results`, `avg_price`, `avg_price_m2`, and `avg_time_in_market` (days on market).

## This count is not the corpus size

Read `count_results` as a market indicator, **not** as a listing count. It disagrees with the search endpoint's `total` for the same filter, and the search total is the authoritative figure. If you need an exact count, use search.

The aggregate is also global: it cannot be scoped to a single agency, so never present it as an agency-scoped metric.

Averages arrive in Colombian pesos per square metre.

- **Documentation:** [https://scrappa.co/docs/fincaraiz-api/fincaraiz_market_data](https://scrappa.co/docs/fincaraiz-api/fincaraiz_market_data)
- **API group:** Fincaraiz API
- **Endpoint:** `GET https://scrappa.co/api/fincaraiz/market-data`

## 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 (default) or 2 for rent. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/fincaraiz/market-data?operation_type_id=1"
```

## Example response

```json
{
    "success": true,
    "market": {
        "id": "1",
        "count_results": 180223,
        "avg_price": 412500000,
        "avg_price_m2": 1658.12,
        "avg_time_in_market": 158,
        "currency": {
            "name": "COP"
        }
    },
    "caveat": "This aggregate is not the corpus size: it disagrees with the search total for the same filter, and it ignores owner_id. Use the search endpoint's total for counts.",
    "meta": {
        "billable": true,
        "endpoint_family": "market-data",
        "attempts": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 503 | Unreadable Response | The platform answered successfully with a body this endpoint cannot read, so nothing is published and nothing is charged (`parser_drift`). Retryable. |
| 503 | Upstream Unavailable | The upstream request failed, or returned no aggregate for that filter. Retryable and never billed. |

## Frequently asked questions

### Why does the count differ from search?

The aggregate is a market indicator computed independently of the search index, and the two disagree. The search endpoint's total is the authoritative listing count — use this endpoint for averages, not totals.

### Can I scope it to one agency?

No. The aggregate ignores the agency filter entirely, so an agency-scoped request would return the global figure. Use agency-properties for an agency's real inventory.

## Related endpoints

- [Search](https://scrappa.co/docs/fincaraiz-api/fincaraiz_search)
- [Agency Inventory](https://scrappa.co/docs/fincaraiz-api/fincaraiz_agency_properties)

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