# Spotahome Rental Search API Documentation Search Spotahome rentals in one city: for each listing the position, id, title, public url, type, property type, monthly price (the lowest price; max_price is set when the listing has a price range), currency, first available date (YYYY-MM-DD), bills, bedrooms, bathrooms, area, instant booking, deposit flags, address, coordinates, photos, rating and a plain-text description. Pages hold 48 listings. Use total_pages, has_more and next_page to walk the results. A valid search with no matching listings is a successful response with an empty listings array. An unknown city returns 404 and is not billed. - **Documentation:** [https://scrappa.co/docs/spotahome-api/spotahome_search](https://scrappa.co/docs/spotahome-api/spotahome_search) - **API group:** Spotahome API - **Endpoint:** `GET https://scrappa.co/api/spotahome/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 slug as used by Spotahome, lowercase letters, numbers and hyphens. Example: madrid. | | `country` | string | Yes | Country slug as used by Spotahome, lowercase letters, numbers and hyphens. Example: spain. | | `page` | integer | No | Page number, 1 to 1000. Defaults to 1. A page past the last page returns an empty listings array. | | `min_price` | integer | No | Lowest monthly price in the city currency. Send together with max_price. Example: 500. | | `max_price` | integer | No | Highest monthly price in the city currency. Send together with min_price. Example: 900. | | `type` | string | No | One of rooms, apartments, studios, residences. Example: studios. | | `move_in` | string | No | Earliest move-in date as YYYY-MM-DD, not in the past and at most two years ahead. Example: 2026-12-01. | ## Example request ```bash #!/bin/bash curl -X GET \ -H "x-api-key: YOUR_API_KEY_HERE" \ "https://scrappa.co/api/spotahome/search?city=madrid&country=spain" ``` ## Example response ```json { "success": true, "data": { "city": { "id": "madrid", "name": "Madrid", "country_code": "ES", "currency": "EUR" }, "total_results": 9704, "total_pages": 203, "page": 1, "has_more": true, "listings": [ { "position": 1, "id": "80504", "title": "Room in shared apartment for rent in Gaztambide, Madrid", "url": "https://www.spotahome.com/madrid/for-rent:rooms/80504", "type": "room_shared", "property_type": "rooms", "price": 660, "currency": "EUR", "available_from": "2027-01-31", "bills_included": "none", "bedrooms": 5, "bathrooms": 2, "is_instant_booking": false, "is_checked": true, "no_security_deposit": false, "has_deposit_protection": false, "address": { "street": "Guzman el Bueno", "postal_code": "28015", "city": "Madrid" }, "latitude": 40.43137, "longitude": -3.71313, "main_photo_url": "https://photos.spotahome.com/smw_768/11f7eb0b4a5bf48d04be29239ad3f231f75e0b0d1b11b3df3845577a.jpg", "photo_urls": [ "https://photos.spotahome.com/smww_768_verified_ur_6_50/11f7eb0b4a5bf48d04be29239ad3f231f75e0b0d1b11b3df3845577a.jpg", "https://photos.spotahome.com/smww_768_verified_ur_6_50/e238b2f85a0f1e4fa4c6404e98689ae31dbe41290f748f7ec451af8a.jpg" ], "description": "This spacious and well-furnished room is located in a shared 5-bedroom apartment in the Gaztambide neighborhood of Madrid. The apartment includes features such as a private washing machine, equipped kitchen with an oven, heating system, and a television for tenant use. Spotahome has personally checked and verified this property." }, { "position": 2, "id": "130400", "title": "Cozy room in 12-bedroom apartment in Atocha, Madrid", "url": "https://www.spotahome.com/madrid/for-rent:rooms/130400", "type": "room_shared", "property_type": "rooms", "price": 850, "currency": "EUR", "available_from": "2026-10-15", "bills_included": "all", "bedrooms": 12, "bathrooms": 1, "is_instant_booking": false, "is_checked": true, "no_security_deposit": false, "has_deposit_protection": false, "address": { "street": "Calle de Atocha, 43, 28012 Madrid, Spain", "postal_code": "28012", "city": "Madrid" }, "latitude": 40.41396, "longitude": -3.7012, "main_photo_url": "https://photos.spotahome.com/smww_768_verified_ur_6_50/88b056d37e1fdefe01f9c8c08a96796a66c275d6cdf2cc5d36094dac.jpg", "photo_urls": [ "https://photos.spotahome.com/smww_768_verified_ur_6_50/88b056d37e1fdefe01f9c8c08a96796a66c275d6cdf2cc5d36094dac.jpg", "https://photos.spotahome.com/smww_768_verified_ur_6_50/3f0c9167c52cdabcc5120891525e3c65181906f55186ca31d480ce21.jpg" ], "description": "Rooms are available for rent in a 12-bedroom shared apartment in the Central Zone of Madrid. All rooms come with a desk, lamp and a wardrobe. There are two communal areas, a kitchen that is fully equipped for the house capacity and a living area. The kitchen has sufficient space to socialise and relax with your friends or other housemates." } ], "next_page": 2 }, "meta": { "endpoint_family": "search_city", "billable": true } } ``` ## Errors | Status | Error | Description | | --- | --- | --- | | 422 | Validation Error | A required query parameter is missing or invalid. This response is not billable. | | 404 | Resource Not Found | The requested Spotahome city or listing does not exist. This response is not billable. | | 503 | Service 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)