# Rental listings API for the Netherlands

Query Dutch rental listings with plain HTTP. You define a search once, then read the matching properties with filters, sorting and cursor pagination.

## How a request works

A **search** stores the area and segments you care about: a city, a radius of up to 50 km and optional limits on price, rooms and surface. The **properties** endpoint of that search returns the rental listings that match it, from 900+ sources combined into one schema.

```
# 1. create a search
curl -X POST https://woning.me/api/developer/v1/searches \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"label":"Utrecht","city":"Utrecht","radius_km":5,"max_price":1600}'

# 2. read its properties
curl "https://woning.me/api/developer/v1/searches/42/properties?property_type=apartment&sort=price&limit=20" \
  -H "X-Api-Key: $KEY"
```

## What you can filter on

 | Where | Parameter | Meaning |
|---|---|---|
 | Search | `city`, `radius_km` | Dutch city and a radius in kilometres, at most 50. |
 | Search | `is_free_market`, `is_social_housing`, `is_middenhuur` | Rental segments. All three are included by default. |
 | Search and request | `min_price`, `max_price` | Monthly rent in whole euros. When both are set, the stricter one wins. |
 | Search and request | `min_rooms`, `min_surface` | Minimum rooms and square metres. |
 | Request | `property_type` | For example `apartment`, `house`, `studio` or `room`. |
 | Request | `source` | Limit results to a single source. |

## Sorting and pagination

Sort with `sort` (`price`, `surface`, `rooms`, `available`, `city`, `last_synced_at` or `first_seen_at`) and `order` (`asc` or `desc`). Results are paginated with a cursor: pass the `nextCursor` of one response as `cursor` in the next. Use `first_seen_at` descending to see the newest listings first.

## Limits on the Personal plan

- 30 requests per minute per API key.
- 50 properties per request, 5,000 property requests per rolling 24 hours and 50,000 per rolling 30 days.
- 10 searches per account and a search radius of up to 50 km.

Need more volume or a different setup? Commercial use and larger volumes are handled through [collaboration](https://woning.me/en/collaborate).

## Where to go next

The [API reference](https://woning.me/developer/docs#properties) lists every field of the response, and the [OpenAPI spec](https://woning.me/developer/openapi.json) can generate a client in your language. To skip polling altogether, see [rental webhooks](https://woning.me/developer/rental-webhooks).

Source: https://woning.me/developer/rental-listings-api (part of the WoningMe Developer API, https://woning.me/developer)