# Hybel Rental Search API Documentation

Scrappa's `GET /api/hybel/search` returns Hybel.no rental homes in one Norwegian place as structured JSON.

## Rentals only

Hybel lists homes for rent. It has no sale listings, no bathroom count and no public landlord profile, so this API has none of them. Hybel ignores text search, so there is no keyword parameter.

## What you get

One request returns one page of 12 homes and Hybel's own match count in `total`. Each home has `id`, `url`, `title`, `type`, `home_type`, `rooms`, `area_m2`, `address`, `city`, `rent` in NOK, `thumbnail`, `badges`, `is_prioritized`, `has_video` and `latitude` and `longitude`. Call the listing endpoint for deposit, included costs, facilities, the description and the whole photo gallery.

## Filters are honoured

Hybel applies every filter itself, so `total` and the paging always describe the real result set. Unknown parameters and unknown list values are rejected with `422` instead of being ignored. `applied_filters` echoes what was sent. A page whose homes break a requested rent range or home type is never returned.

## Place and districts

`place` takes a name from `/api/hybel/location-autocomplete`. A name Hybel does not know returns `422` (`unknown_place`) with suggestions. `available_districts` lists the district names of the place. Pass them in `district`, matched without regard to case. A district that does not exist returns `422` (`invalid_filter`) with the valid names, because Hybel would otherwise ignore it.

## Pagination

Each page holds 12 homes. `page` is 1-based. A page past the last one returns an empty list labelled with that page and `total` null. It never returns another page's homes.

## Coordinates

Coordinates come from Hybel's map data and are joined by listing id. If that data is not available, the homes are still returned with `latitude` and `longitude` set to null.

## Sort

`-updated_at` (default), `-created_at`, `rent`, `-rent`, `-space` or `available_from`.

- **Documentation:** [https://scrappa.co/docs/hybel-api/hybel_search](https://scrappa.co/docs/hybel-api/hybel_search)
- **API group:** Hybel API
- **Endpoint:** `GET https://scrappa.co/api/hybel/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 |
| --- | --- | --- | --- |
| `place` | string | Yes | Place name from location-autocomplete, for example Oslo or Bergen. |
| `min_rent` | integer | No | Minimum monthly rent in NOK as a whole number. |
| `max_rent` | integer | No | Maximum monthly rent in NOK as a whole number. |
| `home_type` | string | No | One or more of house, apartment, studio, shared_room, room_in_apartment. Comma-separated. |
| `rooms` | string | No | One or more room counts from 1 to 10, or other. Comma-separated. |
| `rent_period` | string | No | long_term, short_term or both. Comma-separated. |
| `available_from` | string | No | Earliest move-in date, YYYY-MM-DD. |
| `available_to` | string | No | Latest move-in date, YYYY-MM-DD. |
| `district` | string | No | One or more district names of the place, comma-separated. See available_districts. |
| `student_housing` | boolean | No | true to show student housing only. |
| `balcony` | boolean | No | true to show homes with a balcony only. |
| `pets_allowed` | boolean | No | true to show homes that allow pets only. |
| `parking` | boolean | No | true to show homes with parking only. |
| `elevator` | boolean | No | true to show homes with an elevator only. |
| `internet_included` | boolean | No | true to show homes with internet included in the rent only. |
| `furnished` | boolean | No | true to show furnished homes only. |
| `sort` | string | No | -updated_at (default), -created_at, rent, -rent, -space or available_from. |
| `page` | integer | No | Result page, 1-based. Each page holds 12 homes. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/hybel/search?place=Oslo&max_rent=12000&home_type=apartment&sort=rent"
```

## Example response

```json
{
    "success": true,
    "place": {
        "name": "Oslo",
        "slug": "Oslo"
    },
    "currency": "NOK",
    "total": 210,
    "returned": 1,
    "pagination": {
        "page": 1,
        "limit": 12,
        "total_pages": 18,
        "has_next": true,
        "has_previous": false
    },
    "applied_filters": {
        "place": "Oslo",
        "sort": "rent",
        "max_rent": 12000,
        "home_type": [
            "apartment"
        ]
    },
    "available_districts": [
        "Alna",
        "Bjerke",
        "Frogner"
    ],
    "listings": [
        {
            "id": 382836,
            "url": "https://hybel.no/bolig/382836/leilighet-gabels-gate-1c-oslo/",
            "title": "Leilighet, 3 roms - 77m2",
            "type": "Leilighet",
            "home_type": "apartment",
            "rooms": 3,
            "area_m2": 77,
            "address": "Gabels Gate 1C, Oslo",
            "city": "Oslo",
            "rent": 11900,
            "currency": "NOK",
            "thumbnail": "https://cdn.example.com/ad_pictures/photo.900x600.jpg",
            "badges": [
                "Prioritert"
            ],
            "is_prioritized": true,
            "has_video": false,
            "latitude": 59.911279,
            "longitude": 10.708063
        }
    ],
    "meta": {
        "endpoint_family": "search",
        "billable": true,
        "attempts": 2
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Unknown Place | The `place` value matches no place on Hybel (`unknown_place`). Hybel would otherwise send you to its home page, so the request is rejected. Up to five suggestions are returned. Non-billable. |
| 422 | Unknown District | A `district` is not one of the place's districts (`invalid_filter`). Hybel would ignore it and return the whole place, so the request is rejected and the valid names are returned in `available_districts`. Non-billable. |
| 422 | Validation Error | A query parameter is missing, unknown or unusable (`invalid_filter`). Unknown parameters and unknown list values are rejected, never ignored. Non-billable. |
| 503 | Upstream Unavailable | Hybel could not be reached, refused the request, answered with a page this API could not read, or its place list is not available (`upstream_unavailable`, `upstream_blocked`, `parser_drift`, `place_catalog_unavailable`). 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)