# BoligPortal Price Histogram API Documentation

Scrappa's `GET /api/boligportal/price-histogram` returns the monthly rent distribution of the matching rentals in 50 equal-width buckets.

## Reading the buckets

`min_price` is the start of the first bucket and `bucket_width` the width of each, in DKK. `buckets[i]` is the number of homes with a rent from `min_price + i * bucket_width` up to the next bucket.

## Filters

All search filters except rent bounds, `order` and `page`. The histogram covers the whole rent range. With a rooms filter `meta.count_exact` is false because BoligPortal rounds half rooms.

- **Documentation:** [https://scrappa.co/docs/boligportal-api/boligportal_price_histogram](https://scrappa.co/docs/boligportal-api/boligportal_price_histogram)
- **API group:** BoligPortal API
- **Endpoint:** `GET https://scrappa.co/api/boligportal/price-histogram`

## 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` | string | No | City such as København, Aarhus or Odense (not case sensitive). Unknown cities return 422 with suggestions. |
| `district` | string | No | District inside the city, for example valby or frederiksberg. |
| `area` | string | No | Neighbourhood inside the district. |
| `street` | string | No | Street name, for example Gammel Køge Landevej. |
| `type` | string | No | apartment, house, townhouse or room. Comma-separated. |
| `min_rooms` | number | No | Minimum number of rooms, halves allowed, for example 1.5. Applied exactly: the platform rounds, so results are checked again. |
| `max_rooms` | number | No | Maximum number of rooms, halves allowed. |
| `min_size` | integer | No | Minimum size in square metres. |
| `max_size` | integer | No | Maximum size in square metres. |
| `min_rental_period` | integer | No | Minimum rental period in months. |
| `available_before` | string | No | Latest move-in date, YYYY-MM-DD. |
| `min_lat` | number | No | South edge of a bounding box. Send all four box values or none. |
| `max_lat` | number | No | North edge of a bounding box. |
| `min_lng` | number | No | West edge of a bounding box. |
| `max_lng` | number | No | East edge of a bounding box. |
| `pet_friendly` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `furnished` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `balcony` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `parking` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `elevator` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `shareable` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `student_only` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `senior_friendly` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `social_housing` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `newbuild` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `electric_charging_station` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `dishwasher` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `washing_machine` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |
| `dryer` | boolean | No | true to require the feature. false or omitted applies no filter. Homes where the feature is unknown are left out. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/boligportal/price-histogram?location=K%C3%B8benhavn&type=apartment"
```

## Example response

```json
{
    "success": true,
    "currency": "DKK",
    "min_price": 2500,
    "max_price": 30000,
    "bucket_width": 550,
    "buckets": [
        3,
        4,
        17,
        15,
        33
    ],
    "applied_filters": {
        "location": "k\u00f8benhavn",
        "type": [
            "apartment"
        ]
    },
    "meta": {
        "endpoint_family": "price_histogram",
        "count_exact": true,
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Unknown Location | The `location` is not a BoligPortal city (`unknown_location`). BoligPortal would answer an unknown city with zero results, so the request is rejected with up to five suggestions. Non-billable. |
| 422 | Validation Error | A query parameter is missing, unknown or unusable. Unknown parameters are rejected, never ignored. Sale, bathroom and agency filters do not exist. Non-billable. |
| 503 | Upstream Unavailable | BoligPortal could not be reached after retries, blocked the request, returned another page than asked for, or returned a page this API could not read (`upstream_unavailable`, `upstream_blocked`, `offset_mismatch`, `parser_drift`, `transport_unavailable`, `no_exit_available`). 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)