# Kyero Property Search API Documentation Scrappa's `GET /api/kyero/search` returns Kyero property listings for sale or rent in Spain, Portugal, Italy and France as structured JSON. Get `location_id` and `location_slug` from the autocomplete endpoint. ## What you get One request returns one page of up to 20 listings. Each listing has `id`, `name`, `price`, `price_formatted`, `reference_no`, `bedrooms`, `bathrooms`, `built_m2`, `plot_m2`, `property_type`, `short_description`, `images`, `feature_keys`, `badges`, video and virtual tour links, the listing `agent`, and the `path` that the property endpoint takes. The response also has `location` with its parent places, `pagination`, `available_filters` and `alternate_searches` (nearby and parent places with their ids). ## Filters are honoured Kyero silently ignores filter values that are not in its own lists. This API rejects such values with a `422` (`unsupported_filter_value`) before any lookup, and the rejection is not billed. Allowed values: prices from `available_filters.price` (sale and rent have different lists), rooms 1-10, built area 50, 100, 150 or 200 m2. Every returned listing is also checked against the filters you sent. A listing that breaks a filter is removed and never returned. `applied_filters` shows what was applied. ## Pagination `page` runs from 1 to 50 with 20 listings per page, so at most 1,000 listings per search are reachable. `pagination.count` is the full match count and `pagination.reachable` is the part you can page through. Narrow the search with filters or a smaller location to reach the rest. A page above 50 returns a non-billable `422`. The response never returns one page's data under another page number. ## Property types `property_type` accepts `any`, `apartments` or `villas`. Town houses and country houses are not available yet. ## Coordinates and fees Kyero does not publish the exact position of a listing. The property endpoint returns the town centre and says so in `coordinates_precision`. Kyero publishes no fee fields and no price history. - **Documentation:** [https://scrappa.co/docs/kyero-api/kyero_search](https://scrappa.co/docs/kyero-api/kyero_search) - **API group:** Kyero API - **Endpoint:** `GET https://scrappa.co/api/kyero/search` ## 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 | | --- | --- | --- | --- | | `location_id` | integer | Yes | Location id from the autocomplete endpoint. | | `location_slug` | string | Yes | Location slug from the autocomplete endpoint. | | `operation` | string | No | sale (default) or rent. | | `property_type` | string | No | any (default), apartments or villas. | | `min_price` | integer | No | A step from available_filters.price. Sale: 50000 to 20000000. Rent per month: 250 to 8000. | | `max_price` | integer | No | A step from available_filters.price. | | `min_beds` | integer | No | 1 to 10. | | `max_beds` | integer | No | 1 to 10. | | `min_baths` | integer | No | 1 to 10. | | `max_baths` | integer | No | 1 to 10. | | `min_build_size` | integer | No | In m2: 50, 100, 150 or 200. | | `max_build_size` | integer | No | In m2: 50, 100, 150 or 200. | | `features` | string | No | Comma-separated, all required: pool, garage, terrace, garden, parking, disabled_access, lift, near_beach, near_shops, near_golf, near_transport. | | `new_build` | boolean | No | true to return new builds only. | | `resale_only` | boolean | No | true to return resale properties only. Cannot be combined with new_build. | | `sort` | string | No | price_asc, price_desc or newest. Without it Kyero uses its default order. | | `page` | integer | No | Result page, 1 to 50. | ## Example request ```bash #!/bin/bash curl -X GET \ -H "x-api-key: YOUR_API_KEY_HERE" \ "https://scrappa.co/api/kyero/search?location_id=31673&location_slug=marbella&operation=sale&min_beds=3&max_price=500000&sort=price_asc" ``` ## Example response ```json { "success": true, "location": { "id": 31673, "name": "Marbella", "slug": "marbella", "type": "City", "name_with_country": "Marbella, Spain", "nation_id": 55529, "country": "es", "latitude": 36.50978, "longitude": -4.88525, "hierarchy": [ { "id": 29, "name": "Malaga", "slug": "malaga", "type": "Province" } ] }, "operation": "sale", "applied_filters": { "operation": "sale", "property_type": "any", "sort": "price_asc", "min_beds": 3, "max_price": 500000 }, "listings": [ { "id": 21361013, "name": "Apartment in Marbella, Malaga", "price": 350000, "price_formatted": "\u20ac 350,000", "payment_scheme": "for_sale", "reference_no": "EI-AC2137", "location_id": 31673, "property_type": { "id": 1, "key": "apartment", "group_id": 1 }, "bedrooms": 3, "bathrooms": 2, "built_m2": 100, "plot_m2": 0, "short_description": "Discover a collection of 34 extraordinary apartments and penthouses...", "images": [ "https://img.kyero.com/crop/960x720/properties/21361/21361013/428410368.jpg" ], "images_count": 31, "feature_keys": [ "garage", "lift", "terrace", "pool", "new_build" ], "badges": [ "video_tour", "remote_viewing" ], "primary_badge": "new_build", "featured": false, "virtual_tour_url": null, "video_url": "https://vimeo.com/1025703918", "remote_viewing_enabled": true, "agent": { "id": 14222, "name": "Example Agency", "logo_url": "https://img.kyero.com/fit/125x125/agents/logos/14/14222.jpg", "type": "2", "prime": true, "path": "/en/spain/estate-agents/profile/example-agency-a14222", "url": "https://www.kyero.com/en/spain/estate-agents/profile/example-agency-a14222" }, "path": "/en/property/21361013-apartment-for-sale-marbella", "url": "https://www.kyero.com/en/property/21361013-apartment-for-sale-marbella" } ], "pagination": { "page": 1, "pages": 8, "per_page": 20, "count": 143, "reachable": 143, "max_pages": 50, "has_next": true }, "available_filters": { "price": [ 50000, 75000, 100000 ], "beds": [ 1, 2, 3 ], "baths": [ 1, 2, 3 ], "build_size": [ 50, 100, 150, 200 ], "features": [ "pool", "garage" ], "location_features": [ "near_beach" ], "multimedia": [ "remote_viewing", "video", "virtual_tour" ] }, "alternate_searches": { "locations_nearby": [ { "label": "Estepona", "location_id": 31466, "location_slug": "estepona", "path": "/en/estepona-property-for-sale-0l31466" } ] }, "title": "Properties for sale in Marbella", "meta": { "billable": true, "attempts": 1, "last_status": 200, "endpoint_family": "search", "dropped_by_guard": 0 } } ``` ## Errors | Status | Error | Description | | --- | --- | --- | | 422 | Unsupported Filter Value or Page | A price, room or size value that Kyero does not offer, an unusable parameter, or a page above 50 (`unsupported_filter_value`, `invalid_parameter`, `page_out_of_range`). Kyero ignores unknown values, so they are rejected before any lookup. Non-billable. | | 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)