# MagicBricks Filters API Documentation

Read the filter grammar for one city and category: the filter categories, the property type codes with their labels, and the possession options with their codes. The upstream search page publishes its filter category menu but not every option list on a live fetch, so an option list with no live source is omitted rather than fabricated; the categories are always returned. The payload is cached for six hours.

- **Documentation:** [https://scrappa.co/docs/magicbricks-api/magicbricks_filters](https://scrappa.co/docs/magicbricks-api/magicbricks_filters)
- **API group:** MagicBricks API
- **Endpoint:** `GET https://scrappa.co/api/magicbricks/v1/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 |
| --- | --- | --- | --- |
| `city` | string | Yes | City ref-no such as 4320 for Mumbai, or a city name resolved against /cities. Example: Mumbai. |
| `category` | string | No | buy or rent. Defaults to buy. |
| `property_type` | string | No | Optional property type name or numeric code to narrow the returned options. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/magicbricks/v1/filters?city=Mumbai&category=buy"
```

## Example response

```json
{
    "success": true,
    "data": {
        "city": "Mumbai",
        "category": "buy",
        "categories": [
            {
                "key": "Locality",
                "title": "Top Localities"
            },
            {
                "key": "Budget",
                "title": "Budget"
            },
            {
                "key": "PropertyType",
                "title": "Property Type"
            },
            {
                "key": "Bhk",
                "title": "BHK"
            },
            {
                "key": "InputListings",
                "title": "Posted By"
            }
        ],
        "property_types": [
            {
                "code": 10002,
                "label": "Multistorey Apartment"
            },
            {
                "code": 10001,
                "label": "Residential House"
            },
            {
                "code": 10000,
                "label": "Residential Plot"
            },
            {
                "code": 10003,
                "label": "Builder Floor Apartment"
            }
        ],
        "possession_options": [
            {
                "code": "10081",
                "label": "Ready To Move"
            },
            {
                "code": "2026",
                "label": "2026"
            }
        ]
    },
    "meta": {
        "endpoint_family": "filters",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A public parameter is missing or invalid, or a city, locality or property type cannot be resolved. No upstream call is made and the response is not billable. |
| 404 | Resource Not Found | The requested MagicBricks resource does not exist. The response is not billable. |
| 503 | Unexpected Upstream Response | MagicBricks answered with a body that is not the documented shape. The response is not billable. |
| 503 | Upstream Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

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