# Fincaraiz Location Geometry API Documentation

Scrappa's `GET /api/fincaraiz/location-geometry` returns the polygon boundaries for one or more Colombian locations, ready to draw a region on a map.

Pass the ids you already have from location-autocomplete; several can be requested in one call by comma-separating them. Each result carries `multi_polygon` plus the location `id`, `name`, and `type`.

The list is bounded: at most 200 characters of comma-separated alphanumeric ids, and anything else is rejected with a `422` before the lookup rather than sent upstream.

Boundary payloads are large — a city outline is roughly a megabyte — so request only the regions you will actually draw. Ids that do not resolve are omitted from the response rather than failing the whole call.

- **Documentation:** [https://scrappa.co/docs/fincaraiz-api/fincaraiz_location_geometry](https://scrappa.co/docs/fincaraiz-api/fincaraiz_location_geometry)
- **API group:** Fincaraiz API
- **Endpoint:** `GET https://scrappa.co/api/fincaraiz/location-geometry`

## 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 |
| --- | --- | --- | --- |
| `ids` | string | Yes | One or more location UUIDs from location-autocomplete, comma-separated. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/fincaraiz/location-geometry?ids=183f0a11-0000-4000-8000-000000000000"
```

## Example response

```json
{
    "success": true,
    "requested_ids": [
        "183f0a11-0000-4000-8000-000000000000"
    ],
    "returned": 1,
    "geometries": [
        {
            "id": "183f0a11-0000-4000-8000-000000000000",
            "name": "Medellin",
            "type": "CITY",
            "multi_polygon": {
                "coordinates": [
                    [
                        [
                            -75.7,
                            6.1
                        ],
                        [
                            -75.6,
                            6.2
                        ]
                    ]
                ]
            }
        }
    ],
    "meta": {
        "billable": true,
        "endpoint_family": "location-geometry",
        "attempts": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | No ids were supplied. 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 boundaries (`parser_drift`). Nothing is charged for it. Retryable. |

## Frequently asked questions

### Where do the ids come from?

From location-autocomplete. Each result there carries an id that is valid for this endpoint.

### Why is the response so large?

Boundary polygons describe every contour of the region. A single city outline is around a megabyte, so request only the regions you render.

## Related endpoints

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