# Casa Sapo Property Search API

<p>Search Casa Sapo properties for sale (`buy`) or rent (`rent`) across Portugal, by distrito, concelho or freguesia. Filter by property type, typology (T0 to T6), price, area and seller type, and sort by price or date. Each listing has its id, clean url, title, price as a number in euros, price drop with the previous price and percentage, area, typology, bedrooms, condition, location with coordinates, the full description, photos and the advertiser (agency name, id, profile url, website and address, or only the type `private`). Private seller names and telephone numbers are never returned. `data.total` is the total Casa Sapo reports for the filters. Pages hold 20 to 28 listings. A page that Casa Sapo does not serve is an empty list. `seller_type` is applied to each page after loading, so a page can hold fewer listings than `per_page`; `filtered_out` says how many were removed. Unknown locations answer 404 and are not billed. Casa Sapo publishes the content signal ai-train=no: do not use this data to train AI models.</p>

- **Documentation:** [https://scrappa.co/docs/casa-sapo-api/casa_sapo_search](https://scrappa.co/docs/casa-sapo-api/casa_sapo_search)
- **API group:** Casa Sapo API
- **Endpoint:** `GET https://scrappa.co/api/casa-sapo/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 |
| --- | --- | --- | --- |
| `operation` | string | Yes | `buy` (or `sale`) or `rent`. |
| `property_type` | string | No | apartamentos, moradias, terrenos, lojas, escritorios, predios, armazens, quintas-e-herdades, imoveis-de-luxo, garagens or quartos. Defaults to apartamentos. |
| `location` | string | No | Location slug from the locations endpoint: a concelho (`lisboa`), a freguesia (`lisboa/santo-antonio`) or a distrito (`distrito.lisboa`). Omit it to search all of Portugal. |
| `bedrooms` | integer | No | Typology T0 to T6 as 0 to 6, where 6 means T6 or larger. Only for apartamentos and moradias. |
| `sort` | string | No | `price_asc`, `price_desc`, `newest`, `oldest` or `most_photos`. The default is Casa Sapo relevance. |
| `price_min` | integer | No | Minimum price in euros (monthly rent for rent). |
| `price_max` | integer | No | Maximum price in euros. Must not be below price_min. |
| `area_min` | integer | No | Minimum area in square meters. |
| `area_max` | integer | No | Maximum area in square meters. Must not be below area_min. |
| `seller_type` | string | No | `private` or `agency`. Applied to each page after loading, so a page can hold fewer listings. |
| `page` | integer | No | Page number, 1-based. |

## Example response

```json
{
    "data": {
        "total": 411,
        "filters": {
            "bedrooms": 3,
            "location": "lisboa",
            "operation": "buy",
            "price_max": 600000,
            "property_type": "apartamentos"
        },
        "listings": [
            {
                "id": "94d94722-10d3-11f1-9e61-060000000056",
                "url": "https://casa.sapo.pt/comprar-apartamento-t3-lisboa-santo-antonio-94d94722-10d3-11f1-9e61-060000000056.html",
                "tags": [
                    "Com Garagem"
                ],
                "g3pid": "1095490",
                "price": 1880000,
                "title": "Apartamento T3 Santo Ant\u00f3nio, Lisboa",
                "images": [
                    "https://media.casasapo.pt/Z1440x1080/OAYES/S5/C5773/P29462664/Tphoto/ID8890c101-0000-0500-0000-00001885c712.JPG"
                ],
                "area_m2": 124,
                "bedrooms": 3,
                "category": "Apartamentos",
                "currency": "EUR",
                "location": {
                    "text": "Santo Ant\u00f3nio, Lisboa, Distrito de Lisboa",
                    "country": "PT",
                    "concelho": "Lisboa",
                    "distrito": "Distrito de Lisboa",
                    "latitude": 38.7235,
                    "freguesia": "Santo Ant\u00f3nio",
                    "longitude": -9.15905
                },
                "typology": "T3",
                "condition": "Recuperado",
                "has_video": true,
                "advertiser": {
                    "id": "14457",
                    "name": "IMOJOY Real Estate",
                    "slug": "imojoy-real-estate",
                    "type": "agency",
                    "address": "Rua dos Sobreiros, 25 C, Costa da Guia, Cascais",
                    "website": "http://imojoy.pt",
                    "profile_url": "https://casa.sapo.pt/agencia/imojoy-real-estate/?cl=14457&sys=5"
                },
                "price_drop": {
                    "percentage": -14.55,
                    "previous_price": 2200000,
                    "previous_price_text": "2.200.000 \u20ac"
                },
                "price_text": "1.880.000 \u20ac",
                "description": "Apresentamos este exclusivo apartamento T3, totalmente reabilitado, situado na prestigiada Rua das Amoreiras, uma das localiza\u00e7\u00f5es mais valorizadas de Lisboa.",
                "seller_type": "agency",
                "transaction": "sale",
                "property_type": "Apartamento T3",
                "has_virtual_tour": true
            }
        ],
        "pagination": {
            "page": 1,
            "per_page": 25,
            "has_next_page": true
        }
    },
    "meta": {
        "billable": true,
        "endpoint_family": "search"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
|  | The listing, agency or location does not exist. This response is not billable. |  |
|  | A parameter or filter is missing or invalid. This response is not billable. |  |
|  | Casa Sapo answered a page that no longer matches the documented contract. This response is not billable. |  |
|  | Casa Sapo is temporarily unavailable. Retry the request. This response is not billable. |  |

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