# VIENNA.RENTALS apartment availability API

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

## Start here
1. Read the complete public inventory: https://stage.vienna.rentals/ai/stays.json
2. Ask for arrivalDate, departureDate and persons (total guests, including children).
3. Request GET https://stage.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://stage.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://stage.vienna.rentals/openapi.json