# Supercasa Search

Search homes for sale and rent on Supercasa, Portugal's national property portal, including new-build developments.

- **Documentation:** [https://scrappa.co/docs/supercasa-api/supercasa_search](https://scrappa.co/docs/supercasa-api/supercasa_search)
- **API group:** Supercasa API
- **Endpoint:** `GET https://scrappa.co/api/supercasa/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 |
| --- | --- | --- | --- |
| `location` | string | No | Place name to search, e.g. Lisboa, Porto or Caldas da Rainha. |
| `location_level` | string | No | How to interpret the location: state, town, neighborhood or zone. Sent only when you supply it — a level sent with an ambiguous name resolves to no match instead of the disambiguation options, so leaving it unset is what gets you those options and a selection token. |
| `business` | string | No | sale (default), rent or holiday_rent. |
| `category` | string | No | Search profile. property (default) covers the full filter set, rooms adds room preferences, new_construction covers empreendimentos. |
| `category_ids[]` | array | No | Specific category ids from the filters endpoint. |
| `min_price` | number | No | Minimum asking price in EUR. |
| `max_price` | number | No | Maximum asking price in EUR. |
| `min_area` | number | No | Minimum area in m². |
| `max_area` | number | No | Maximum area in m². |
| `min_bedrooms` | integer | No | Minimum bedroom count. |
| `max_bedrooms` | integer | No | Maximum bedroom count. |
| `bathrooms` | integer | No | Minimum bathroom count. |
| `condition` | integer | No | Condition id from the filters endpoint. |
| `features[]` | array | No | Feature names from the filters endpoint, e.g. elevador. |
| `sort` | string | No | relevance (default), newest, price_asc or price_desc. |
| `page` | integer | No | Result page, 1 to 75. Each page holds 25 listings, so a single query tops out at 1,875 results. |
| `location_selection_token` | string | No | Opaque token from the autocomplete endpoint. Pass it instead of location — never alongside it — to resume an unambiguous search. Either this or location is required. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/supercasa/search?location=Lisboa&business=sale&category=property&max_price=350000&page=1"
```

## Example response

```json
{
    "success": true,
    "listingId": 2165197,
    "listingReference": "SuperCasa QRHR2395",
    "title": "Apartamento T2 \u00e0 venda em Benfica",
    "propertyType": "Apartamento",
    "condition": "Renovado",
    "business": "Comprar",
    "price": 395000,
    "location": "Benfica, Lisboa",
    "bedrooms": 2,
    "bathrooms": 2,
    "grossAreaSqm": 120,
    "firstPhoto": "https://images.egorealestate.com/Z720x540/S5/C10197/P29637360/Tphoto/IDf03ac401.jpg",
    "url": "https://supercasa.pt/venda-apartamento-t2-lisboa/i2165197"
}
```

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