# Urbania Property Search API Documentation

Search Urbania listings for sale, rent or temporary rent in Peru. Filter by place, property type, price with its currency, bedrooms, bathrooms and covered area, sort by price, date or views and page through the results. Each item has all prices in soles and dollars, fees, bedrooms, bathrooms, areas, parking, address, coordinates, photos, highlights and the advertiser. A page holds up to 30 listings. Development projects appear in every search without room counts and carry is_project true; set exclude_projects to remove them. Every returned item satisfies the filters you set, and data.excluded counts items removed by exclude_projects or by the price check. A valid search with no match is a successful response with an empty list. A page past the last page returns an empty list. An unknown place is a 422 error.

- **Documentation:** [https://scrappa.co/docs/urbania-api/urbania_search](https://scrappa.co/docs/urbania-api/urbania_search)
- **API group:** Urbania API
- **Endpoint:** `GET https://scrappa.co/api/urbania/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 | No | sale, rent or temporary. Defaults to sale. |
| `property_type` | string | No | all, apartment, house, land, office or commercial. Defaults to all. |
| `location` | string | No | Place slug from the slug field of /autocomplete, for example miraflores--lima--lima. Without it the search covers all of Peru. |
| `price_min` | integer | No | Lowest price in the chosen currency. |
| `price_max` | integer | No | Highest price in the chosen currency. |
| `currency` | string | No | PEN or USD for the price filter. Defaults to PEN. |
| `bedrooms_min` | integer | No | Fewest bedrooms. |
| `bedrooms_max` | integer | No | Most bedrooms. |
| `bathrooms_min` | integer | No | Fewest bathrooms. |
| `area_min` | integer | No | Smallest covered area in square metres. |
| `area_max` | integer | No | Largest covered area in square metres. |
| `sort` | string | No | relevance, price_asc, price_desc, newest, most_viewed or price_drop. Price sorts use the price in soles. Defaults to relevance. |
| `exclude_projects` | boolean | No | true removes development projects, which have no room counts. Defaults to false. |
| `page` | integer | No | One-based page number. Defaults to 1. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/urbania/search?operation=sale&property_type=apartment&location=miraflores--lima--lima&bedrooms_min=2&price_min=200000&price_max=400000&currency=USD&exclude_projects=1"
```

## Example response

```json
{
    "success": true,
    "data": {
        "items": [
            {
                "id": 151143469,
                "code": "Sociedad Lu",
                "url": "https://urbania.pe/inmueble/clasificado/veclapin-venta-de-departamento-en-barrio-medico-miraflores-3-dormitorios-151143469",
                "title": "Flat Moderno en Barrio Medico Limite con La Aurora",
                "summary": "Departamento \u00b7 104m\u00b2 \u00b7 3 Dormitorios \u00b7 2 Estacionamientos",
                "operation": "sale",
                "prices": [
                    {
                        "currency": "PEN",
                        "amount": 702000,
                        "formatted": "702,000",
                        "symbol": "S/"
                    },
                    {
                        "currency": "USD",
                        "amount": 208000,
                        "formatted": "208,000",
                        "symbol": "USD"
                    }
                ],
                "expenses": {
                    "currency": "PEN",
                    "amount": 500,
                    "formatted": "500",
                    "symbol": "S/"
                },
                "property_type": "Departamentos",
                "is_project": false,
                "bedrooms": 3,
                "bathrooms": 2,
                "half_bathrooms": 1,
                "parking": 2,
                "area_total": 103,
                "area_covered": 104,
                "age_years": 10,
                "location": {
                    "address": "Calle V\u00edctor Maurtua 166",
                    "latitude": -12.11,
                    "longitude": -77.05
                },
                "publisher": {
                    "id": 102453971,
                    "name": "LA VILLA NUEVA",
                    "type": "agency"
                }
            }
        ],
        "page": 1,
        "per_page": 30,
        "total": 833,
        "total_pages": 28,
        "has_more": true,
        "excluded": {
            "projects": 15,
            "price_mismatch": 0
        }
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A public parameter is missing or invalid, or the location cannot be resolved. The response is not billable. |
| 404 | Resource Not Found | No Urbania resource matches the request. The response is not billable. |
| 503 | Unexpected Upstream Response | Urbania answered with a page in an unexpected format. The response is not billable. |
| 503 | Upstream Unavailable | Urbania 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)