# Yad2 Real Estate Search API Documentation

Search public Yad2 real-estate listings for sale or for rent in one region, with price, rooms, floor, size, property type and sorting filters and one-based paging. Each listing carries its token, advertiser type, numeric price in Israeli shekels with the ILS currency, the full address with coordinates, the property details, every image, the marketing tags and the public web url. Promoted listings that are ordinary ads (platinum, trio, booster and king of the har) ride along in buckets. A page past the end of the result set is a successful, billable answer.

- **Documentation:** [https://scrappa.co/docs/yad2-api/yad2_search](https://scrappa.co/docs/yad2-api/yad2_search)
- **API group:** Yad2 API
- **Endpoint:** `GET https://scrappa.co/api/yad2/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 |
| --- | --- | --- | --- |
| `deal` | string | Yes | forsale for the sale feed or rent for the rental feed. Required. |
| `region` | integer | Yes | Region id from the regions endpoint, for example 2 for the south or 8 for Jerusalem. Required. |
| `page` | integer | No | 1-based page number. Defaults to 1. The gateway returns 20 private and 20 agency listings per page. |
| `minPrice` | integer | No | Lower price bound in Israeli shekels. |
| `maxPrice` | integer | No | Upper price bound in Israeli shekels. |
| `minRooms` | number | No | Lower bound on the room count, decimals allowed (3.5). |
| `maxRooms` | number | No | Upper bound on the room count. |
| `minSquaremeter` | number | No | Lower bound on the built area in square meters. |
| `maxSquaremeter` | number | No | Upper bound on the built area in square meters. |
| `minSquareMeterBuild` | number | No | Lower bound on the built area excluding the garden, in square meters. |
| `maxSquareMeterBuild` | number | No | Upper bound on the built area excluding the garden, in square meters. |
| `minFloor` | number | No | Lower bound on the floor, -1 for a basement. |
| `maxFloor` | number | No | Upper bound on the floor. |
| `property` | integer | No | Property type id from the property facet, for example 1 for an apartment, 5 for a private house or 33 for a plot. |
| `propertyCondition` | integer | No | Property condition id from the property facet rows. |
| `sort` | integer | No | Sort order id as used by the Yad2 feed. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/yad2/search?deal=forsale&region=2&page=1"
```

## Example response

```json
{
    "success": true,
    "data": {
        "deal": "forsale",
        "region": 2,
        "listings": [
            {
                "token": "hei3dmp5",
                "order_id": 57601142,
                "ad_type": "private",
                "category_id": 2,
                "subcategory_id": 1,
                "price": 1950000,
                "currency": "ILS",
                "address": {
                    "region": {
                        "id": "2",
                        "text": "\u05d3\u05e8\u05d5\u05dd"
                    },
                    "area": {
                        "text": "\u05d0\u05d6\u05d5\u05e8 \u05d0\u05e9\u05d3\u05d5\u05d3, \u05d0\u05e9\u05e7\u05dc\u05d5\u05df \u05d5\u05d4\u05e1\u05d1\u05d9\u05d1\u05d4"
                    },
                    "city": {
                        "id": "7100",
                        "text": "\u05d0\u05e9\u05e7\u05dc\u05d5\u05df"
                    },
                    "neighborhood": {
                        "id": "471",
                        "text": "\u05d1\u05e8\u05e0\u05e2"
                    },
                    "street": {
                        "text": "\u05d9\u05d5\u05e0\u05ea\u05df \u05e0\u05ea\u05e0\u05d9\u05d4\u05d5"
                    },
                    "house": {
                        "number": 8,
                        "floor": 10
                    },
                    "coords": {
                        "lat": 31.688916,
                        "lon": 34.578495
                    }
                },
                "details": {
                    "property": {
                        "text": "\u05d3\u05d9\u05e8\u05d4"
                    },
                    "property_condition": {
                        "id": "2"
                    },
                    "rooms_count": 4,
                    "square_meter": 120
                },
                "cover_image": "https://img.yad2.co.il/Pic/202610/10/2_1/o/y2_1pa_010545_20261010223138.jpeg",
                "images": [
                    "https://img.yad2.co.il/Pic/202610/10/2_1/o/y2_1pa_010545_20261010223138.jpeg",
                    "https://img.yad2.co.il/Pic/202610/10/2_1/o/y2_1pa_010921_20261010223139.jpeg"
                ],
                "tags": [
                    {
                        "name": "\u05d7\u05e0\u05d9\u05d4",
                        "id": 903,
                        "priority": 1
                    },
                    {
                        "name": "\u05de\u05de\"\u05d3",
                        "id": 909,
                        "priority": 1
                    }
                ],
                "web_url": "https://www.yad2.co.il/item/hei3dmp5"
            }
        ],
        "buckets": {
            "platinum": [
                {
                    "token": "d3jocwiu",
                    "ad_type": "commercial",
                    "price": 1100000,
                    "currency": "ILS",
                    "web_url": "https://www.yad2.co.il/item/d3jocwiu"
                }
            ]
        },
        "pagination": {
            "page": 1,
            "total": 16891,
            "total_pages": 702,
            "has_more": true
        }
    },
    "meta": {
        "endpoint_family": "search",
        "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)