# Vuokraovi Rental Search API Documentation Scrappa's `GET /api/vuokraovi/search` returns Vuokraovi rental homes in Finland as structured JSON, with location, rent, size, rooms, type filters, sort and paging. ## Rentals only Vuokraovi lists homes for rent. It has no sale listings and no bathrooms field, so this API has no sale or bathrooms parameter. Finnish sale listings are on the Etuovi and Oikotie APIs. ## What you get One request returns one page of listings, Vuokraovi's own match count in `total`, the real `page` and `limit`, and `has_more`. Each listing has `id`, `friendly_id`, `url`, `address`, `district_city`, `latitude`, `longitude`, `year_built`, `published_at`, `next_showings`, `image_url`, `office`, `room_structure`, `rooms`, `floor`, `area`, `total_area`, `rent`, `availability`, `property_subtype` and `private_lessor_name`. A field Vuokraovi does not state is left out. A rent or area of zero means "not stated" and is left out. Call the listing endpoint for the description, deposit, charges, images and agent. ## Filters are honoured Vuokraovi applies every filter itself, so `total` and the paging describe the real result set. Unknown parameters and unknown values return `422` instead of being ignored. `applied_filters` echoes what was sent. ## Location Take `location_code`, `location_type` and `parent_region_code` from `search_params` of `/api/vuokraovi/location-autocomplete`. Without a location the search covers all of Finland. A code that matches no place returns an empty list with `total` 0. ## Sorting `sort` is one of `PUBLISHED_OR_UPDATED_AT` (default), `PUBLISHING_TIME`, `SEARCH_RENT`, `LIVING_AREA`, `CONSTRUCTION_FINISHED_YEAR`, `LOCATION` (asc or desc), `AVAILABILITY` or `NEXT_SHOWINGS` (asc only). `SEARCH_RENT` and `LIVING_AREA` ascending start with listings that state no rent or area. This is Vuokraovi's own order and is not changed. ## Pagination `page` is 1-based and `limit` is 25, 30 (default) or 100. A page past the last one returns an empty list with the real `total`. It never returns another page's listings. ## Agency listings Set `office_id` to list the homes of one agency. Take the id from a listing or from the agency endpoint. - **Documentation:** [https://scrappa.co/docs/vuokraovi-api/vuokraovi_search](https://scrappa.co/docs/vuokraovi-api/vuokraovi_search) - **API group:** Vuokraovi API - **Endpoint:** `GET https://scrappa.co/api/vuokraovi/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_code` | string | No | Location code from location-autocomplete, for example FI_UUSIMAA_HELSINKI. Needs location_type. | | `location_type` | string | No | CITY, DISTRICT, SUBDISTRICT, MUNICIPALITY, POST_CODE or STREET. Needs location_code. | | `parent_region_code` | string | No | Parent region code from location-autocomplete, for example FI_UUSIMAA. | | `min_rent` | integer | No | Minimum monthly rent in euros. | | `max_rent` | integer | No | Maximum monthly rent in euros. | | `min_size` | integer | No | Minimum living area in square metres. | | `max_size` | integer | No | Maximum living area in square metres. | | `min_year` | integer | No | Minimum year the building was finished. | | `max_year` | integer | No | Maximum year the building was finished. | | `rooms` | string | No | Room counts 1 to 5, or 6 for six and more. Comma-separated, for example 2,3. | | `property_type` | string | No | apartment_house, row_house, semi_detached_house, detached_house, separate_house, balcony_access_block or wooden_house_apartment. Comma-separated. | | `lessor_type` | string | No | all (default), private or agency. | | `published_within` | string | No | any (default), 1d, 2d, 7d or 30d. | | `new_building` | string | No | all (default), only or exclude. | | `kitchen_type` | string | No | kitchen, combined_with_living_room, kitchenette or kitchen_niche. Comma-separated. | | `condition` | string | No | good, satisfactory, tolerable or unclassified. Comma-separated. | | `living_form` | string | No | non_subsidized, student_apartment, senior_house, cell_flat, need_based_apartment, assisted_living_residence, company_housing or subtenant. Comma-separated. | | `rental_agreement` | string | No | open_ended for permanent contracts. | | `available_immediately` | boolean | No | true for homes free to move in now. | | `has_images` | boolean | No | true for listings with images. | | `has_panorama` | boolean | No | true for listings with a panorama. | | `has_video` | boolean | No | true for listings with a video. | | `has_showing_within_7_days` | boolean | No | true for listings with a showing in the next 7 days. | | `query` | string | No | Free text, for example sauna. | | `office_id` | integer | No | Only listings of this agency. | | `sort` | string | No | PUBLISHED_OR_UPDATED_AT (default), PUBLISHING_TIME, SEARCH_RENT, LIVING_AREA, CONSTRUCTION_FINISHED_YEAR, LOCATION, AVAILABILITY or NEXT_SHOWINGS. | | `direction` | string | No | desc (default) or asc. AVAILABILITY and NEXT_SHOWINGS support asc only. | | `limit` | integer | No | Listings per page: 25, 30 (default) or 100. | | `page` | integer | No | Result page, 1-based. | ## Example request ```bash #!/bin/bash curl -X GET \ -H "x-api-key: YOUR_API_KEY_HERE" \ "https://scrappa.co/api/vuokraovi/search?location_code=FI_UUSIMAA_HELSINKI&location_type=CITY&max_rent=900&rooms=2&limit=30" ``` ## Example response ```json { "success": true, "total": 1596, "returned": 1, "page": 1, "limit": 30, "has_more": true, "applied_filters": { "location_code": "FI_UUSIMAA_HELSINKI", "location_type": "CITY", "max_rent": 900, "rooms": [ "2" ], "sort": "PUBLISHED_OR_UPDATED_AT", "direction": "desc" }, "listings": [ { "id": 2751570, "friendly_id": "hh4763", "url": "https://www.vuokraovi.com/kohde/hh4763", "address": "Runeberginkatu 69 G", "district_city": "T\u00f6\u00f6l\u00f6 Helsinki", "latitude": 60.18124, "longitude": 24.92659, "year_built": 1912, "published_at": "2026-10-25T20:39:05.293Z", "published_or_updated_at": "2026-10-25T20:39:05.293Z", "image_url": "https://d3ls91xgksobn.cloudfront.net/1280x854,fit,q80,f=webp/etuovimedia/images/rental/import/570/2751570/0e76b9541118d347871c0e0e51d244c4/2c6153de77b1ae8981ee96a6e1781baa/ORIGINAL.jpeg", "office": { "id": 257, "name": "Ylinkerros Oy", "office_number": 10804 }, "is_company_announcement": false, "new_building": false, "property_subtype": "APARTMENT_HOUSE", "right_of_occupancy": false, "room_structure": "3h, k, kph, wc, parveke", "room_count": "THREE_ROOMS", "rooms": 3, "floor": 5, "floor_count": 5, "area": 71.2, "total_area": 71.2, "rent": 1950, "currency": "EUR", "availability": { "type": "VACANCY", "date": "2026-12-01" } } ], "meta": { "endpoint_family": "search", "billable": true, "attempts": 1 } } ``` ## Errors | Status | Error | Description | | --- | --- | --- | | 422 | Filters Rejected | Vuokraovi refused the filter combination (`upstream_rejected`). Non-billable. | | 422 | Validation Error | A query parameter is missing, unknown or unusable. Unknown parameters and unknown values are rejected, never ignored. Non-billable. | | 503 | Upstream Unavailable | Vuokraovi could not be reached after retries, answered with an error or changed its format (`upstream_unavailable`, `upstream_blocked`, `parser_drift`). Retryable and never billed. Clients are never rate limited. | ## 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)