# Build with AI on Dutch rental data

You do not need to be a developer. Give your AI assistant the right context, say what you want to build, and let it write the code or connect to the API directly.

## Three steps

1. [Create an account](https://woning.me/developer/register), add a payment method (the 2-day free trial starts) and generate an API key in the [dashboard](https://woning.me/developer/dashboard).
2. Copy the prompt below and paste it into ChatGPT, Claude, Cursor or another AI assistant. Replace the last line with what you want.
3. Let the assistant write the code. When it asks for your key, give it as an environment variable called `WONINGME_API_KEY`, not inside the code.

Copy prompt [view the prompt](https://woning.me/developer/ai-prompt.txt)

```
I want to build something with the WoningMe Dutch Rental Listings API. Please help me do it step by step, and write code I can run.

Read these first:
- https://woning.me/llms-full.txt (summary, reference and guides in plain text)
- https://woning.me/developer/openapi.json (the OpenAPI spec)

Facts you must follow:
- Base URL: https://woning.me/api/developer/v1
- Authentication: header X-Api-Key: <my key>. Read the key from an environment variable called WONINGME_API_KEY. Never hard-code it and never print it.
- The quickest call needs no setup: GET /listings?city=Utrecht&max_price=1500&sort=first_seen_at&order=desc. City names are forgiving (typos, "den haag").
- Rent is in euro cents (priceEurCents: 145000 means EUR 1,450). Filters such as max_price are whole euros.
- Results are paged: send the nextCursor of one response as cursor in the next request.
- To be told about new listings, do not poll. Create saved searches (POST /searches), then set one webhook URL with PUT /webhook. Each new match is POSTed to it. Verify the X-WoningMe-Signature header (HMAC-SHA256 of the raw body with the webhook secret) before trusting a payload.
- Errors contain a hint field that says how to fix them. Limits: 30 requests per minute, 50 listings per request.
- Rentals only, no properties for sale. The Personal plan is for non-commercial use.
- If you can use MCP tools, connect the MCP server instead of writing HTTP calls: https://woning.me/mcp (see https://woning.me/developer/mcp-server).

Be kind to the API (it is a shared service; heavy use gets rate limited):
- For new listings, use a webhook instead of polling (PUT /webhook after creating saved searches).
- If you must poll, do it at most once every 5 minutes per query, and ask only for what is new: set listed_since to the time of your last check (ISO date or datetime) with sort=first_seen_at, order=desc.
- Be specific. Always set city and the filters you care about (max_price, min_rooms, property_type), and keep limit small. Do not page through all results: use total from the first response to know how many exist, and stop when you have enough.
- Never repeat an identical query within a minute: answers are cached for 60 seconds, and a response with a notice field means you are repeating yourself.
- Keep your own copy. Store results and reuse them instead of asking again for the same listings.
- Send requests one after another, not in parallel bursts, and prefer one well-filtered request over many near-identical ones.
- Watch the X-RateLimit-Remaining header. On HTTP 429 wait for the Retry-After seconds and then back off (double the wait on each repeated 429).
- Page with cursor, not skip. Do not create a saved search for every question: saved searches (max 10) exist for webhooks. Do not regenerate your key or send test events in a loop.

Listing details (not available yet; follow these rules from the start):
- Request the images of a listing only when a user is viewing that listing's detail page, one listing per user action.
- Request the description of a listing only when a user is viewing that listing's detail page, one listing per user action.
- Do not fetch details periodically, in a loop, in bulk, or in advance for a list of listings, and do not poll or refresh them on a schedule. This is not allowed.
- Until then: show the main image (imageUrl) and link to the original listing (url) for everything else.

My goal: <describe what you want to build, in your own words>
```

## Things people build

### An alert when a matching home appears

Say: "Send me a Telegram message whenever a new rental in Utrecht under 1600 euro with at least 2 rooms is listed." The assistant creates a saved search, sets the webhook and writes a small server that receives it. See [rental webhooks](https://woning.me/developer/rental-webhooks).

### A Google Sheet that fills itself

Say: "Write a Google Apps Script that loads the newest 50 rentals in Amsterdam into my sheet every hour." One call to `GET /listings` is enough.

### A page that shows rentals for one city

Say: "Build a simple web page with a table of apartments in Eindhoven under 1400 euro, newest first, with a link to each listing."

### Research on the rental market

Say: "Fetch all listings in Rotterdam from the last 30 days and show the average rent per number of rooms." Use `listed_since` and the cursor to page through the results.

## No code at all: Make, Zapier and n8n

These tools can receive a webhook and pass it on to email, Slack, Telegram or a spreadsheet.

1. In the tool, create a scenario or zap that starts with a webhook: Webhooks > Custom webhook in Make, Webhooks by Zapier > Catch Hook in Zapier, or the Webhook node in n8n. Copy the https URL it gives you.
2. Create a saved search for the area you want, then set that URL as your webhook (the `PUT /webhook` call from the prompt above, which an AI assistant can do for you, or with the MCP tools).
3. Use the fields of the `property` object (`street`, `city`, `priceEurCents`, `url`) in the next step of your scenario.

These tools usually cannot verify the HMAC signature. Use a hard-to-guess webhook URL and do not publish it. If you need verified deliveries, let your AI assistant write a small endpoint that checks `X-WoningMe-Signature`.

## Let the AI use the API directly: MCP

Assistants that support MCP (Claude, Cursor and others) can connect to the [WoningMe MCP server](https://woning.me/developer/mcp-server) and search rentals, manage saved searches and set the webhook as tools, with only your API key. You then simply ask: "Which apartments under 1500 euro are new in Utrecht?"

## Be kind to the API

The API is a shared service, so heavy use is rate limited. The prompt above already tells your AI assistant these rules; they are worth knowing yourself:

- For new listings, use a webhook instead of polling (PUT /webhook after creating saved searches).
- If you must poll, do it at most once every 5 minutes per query, and ask only for what is new: set listed_since to the time of your last check (ISO date or datetime) with sort=first_seen_at, order=desc.
- Be specific. Always set city and the filters you care about (max_price, min_rooms, property_type), and keep limit small. Do not page through all results: use total from the first response to know how many exist, and stop when you have enough.
- Never repeat an identical query within a minute: answers are cached for 60 seconds, and a response with a notice field means you are repeating yourself.
- Keep your own copy. Store results and reuse them instead of asking again for the same listings.
- Send requests one after another, not in parallel bursts, and prefer one well-filtered request over many near-identical ones.
- Watch the X-RateLimit-Remaining header. On HTTP 429 wait for the Retry-After seconds and then back off (double the wait on each repeated 429).
- Page with cursor, not skip. Do not create a saved search for every question: saved searches (max 10) exist for webhooks. Do not regenerate your key or send test events in a loop.

## Listing details: planned, with rules

Listing details (all images, the full description) are not available through the API yet. When a details endpoint is added, these rules apply:

- Request the images of a listing only when a user is viewing that listing's detail page, one listing per user action.
- Request the description of a listing only when a user is viewing that listing's detail page, one listing per user action.
- Do not fetch details periodically, in a loop, in bulk, or in advance for a list of listings, and do not poll or refresh them on a schedule. This is not allowed.
- Until then: show the main image (imageUrl) and link to the original listing (url) for everything else.

## Good to know

- Keep your API key private. Do not paste it into public chats, screenshots or repositories. If it leaks, generate a new one in the dashboard and the old one stops working at once.
- The Personal plan is for personal and non-commercial projects. For a commercial product, [let's talk](https://woning.me/en/collaborate).
- Errors contain a `hint` that tells you or your assistant how to fix them. Paste the whole error into the chat.

Source: https://woning.me/developer/build-with-ai (part of the WoningMe Developer API, https://woning.me/developer)