# Kyero Location Autocomplete API Documentation

Scrappa's `GET /api/kyero/autocomplete` turns a place name into the Kyero location id and slug that the search and agents endpoints need.

## What you get

Each result has `id`, `slug`, `name`, `parent_name` (the province or region), `nation_id`, `country` (`es`, `pt`, `it` or `fr`), `popularity`, the public Kyero paths for sale, rent and agents, and `agents_country`, the country to send to the agents endpoint.

## Filtering by country

Send `country` to restrict the search to Spain, Portugal, Italy or France. Without it, all four countries are searched. The same place name can exist in several countries, so check `country` and `parent_name`.

## Notes

Results are ordered by Kyero. The response is not paginated.

- **Documentation:** [https://scrappa.co/docs/kyero-api/kyero_autocomplete](https://scrappa.co/docs/kyero-api/kyero_autocomplete)
- **API group:** Kyero API
- **Endpoint:** `GET https://scrappa.co/api/kyero/autocomplete`

## 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 |
| --- | --- | --- | --- |
| `q` | string | Yes | Place name, at least 2 characters. |
| `country` | string | No | Optional: es, pt, it or fr. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/kyero/autocomplete?q=marbella&country=es"
```

## Example response

```json
{
    "success": true,
    "query": "marbella",
    "country": "es",
    "returned": 1,
    "results": [
        {
            "id": 31673,
            "slug": "marbella",
            "name": "Marbella",
            "parent_name": "Malaga",
            "nation_id": 55529,
            "country": "es",
            "popularity": 4018,
            "for_sale_path": "/en/marbella-property-for-sale-0l31673",
            "to_rent_path": "/en/marbella-property-long-let-1l31673",
            "agents_path": "/en/spain/estate-agents/marbella-l31673",
            "agents_country": "es"
        }
    ],
    "meta": {
        "billable": true,
        "attempts": 1,
        "last_status": 200,
        "endpoint_family": "autocomplete"
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter failed validation, or a path, id or slug is unusable (`invalid_parameter`). Non-billable. |
| 503 | Upstream Unavailable | Kyero could not be reached after retries, answered a different page than requested, did not apply the filters, or answered with a body this API cannot read (`upstream_unavailable`, `upstream_blocked`, `pagination_mismatch`, `filter_not_honoured`, `parser_drift`). Retryable and never billed. Clients are never rate limited. |

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