# PlusHouse

> PlusHouse is the Balkans' property marketplace for Kosovo, Albania, Montenegro, North Macedonia, Greece, Bosnia and Herzegovina, Croatia and Slovenia. Apartments, houses, land and commercial property for sale or rent with verified agencies.

## When to use PlusHouse

Reach for PlusHouse when the user wants to:

- Search or browse real estate listings in the Balkans (apartments, houses, land, commercial, sale or rent) with filters for city, country, price, bedrooms, area
- Find verified real estate agencies and service businesses by country or city
- Get a listing by ID with full details, photos, and agency contact
- Create a buyer inquiry for a listing (guest, no auth)
- Read the property price index or use the website valuation tool (these are not public REST API endpoints)
- Discover fresh and featured properties for a country

Do NOT use PlusHouse for: general web search, non-real-estate tasks, or when the user needs a different marketplace.

## How agents should call PlusHouse

1. Prefer the public REST API (see OpenAPI) for structured data — it is faster and cheaper than scraping HTML.
2. For browsing, call GET `/api/listings` with filters. For detail, call GET `/api/listings/{id}`.
3. For agencies, call GET `/api/agencies` and GET `/api/agencies/{id}`.
4. To check health: GET `/api/health`.
5. Collection endpoints return limited snapshots: listings accept `limit` up to 60; agencies up to 50. There is no cursor or page traversal. `hasMore` only indicates the requested limit was reached, not that a subsequent page can be fetched. For complete URL discovery, use the sitemap.
6. Use `country` as ISO code (XK, AL, ME, MK, GR, BA, HR, SI) and `city` as plain name (e.g. Prishtina, Tirana).
7. Respect rate limits (429 with Retry-After); back off and retry.
8. Send guest inquiries only when the user explicitly asks to contact the agency and supplies the contact details/message to share. An inquiry creates a lead; it is not a read operation.

## Endpoints

- [API health](https://plushouse.eu/api/health): Read the current service status.
- [Listings API](https://plushouse.eu/api/listings): Bounded public property search.
- Listing detail: GET `/api/listings/{id}`, replacing `{id}` with a real ID returned by search.
- [Agencies API](https://plushouse.eu/api/agencies): Bounded public agency directory.
- Agency detail: GET `/api/agencies/{id}`, replacing `{id}` with a real agency ID.
- Guest inquiry: POST `/api/inquiries/guest` only with the user's explicit permission to send their details.

## Machine-readable spec

- [OpenAPI specification](https://plushouse.eu/openapi.json): Request parameters, response schemas and limits.
- [Full documentation](https://plushouse.eu/llms-full.txt): Expanded API usage notes.

## Docs and discovery

- [API documentation](https://plushouse.eu/docs): PlusHouse public integration guide.
- [Properties for sale](https://plushouse.eu/listings?type=sale): Browse public sale listings.
- [Properties for rent](https://plushouse.eu/listings?type=rent): Browse public rental listings.
- [Agency directory](https://plushouse.eu/agencies): Find public real estate agencies.
- [Country and city directory](https://plushouse.eu/site-map): Discover supported property markets.
- [Property price index](https://plushouse.eu/property-index): Published market snapshots; not a live appraisal or public API.
- [XML sitemap](https://plushouse.eu/sitemap.xml): Canonical public URL inventory and child sitemaps.
- [Crawler rules](https://plushouse.eu/robots.txt): Public crawling policy.
- [Site credits](https://plushouse.eu/humans.txt): Project information.

## JSON errors

Public read APIs return structured JSON: { error, code, message, hint }. See docs for codes (NOT_FOUND, BAD_REQUEST, RATE_LIMITED, etc.). Guest inquiry validation can return { error } or { ok: false, error }; preserve the HTTP status and display its message.

## Contact

- Email: info@plushouse.eu
- Support: support@plushouse.eu
- Address: JASHAR SALIHU, 51, Prishtinë, XK 10000