# Aqar Search API Documentation

<p><strong>Aqar Search API</strong> returns Saudi properties for sale or for rent as JSON, up to 50 per page. Choose <code>listing_type</code> and <code>property_type</code> (apartment, villa, land, floor, building, shop, rest_house, farm, office, warehouse, room), or send a raw <code>category_id</code>. Filter by city, district, price, area, bedrooms, bathrooms, living rooms, street width, building age, furnished state, rent period and keyword, sort by price or area, and page through the results. Every item has the price in SAR, area, rooms, location, photos at three widths, the description in Arabic and English and the advertiser with an <code>id</code> for the agent route.</p><p><strong>Filters are never ignored.</strong> If Aqar returns an ad that breaks a requested filter, the request fails and is not billed. A page is never labelled as another page: the response carries <code>page</code>, <code>size</code>, <code>from</code> and the real <code>total</code>. Aqar ranking shifts between calls, so an ad can show on two neighbouring pages. Results are available up to position 12000.</p><p><strong>Not offered.</strong> Sorting by newest or by bedrooms is refused with a 422 error, because Aqar does not honour it. An implausible area value is returned as <code>null</code>. Phone numbers are never returned. Failed requests are not billed.</p>

- **Documentation:** [https://scrappa.co/docs/aqar-api/aqar_search](https://scrappa.co/docs/aqar-api/aqar_search)
- **API group:** Aqar API
- **Endpoint:** `GET https://scrappa.co/api/aqar/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 |
| --- | --- | --- | --- |
| `listing_type` | string | No | sale (default) or rent. |
| `property_type` | string | No | apartment (default), villa, land, floor, building, shop, rest_house, farm, office, warehouse or room. Not every type exists for both sale and rent. |
| `category_id` | integer | No | Raw Aqar category id, instead of listing_type and property_type. |
| `city_id` | integer | No | City id from autocomplete. |
| `district_id` | integer | No | District id from autocomplete. |
| `min_price` | integer | No | Minimum price in SAR (rent: per rent period). |
| `max_price` | integer | No | Maximum price in SAR. |
| `min_area` | integer | No | Minimum area in square meters. |
| `max_area` | integer | No | Maximum area in square meters. |
| `min_beds` | integer | No | Minimum bedrooms. |
| `min_baths` | integer | No | Minimum bathrooms. |
| `min_living_rooms` | integer | No | Minimum living rooms. |
| `min_street_width` | integer | No | Minimum street width in meters. |
| `max_age` | integer | No | Maximum building age in years. |
| `furnished` | boolean | No | true for furnished, false for unfurnished. |
| `rent_period` | string | No | monthly or yearly. Rent only. |
| `keyword` | string | No | Word to find in the ad text, Arabic or English. |
| `sort` | string | No | price_asc, price_desc, area_asc or area_desc. Default: Aqar ranking. |
| `page` | integer | No | One-based page number (default 1). |
| `size` | integer | No | Results per page, 1 to 50 (default 20). |

## Example response

```json
{
    "data": {
        "items": [
            {
                "id": 6908541,
                "age": 0,
                "url": "https://sa.aqar.fm/ad/6908541",
                "area": 182,
                "price": {
                    "value": 500000,
                    "currency": "SAR"
                },
                "images": [
                    {
                        "large": "https://images.aqar.fm/webp/1200x0/props/055115056_1791368464635.jpg",
                        "small": "https://images.aqar.fm/webp/350x0/props/055115056_1791368464635.jpg",
                        "medium": "https://images.aqar.fm/webp/750x0/props/055115056_1791368464635.jpg"
                    }
                ],
                "city_id": 21,
                "bedrooms": 5,
                "location": {
                    "latitude": 24.549226,
                    "longitude": 46.801222
                },
                "bathrooms": 2,
                "furnished": false,
                "published": true,
                "unit_code": null,
                "advertiser": {
                    "id": 5217711,
                    "name": "Test Advertiser",
                    "avatar": null,
                    "rating": null,
                    "paid_member": true
                },
                "created_at": "2026-10-06T22:50:02Z",
                "category_id": 6,
                "description": "\u0644\u0644\u0628\u064a\u0639 \u0641\u064a\u0644\u0627 \u062a\u0627\u0648\u0646 \u0647\u0627\u0648\u0633 \u0639\u0644\u0648\u064a \u0628\u062d\u064a \u0637\u064a\u0628\u0647 \n\u0645\u0633\u0627\u062d\u0647 257\n\u0627\u0644\u0633\u0639\u0631 500\u0627\u0644\u0641 ............\n....\u2026",
                "district_id": 684,
                "meter_price": null,
                "rent_period": null,
                "listing_type": "sale",
                "living_rooms": 2,
                "street_width": null,
                "property_type": "apartment",
                "description_en": "townhouse villa for sale in taybah district\narea: 257\nprice: 500k ............\n....\u2026"
            }
        ],
        "pagination": {
            "from": 0,
            "page": 1,
            "size": 1,
            "total": 3935,
            "total_pages": 3935,
            "has_next_page": true
        },
        "applied_filters": {
            "sort": "price_asc",
            "city_id": 21,
            "min_beds": 3,
            "max_price": 900000,
            "category_id": 6,
            "listing_type": "sale",
            "property_type": "apartment"
        }
    },
    "meta": {
        "billable": true,
        "endpoint_family": "search"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A required parameter or a range is invalid. This response is not billable. |
| 503 | Upstream Unavailable | Aqar could not be reached or returned data that does not match the request. This response is not billable and is retryable. |

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