# Square Yards Property Search API Documentation

Search property listings in one Indian city for sale or rent. Filter by bedrooms, property type, locality, price range and area range, sort by price and page through the results. Each item carries the price in rupees and as displayed, bedrooms, bathrooms, area, property type, status, furnishing, facing, floor, locality with its id, coordinates, photos, highlights and the agent. A page holds up to 25 listings, and some pages hold fewer because project cards, repeated listings and listings that break your filters are removed (per_page is an upper bound). Every returned item satisfies the filters you set. A valid search with no match is a successful response with an empty list. An unknown city, property type, bedroom value or sort is a 422 error.

- **Documentation:** [https://scrappa.co/docs/squareyards-api/squareyards_search](https://scrappa.co/docs/squareyards-api/squareyards_search)
- **API group:** Square Yards API
- **Endpoint:** `GET https://scrappa.co/api/squareyards/v1/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 |
| --- | --- | --- | --- |
| `city` | string | Yes | City id or city name from /cities. Example: Mumbai. |
| `category` | string | No | buy for sale listings or rent for rentals. Defaults to buy. |
| `bedrooms` | string | No | Bedroom count such as 2, or an exact label from /filters such as 2 BHK, 1 RK or Studio. |
| `property_type` | string | No | Property type name or id from /filters, for example Apartment, Villa, Office Space or 9. |
| `locality` | integer | No | Locality id from /autocomplete (the locality_id of a locality item), for example 65173 for Andheri West. |
| `min_price` | integer | No | Lowest price in rupees. For rent this is the monthly rent. |
| `max_price` | integer | No | Highest price in rupees. For rent this is the monthly rent. |
| `min_area` | integer | No | Smallest area in square feet. |
| `max_area` | integer | No | Largest area in square feet. |
| `sort` | string | No | price_asc or price_desc. Without it the site relevance order applies. |
| `page` | integer | No | One-based page number. Defaults to 1. A page past the last page returns an empty list. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/squareyards/v1/search?city=Mumbai&category=buy&bedrooms=2&min_price=10000000&max_price=20000000&sort=price_asc"
```

## Example response

```json
{
    "success": true,
    "data": {
        "items": [
            {
                "id": 9306882,
                "url": "https://www.squareyards.com/resale-2-bhk-650-sq-ft-apartment-in-ashford-royale/9306882",
                "title": "2 BHK Apartment For Sale in Ashford Royale",
                "listing_type": "sale",
                "project_name": "Ashford Royale",
                "price": 18200000,
                "price_display": "\u20b9 1.82 Cr",
                "currency": "INR",
                "price_period": null,
                "unit_type": "2 BHK",
                "bedrooms": 2,
                "bathrooms": 2,
                "area": 650,
                "area_unit": "sqft",
                "property_type": "Apartment",
                "status": "Under Construction",
                "possession_status": "Under Construction",
                "furnishing": "Unfurnished",
                "facing": "West",
                "floor": null,
                "view": null,
                "flooring": null,
                "parking": "1 Covered Parking",
                "city": "Mumbai",
                "locality": "Nahur",
                "locality_id": 2823,
                "latitude": 19.157592,
                "longitude": 72.94506,
                "image": "https://img.squareyards.com/secondaryPortal/IN_638960510924149900-141025030452452.jpg",
                "images": [
                    "https://img.squareyards.com/secondaryPortal/IN_638960510924149900-141025030452452.jpg"
                ],
                "highlights": [
                    "Reputed Builder",
                    "Peaceful Vicinity"
                ],
                "agent": {
                    "id": 331378,
                    "name": "YOGESH BAPU GHADIGAONKAR",
                    "type": "CP",
                    "rating": null,
                    "experience_years": 7,
                    "premium": false,
                    "location": "Mumbai",
                    "image": null,
                    "slug": "yogesh-bapu-ghadigaonkar"
                }
            }
        ],
        "page": 1,
        "per_page": 25,
        "total": 7838,
        "has_more": true
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A public parameter is missing or invalid, or a city, property type, bedroom value or sort cannot be resolved. The response is not billable. |
| 404 | Resource Not Found | The requested Square Yards resource does not exist. The response is not billable. |
| 503 | Unexpected Upstream Response | Square Yards answered with a body that is not the documented shape. The response is not billable. |
| 503 | Upstream Unavailable | Square Yards was temporarily unavailable or blocked the request. The response is not billable and the request never answers 429. |

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