# Fincaraiz Route Resolver API Documentation

Scrappa's `GET /api/fincaraiz/route-resolver` turns a public Fincaraiz URL into the filter values it represents — this is the supported way to translate between the platform's two id vocabularies.

Pass a path such as `/venta/apartamentos/medellin/antioquia`. The response reports the resolved view and status, the URL parts, and the filter set behind that page: `operation_type_id`, `property_type_id`, `currencyID`, `order`, and the location tree carrying both the department name and its search UUID.

Because it returns the UUID the search endpoint wants, this removes the most common integration error on this platform — reaching for the numbered vocabulary id, which silently matches nothing.

- **Documentation:** [https://scrappa.co/docs/fincaraiz-api/fincaraiz_route_resolver](https://scrappa.co/docs/fincaraiz-api/fincaraiz_route_resolver)
- **API group:** Fincaraiz API
- **Endpoint:** `GET https://scrappa.co/api/fincaraiz/route-resolver`

## 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 |
| --- | --- | --- | --- |
| `url` | string | Yes | Public Fincaraiz path, for example /venta/apartamentos/medellin/antioquia. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/fincaraiz/route-resolver?url=%2Fventa%2Fapartamentos%2Fmedellin%2Fantioquia"
```

## Example response

```json
{
    "success": true,
    "route": {
        "status": 200,
        "view": "searchPage",
        "urlParts": {
            "path": "/venta/apartamentos/medellin/antioquia",
            "query": "",
            "fragment": ""
        },
        "extras": {
            "operation_type_id": 1,
            "property_type_id": [
                2
            ],
            "order": 2,
            "filters": []
        }
    },
    "meta": {
        "billable": true,
        "endpoint_family": "route-lookup",
        "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. |
| 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. |
| 422 | Validation Error | No url was supplied. Non-billable. |
| 404 | Route Not Found | That URL does not resolve to a Fincaraiz route (`not_found`). Non-billable. |

## Frequently asked questions

### Why not just use the ids from the vocabulary endpoint in search?

Because they are a different id set. Search geography uses UUIDs; the vocabulary numbers locations. The route resolver returns both in one call, which is the supported translation.

## Related endpoints

- [Search](https://scrappa.co/docs/fincaraiz-api/fincaraiz_search)
- [Location Vocabulary](https://scrappa.co/docs/fincaraiz-api/fincaraiz_location_vocabulary)

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