# Yad2 Search Filters API Documentation

Return the live Yad2 search facets for one deal. Each requested field comes back as a list of rows with the display text, the value to send back to the search endpoint, and the facet group or breadcrumb trail where the gateway provides one. Ask for city, area, property and rooms by default, or name any other field the Yad2 app uses. A field the gateway does not know comes back as an empty list, which is a successful, billable answer.

- **Documentation:** [https://scrappa.co/docs/yad2-api/yad2_filters](https://scrappa.co/docs/yad2-api/yad2_filters)
- **API group:** Yad2 API
- **Endpoint:** `GET https://scrappa.co/api/yad2/filters`

## 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 |
| --- | --- | --- | --- |
| `deal` | string | Yes | forsale or rent. Required. |
| `fields` | string | No | Comma-separated facet names, up to 12. Defaults to city,area,property,rooms. Without a field list the gateway answers an empty result. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/yad2/filters?deal=forsale&fields=city%2Carea%2Cproperty%2Crooms"
```

## Example response

```json
{
    "success": true,
    "data": {
        "deal": "forsale",
        "facets": {
            "city": [
                {
                    "text": "\u05de\u05d1\u05e9\u05e8\u05ea \u05e6\u05d9\u05d5\u05df",
                    "value": "1015",
                    "breadcrumbs": [
                        "\u05de\u05d7\u05d5\u05d6 \u05d9\u05e8\u05d5\u05e9\u05dc\u05d9\u05dd",
                        "\u05d0\u05d6\u05d5\u05e8 \u05d4\u05e8\u05d9 \u05d9\u05d4\u05d5\u05d3\u05d4, \u05de\u05d1\u05e9\u05e8\u05ea \u05d5\u05d4\u05e1\u05d1\u05d9\u05d1\u05d4"
                    ]
                },
                {
                    "text": "\u05d0\u05d5\u05e8 \u05e2\u05e7\u05d9\u05d1\u05d0",
                    "value": "1020",
                    "breadcrumbs": [
                        "\u05d7\u05d3\u05e8\u05d4, \u05d6\u05db\u05e8\u05d5\u05df \u05d5\u05d4\u05e2\u05de\u05e7\u05d9\u05dd",
                        "\u05d0\u05d6\u05d5\u05e8 \u05e7\u05d9\u05e1\u05e8\u05d9\u05d4 \u05d5\u05d4\u05e1\u05d1\u05d9\u05d1\u05d4"
                    ]
                }
            ],
            "area": [
                {
                    "text": "\u05e6\u05e4\u05d5\u05df",
                    "value": "25"
                },
                {
                    "text": "\u05d0\u05d6\u05d5\u05e8 \u05d7\u05d9\u05e4\u05d4 \u05d5\u05d4\u05e1\u05d1\u05d9\u05d1\u05d4",
                    "value": "5"
                }
            ],
            "property": [
                {
                    "text": "\u05d3\u05d9\u05e8\u05d4",
                    "value": "1",
                    "group": "apartments",
                    "advanced_search": false
                },
                {
                    "text": "\u05d3\u05d9\u05e8\u05ea \u05d2\u05df",
                    "value": "3",
                    "group": "apartments",
                    "advanced_search": false
                }
            ],
            "rooms": []
        }
    },
    "meta": {
        "endpoint_family": "filters",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 503 | Yad2 Upstream Unavailable | Yad2 could not be reached for this request after the attempt budget. Never charged. |
| 503 | Yad2 Refused | Yad2 refused every attempt for this request instead of answering with data. The response is never charged. |
| 422 | Invalid Parameter | Yad2 refused a value in this request. The request is never forwarded upstream and is never charged. |
| 502 | Parser Drift | Yad2 answered with a payload this parser does not recognise. The incident has been reported; retrying returns the same body. |

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