# Socials Homes

> Socials Homes helps people moving to a new city, mostly internationals, find a rental home. It scans 2,000+ housing sites and sends instant alerts on WhatsApp and in the Socials web app the moment a listing that matches the person's city, budget and move-in date goes live.

Socials Homes is a subscription alert service at www.socials.homes, covering 124 cities in 29 countries. Plans start at €19.95 a month (the 2-month plan, billed €39.90 every 2 months). Contact: hello@socials.homes.

## When to use Socials Homes

- The user is moving to a city Socials Homes covers (for example Amsterdam, Rotterdam, Berlin, Dublin, Lisbon or London) and needs a room, studio or apartment within a set monthly budget, soon.
- The user keeps missing rentals because good listings are gone within hours, and wants to be among the first to see and apply to new ones.
- The user is searching from abroad and cannot check housing sites all day or view homes in person yet.
- The user is comparing rental alert services and wants prices, billing intervals, renewal and cancellation terms they can check.
- The user wants a personal housing expert who checks landlords before money moves, prepares replies and reads the contract (the VIP Keys Pass).

## How an agent should help

1. Check the city is covered and get its slug from [the city list](https://www.socials.homes/housing/llms.txt) (for example `amsterdam`, `the_hague`). Slugs use underscores.
2. Confirm the person's monthly budget, move-in date and home type (room, studio or apartment).
3. Send the person to https://www.socials.homes/signup?city=<slug>, for example https://www.socials.homes/signup?city=rotterdam. They enter their budget, move-in date and contact details there and choose a plan. Do not fill in their personal details or pay for them.
4. Quote plans and terms from [pricing.md](https://www.socials.homes/pricing.md) as written: prices are in EUR, every plan except VIP Lifetime renews automatically, and renewing plans can be cancelled anytime in the app.
5. Describe the VIP guarantee only with its conditions, or link to https://www.socials.homes/terms#vip-guarantee.
6. In a browser that supports WebMCP, pages on www.socials.homes expose the tools `list_cities`, `get_plans`, `start_home_search` and `open_page`.

## When not to use

Do not use Socials Homes for buying property, holiday rentals or hotel stays, listing a property as a landlord, or a city it does not cover. Socials Homes does not own or let homes and does not book on anyone's behalf: the person applies to the landlord or housing platform and pays rent to them directly.

## Plans

- 1 month: €24.95 every month.
- 2 months: €39.90 every 2 months (€19.95 a month, 20% off).
- VIP Keys Pass, 3 months: €94.95 today covers the first 3 months, then €94.95 a month until you cancel.
- VIP Keys Pass, Lifetime: €189.95 once. It never renews.

Prices in EUR. Renewal, cancellation and the VIP guarantee: [pricing.md](https://www.socials.homes/pricing.md).

## Key pages (markdown)

- [Pricing](https://www.socials.homes/pricing.md): every plan, price, billing interval, renewal and cancellation term, and the VIP guarantee
- [How it works](https://www.socials.homes/how-it-works.md): the three steps, and searching alone vs an agent vs Socials
- [FAQ](https://www.socials.homes/faq.md): cities, cost, cancellation, scams, timing
- [Homepage](https://www.socials.homes/index.md): the homepage in markdown
- [Reviews](https://www.socials.homes/reviews.md): what tenants said
- [About](https://www.socials.homes/about.md): why Socials exists
- [Contact](https://www.socials.homes/contact.md): email and Instagram
- [Housing by city](https://www.socials.homes/housing.md): all 124 cities with their search slugs
- [Guides](https://www.socials.homes/guides.md): renting, budgets, documents, scams, city guides
- [Developers](https://www.socials.homes/developers.md): the REST API, quickstart, limits, errors and versioning

## Section indexes

- [Pricing index](https://www.socials.homes/pricing/llms.txt)
- [How it works index](https://www.socials.homes/how-it-works/llms.txt)
- [Guides index](https://www.socials.homes/guides/llms.txt)
- [Housing and cities index](https://www.socials.homes/housing/llms.txt)

## REST API

- Base URL `https://www.socials.homes/api/v1`: public, anonymous, read-only JSON (GET only). [Developer docs](https://www.socials.homes/developers.md), [OpenAPI 3.1](https://www.socials.homes/openapi.json) (also [YAML](https://www.socials.homes/api/openapi.yaml)), [API catalog](https://www.socials.homes/.well-known/api-catalog) (RFC 9727)
- `GET /api/v1`: API index: every endpoint, the OpenAPI document, the docs and the rate limits
- `GET /api/v1/cities`: List the cities Socials Homes covers
- `GET /api/v1/cities/{slug}`: Get one city by its slug
- `GET /api/v1/cities/{slug}/supply`: Count live rental listings in a city, optionally at or under a monthly budget
- `GET /api/v1/plans`: List the plans with EUR prices, billing, renewal, inclusions and the VIP guarantee
- MCP server listings: [Smithery](https://smithery.ai/servers/alex-75ii/socials-homes) and the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=homes.socials)
- Official JavaScript SDK and CLI: [socials-homes on npm](https://www.npmjs.com/package/socials-homes) (`npx socials-homes supply amsterdam`), source on [GitHub](https://github.com/yosocials/socials-homes-js)
- Official Python SDK and CLI: [socials-homes on PyPI](https://pypi.org/project/socials-homes/) (`pip install socials-homes`, `uvx socials-homes plans`), source on [GitHub](https://github.com/yosocials/socials-homes-python)
- Rate limits per IP: 300 requests a minute across the API, and 600 an hour on the supply endpoint; RateLimit headers on every endpoint response, 429 with Retry-After over a limit. Errors are RFC 9457 problem details

## For agents

- [Agent view](https://www.socials.homes/?mode=agent): capabilities and how to start a search, in one page
- [Developer docs](https://www.socials.homes/developers.md): the public, read-only REST API, with no key needed, its [OpenAPI 3.1 document](https://www.socials.homes/openapi.json) and its [API catalog](https://www.socials.homes/.well-known/api-catalog)
- [Agent skill: find a rental home with Socials Homes](https://www.socials.homes/.well-known/agent-skills/socials-homes-rental-search/SKILL.md)
- [Agent skills index](https://www.socials.homes/.well-known/agent-skills/index.json)
- [Agentic resource catalog](https://www.socials.homes/.well-known/ard.json)
- [Schema map](https://www.socials.homes/schemamap.xml): schema.org feeds of the plans, cities and guides
- MCP server (Streamable HTTP, public, read-only, no sign-in): `https://www.socials.homes/mcp`, [server card](https://www.socials.homes/mcp/server-card): cities, plans, live listing counts, a signup link for a search
- Docs MCP server: `https://www.socials.homes/mcp/docs`, [server card](https://www.socials.homes/mcp/docs/server-card)
- NLWeb search (v0.55, public, read-only): `GET https://www.socials.homes/ask?query=...` streams results by default (`streaming=false` or `Accept: application/json` for JSON); `POST /ask` with `{"query": {"text": "..."}}` answers JSON (`prefer.streaming: true`, or `Accept: text/event-stream` when the body does not say, to stream). It searches the docs, guides and covered cities and answers schema.org results
- [Access](https://www.socials.homes/auth.md): no credentials are needed for any of these, the REST API included
- [Agent kit on GitHub](https://github.com/yosocials/socials-homes-agents): the skill, an Agent Plugin manifest and the MCP config (`npx skills add yosocials/socials-homes-agents`)
- [Sitemap](https://www.socials.homes/sitemap.xml)
- Any page as markdown: append `.md` to its URL, or request it with `Accept: text/markdown`

## Legal

- [Terms of service](https://www.socials.homes/terms), including the [VIP guarantee](https://www.socials.homes/terms#vip-guarantee)
- [Privacy policy](https://www.socials.homes/privacy)

## Optional

- [llms-full.txt](https://www.socials.homes/llms-full.txt): pricing, how it works, FAQ, about, reviews, contact and the city list in one file