# SpareRoom Search

Search UK rooms and flatshares on SpareRoom by area or postcode district. Filter by rent, room type, en-suite, furnishing, bills included, move-in date, stay length, household, landlord type, pets, smoking and more, and sort by relevance, age or price. Pages hold up to 100 ads and start at page 1. A search reaches at most 1,000 ads: data.truncated is true when more match, so split a big city with the areas endpoint and search each district. Page N always returns page N. Ads are de-duplicated by id. SpareRoom matches rent per ad, so Scrappa removes the rooms outside your rent band and compares weekly and monthly prices on rent_period. With a rent filter data.total_pool and data.rows_reachable are null, because the SpareRoom count no longer describes the rows. When a place name matches several places, the answer is 200 with data.type ambiguous_place and data.options. Repeat the search with one option as where. This answer is not billed. An unknown place returns a 404 and invalid parameters return a 422, both not billed. data.filter_options lists the filter groups with the ad count of each option and the parameters that select it.

- **Documentation:** [https://scrappa.co/docs/spareroom-api/spareroom_search](https://scrappa.co/docs/spareroom-api/spareroom_search)
- **API group:** SpareRoom API
- **Endpoint:** `GET https://scrappa.co/api/spareroom/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 |
| --- | --- | --- | --- |
| `where` | string | Yes | Area, town or postcode district, for example London, Manchester or E1. Use the locations endpoint to find valid values and the areas endpoint to list the districts of a city. |
| `page` | integer | No | Result page, starting at 1. Each page holds up to 100 ads and at most 1,000 ads are reachable per search. |
| `sort` | string | No | relevance (default), newest, last_updated, price_low_to_high or price_high_to_low. |
| `min_rent` | integer | No | Minimum room rent, in the units of rent_period. Rooms below it are removed. |
| `max_rent` | integer | No | Maximum room rent, in the units of rent_period. Rooms above it are removed. |
| `rent_period` | string | No | pcm (per month, default) or pw (per week). Weekly prices are compared as monthly and the other way round. |
| `bills_included` | boolean | No | true to return only ads with bills included. |
| `available_from` | string | No | Move-in date as YYYY-MM-DD. Matches ads with a room free on that date. |
| `types` | string | No | Comma list of rooms, studios and whole_properties. Leave empty for all stock. |
| `room_types` | string | No | double or single. |
| `ensuite` | string | No | Y for rooms with an en-suite. |
| `furnished` | string | No | Y for furnished, N for unfurnished. |
| `rooms_for` | string | No | males, females or couples. |
| `share_type` | string | No | P for professionals, S for students. |
| `genderfilter` | string | No | males, females or mixed households. |
| `gayshare` | string | No | Y for LGBT households. |
| `vegetarians` | string | No | Y for vegetarian or vegan households. |
| `disabled_access` | string | No | Y for ads with disabled access. |
| `living_room` | string | No | shared for ads with a shared living room. |
| `parking` | string | No | Y for ads with parking. |
| `smoking` | string | No | Y when smoking is allowed, N for no smoking. |
| `pets_req` | string | No | Y for ads that suit pets. |
| `days_of_wk_available` | string | No | Mon to Fri only or 7 days a week. |
| `short_lets_considered` | string | No | Y for ads that consider short lets. |
| `posted_by` | string | No | private_landlords, flatmates, agents or co_live. |
| `landlord` | string | No | live_in or live_out. |
| `photoadsonly` | string | No | Y for ads with photos. |
| `free_to_contact` | string | No | Y for ads that are free to contact. |
| `no_deposit` | string | No | Y for low or no deposit ads. |
| `verified_users` | string | No | Y for verified advertisers. |
| `min_term` | integer | No | Stay of at least this many months. |
| `max_term` | integer | No | Stay of at most this many months. |
| `no_of_rooms` | integer | No | Ads with at least this many rooms. |
| `min_age_req` | integer | No | Household minimum age. |
| `max_age_req` | integer | No | Household maximum age. |
| `min_beds` | integer | No | Smallest household size, including you. |
| `max_beds` | integer | No | Largest household size, including you. |

## Errors

| Status | Error | Description |
| --- | --- | --- |
|  | A parameter is missing or invalid. This response is not billable. |  |
|  | The ad, place or city does not exist. This response is not billable. |  |
|  | The upstream is unavailable, refused the request or answered in an unexpected shape. 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)