# Fincaraiz Map Pins API Documentation

Scrappa's `GET /api/fincaraiz/map-pins` returns the coordinates of every listing matching a filter — one pin per listing, with its id.

This is the platform's only map layer. Unlike search, it is not paginated in the way you would expect: it returns the full spread of pins for the filter rather than a page of them, so responses are large.

Each pin carries the listing `id` and its coordinates, so you can fetch full detail for the ones a user actually clicks rather than paying for every listing up front.

A multi-valued filter is all or nothing here: `property_type_id=2,notanumber` is rejected with a `422` and never billed, rather than answered as `property_type_id=2`. Silently narrowing a filter would return pins the customer did not ask for and charge them for the narrower answer. The same rule applies on search.

- **Documentation:** [https://scrappa.co/docs/fincaraiz-api/fincaraiz_map_pins](https://scrappa.co/docs/fincaraiz-api/fincaraiz_map_pins)
- **API group:** Fincaraiz API
- **Endpoint:** `GET https://scrappa.co/api/fincaraiz/map-pins`

## 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. |
| `property_type_id` | integer | No | One or more of 1 house, 2 apartment, 3 lot, 4 commercial premises. |
| `rows` | integer | No | Pins per page, 1-200 (default 100). Echoed back as `rows` exactly as applied. |
| `page` | integer | No | Result page, 1-based. Echoed back as `page` exactly as applied. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/fincaraiz/map-pins?operation_type_id=1&property_type_id=2"
```

## Example response

```json
{
    "success": true,
    "returned": 2,
    "applied_filters": {
        "operation_type_id": 1,
        "property_type_id": [
            2
        ]
    },
    "pins": [
        {
            "id": "191347339",
            "project_id": null,
            "latitude": 10.4236,
            "longitude": -75.5478,
            "point_type": "property",
            "md5": "..."
        }
    ],
    "meta": {
        "billable": true,
        "endpoint_family": "map-pins",
        "attempts": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Unsupported Filter | A filter this endpoint cannot apply, or a list with any unusable entry, was supplied (`unknown_filter`). Non-billable. |
| 503 | Upstream Unavailable | The upstream request failed after retries. Retryable and never billed. |
| 503 | Unreadable Response | Fincaraiz answered 200 with something other than a list of pins — an envelope, an empty object, or a list holding a non-record (`parser_drift`). Nothing is charged for it; an unreadable body is never published as an empty map. Retryable. |

## Frequently asked questions

### Is there a limit on map pins?

No hard limit, but broad filters return a large payload — roughly a megabyte for a national sale search. Narrow by property type or location when you can.

## Related endpoints

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

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