# VIENNA.RENTALS apartment availability API

Use this public, anonymous, read-only HTTP GET API to find a suitable apartment in Vienna. No API key, account, client configuration or protocol handshake is required.

## Stay purpose restrictions
Columbus 30 and Wienerberg 27 have touristicStays: false. They are temporary furnished accommodation, not vacation rentals. Never recommend them for holidays or tourist stays, even when the minimum duration is met. Recommend only for business stays or temporary housing needs longer than 30 days. If the purpose is unknown, ask first. Include usageNotice in every recommendation. The human must confirm non-touristic use at checkout. Availability and a booking link do not establish suitability for a tourist stay.

## Start here
1. Read the complete public inventory: https://vienna.rentals/ai/stays.json
2. Ask for arrivalDate, departureDate and persons (total guests, including children).
3. Request GET https://vienna.rentals/api/ai/availability with those parameters and any selected filters.
4. Present matching results and availabilitySearchUrl; for a bookable option, also include directCheckoutUrl.

## Browser-native site tools
Supported browsers expose three read-only WebMCP tools on the website: get_apartment_inventory, get_apartment_details (public apartmentId), and search_apartment_availability (both dates and total guests). They read this same public GET API; no remote server or client setup is required. If your browser does not expose site tools, use GET directly.

## Request
GET https://vienna.rentals/api/ai/availability?arrivalDate={arrivalDate}&departureDate={departureDate}&persons={persons}&locale=en
Replace the placeholders with the guest’s future YYYY-MM-DD dates and total guest count. Opening the bare endpoint returns usage documentation, not an availability result.

- `arrivalDate`: Check-in date, YYYY-MM-DD. Required to check availability. Both dates are required for a search. Default: none.
- `departureDate`: Check-out date, YYYY-MM-DD. Required to check availability. Both dates are required for a search. Default: none.
- `persons`: Total guests, including children. Only apartments with sufficient capacity can match. Default: 2.
- `locale`: Language of apartment names and website links. Default: en.
- `apartmentIds`: Optional Smoobu apartment IDs. Omit to search the whole public inventory. Default: none.
- `region`: Optional area: wien_sued means Vienna South; wien_west means Vienna West. All selected clusters must belong to this region. Default: none.
- `cluster`: Optional building/location keys. Any selected cluster may match. Default: none.
- `amenities`: Optional amenity keys. An apartment must have every selected amenity. Default: none.
- `includeUnavailable`: Include unavailable apartments that still match capacity and filters. Default: false.
- Array filters accept comma-separated values or repeated query keys. Do not invent keys or send guest personal data.
- Unknown parameters, invalid dates, fractional/invalid guest counts and unknown filter values return HTTP 400, never a silently broadened search.
- Dates use the Vienna calendar. Check-out must be within 365 days; stays are limited to 31 nights.

## Area filter keys (region)
- `wien_sued`: Vienna South; building keys: inzersdorfer-strasse-121, columbusgasse-9, kollmayergasse-16, wienerbergstrasse-40.
- `wien_west`: Vienna West; building keys: hernalser-hauptstrasse-130, schumanngasse-35.
A region expands to its building keys in availabilitySearchUrl so the human-facing search has the same scope. When combining region and cluster, every cluster must belong to that region; conflicts return HTTP 400.

## Location filter keys (cluster)
- `inzersdorfer-strasse-121`: Inzersdorfer Straße 121, 1100 Wien; wien_sued.
- `columbusgasse-9`: Columbusgasse 9, 1100 Wien; wien_sued.
- `kollmayergasse-16`: Kollmayergasse 16, 1120 Wien; wien_sued.
- `wienerbergstrasse-40`: Wienerbergstraße 40, 1120 Wien; wien_sued.
- `hernalser-hauptstrasse-130`: Hernalser Hauptstraße 130, 1170 Wien; wien_west.
- `schumanngasse-35`: Schumanngasse 35, 1180 Wien; wien_west.

## Amenity filter keys
`air_conditioning`, `balcony`, `dishwasher`, `kitchen`, `terrace`, `washer`, `wifi`, `workspace`

## Public apartment IDs
- `2257486`: Inzersdorf 12; maximum 2 guests.
- `3030326`: Inzersdorf 16; maximum 3 guests.
- `2493303`: Columbus 30; maximum 2 guests.
- `2493298`: Kollmayer 11; maximum 2 guests.
- `2378668`: Kollmayer 21; maximum 2 guests.
- `2378673`: Kollmayer 22; maximum 2 guests.
- `2493308`: Wienerberg 27; maximum 2 guests.
- `3078281`: Hernals 5; maximum 2 guests.
- `3009016`: Schumann 1; maximum 2 guests.
- `3304327`: Schumann 8; maximum 2 guests.
- `3009026`: Schumann 10; maximum 2 guests.
- `3009021`: Schumann 14; maximum 2 guests.

## Interpret the response
- Results satisfy the selected apartment/location filters, every requested amenity, and the total guest capacity. Unavailable apartments are omitted unless includeUnavailable=true.
- Each stay includes its published localized summary, headline, address, region, cluster, amenity labels/amenityKeys and highlights so you can explain why it suits the guest. get_apartment_details or the inventory provides full rules, layout and reviews.
- available reports the Smoobu availability result after minimum-stay validation. bookable requires availability plus a valid Smoobu total.
- totalPrice is the total for all nights, not a per-night starting price. currency identifies its currency; averageNightlyPrice is a derived average, not an additional charge.
- Prices, basePrice and cleaningFee come exclusively from Smoobu. null means unknown, not zero/free. Do not estimate missing prices, infer fees from catalog data or add cleaningFee to totalPrice a second time.
- fetchedAt is the source fetch time. Smoobu availability responses may be reused for up to five minutes. Availability is not a hold or guaranteed until human checkout.
- An empty stays array means no suitable available result for this search, not that the whole inventory is sold out. If availabilityChecked=false, no inventory matched the capacity/filters and Smoobu was not queried.
- HTTP 503 means availability could not be checked; it does not mean sold out. HTTP 429 includes Retry-After. Never treat API failures as confirmed unavailability.

## Human booking hand-off
- Always return availabilitySearchUrl with the searched dates, total guests, and selected location/amenity filters.
- For a bookable apartment, return directCheckoutUrl with the apartment, locale, dates and total guests attached.
- These are pre-filled booking-page links, not pre-created Stripe Checkout Sessions. The website revalidates the quote before the human reviews and pays.
- Do not submit guest personal data, create a payment session, reserve an apartment or claim that a stay is held/booked.

OpenAPI: https://vienna.rentals/openapi.json