# Casafari MCP and REST API: full reference > **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph). --- # Casafari MCP **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property in the graph is one record, merged from every source that advertises it and cleaned, with its full history: every price change, every status change, when it came on the market and when it was delisted. Residential and commercial property alike, for sale and for rent. [How the property graph is built](/docs/property-graph). Casafari MCP connects AI assistants and agents to it as [Model Context Protocol](https://modelcontextprotocol.io/) tools: the property graph, comparables and valuations, area insights, and agency and agent analysis. 22 tools in 3 products, behind one endpoint and one sign-in. The same data is also available over a [REST API](/docs/rest) (39 operations at `https://api.casafari.com`). Docs are organised by product, and each product lists its MCP tools and its REST operations; [MCP and REST compared](/docs/parity) shows where the two overlap and where they do not. ## Endpoint | | | |---|---| | Server URL | `https://mcp.casafari.com/` | | Transport | Streamable HTTP | | Sign-in | OAuth 2.1 with your Casafari account. See [Authentication](/docs/authentication). | | Server card | [https://mcp.casafari.com/.well-known/mcp/server-card.json](https://mcp.casafari.com/.well-known/mcp/server-card.json) | To add it to Claude, ChatGPT, Claude Code, Cursor or VS Code, see [Connect](/docs/connect). ## Products | Product | MCP tools | REST operations | What it answers | |---|---|---|---| | [Properties](/docs/properties) | — | 5 | Search the property graph, where every property is one record with its price and status history. Over REST: search by structured filters, fetch a property and its history by id, resolve a portal or agency ad id to the property it belongs to, create shareable links. | | [Comparables & Valuation](/docs/comparables-valuation) | 1 | 4 | Comparable properties and estimated prices for a home: properties on the market, past sales and rentals, and official registry records, matched around a point, an address or a cadastral reference. | | [Area Insights](/docs/area-insights) | 8 | 6 | Insights for an area: price, supply and activity over time, distributions by price, bedrooms and time on market, and market analysis. Over MCP also growth and volatility measures and heatmaps by district. | | [Alerts](/docs/alerts) | — | 12 | Alert feeds that follow the property graph for a set of filters: new properties, price rises and cuts, reservations, delistings and sales. Create a feed, read its alerts, or have them delivered to your webhook. | | [References](/docs/references) | — | 10 | The reference data requests are built from: property types, features and conditions, agencies, agents and the sources the graph is built from, locations with typeahead, and zip-code boundaries. | | [AgentGraph AI](/docs/agentgraph) | 13 | — | Find the real estate agencies and agents worth partnering with: area screens against partner profiles, full profiles, territory maps, partner briefs and watchlists. | ## How tools are named Every tool is named `_`: the prefix is the gateway's short name for the product (it calls it a group), the rest is the tool's own name, for example `comps_get-comparables` or `agentgraph_screen_agencies`. Always call a tool by its full name. The one exception is the gateway's own tool, [`list_servers`](/docs/gateway/list_servers), which has no prefix. ## Your account decides which tools you see `tools/list` returns only the tools your Casafari subscription covers, and rights are checked again on every call, so a change to your subscription applies on your next request. A tool that is missing from the list, or a call that is refused, means the subscription does not cover it; retrying will not help. When a product's quota is used up, its tools answer `Request limit reached for this product.` ## Start with `list_servers` Before using a product for the first time, call [`list_servers`](/docs/gateway/list_servers). It returns each product you can use (the gateway calls them groups) with its own instructions, for example which tool to start with. Most data tools take a location as ids, a circle or a polygon rather than a name: resolve a place name to ids with [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead) first (AgentGraph AI has its own [`agentgraph_find_location`](/docs/agentgraph/find_location) for Germany). ## Read these docs as Markdown Every page has a Markdown version: add `.md` to its URL, or send `Accept: text/markdown`. [/llms.txt](/llms.txt) lists every page and tool; [/llms-full.txt](/llms-full.txt) is the whole reference in one file. More in [For AI agents](/docs/agents). ## Questions and answers ### What is the difference between Casafari MCP and the Casafari REST API? Casafari MCP and the REST API serve the same property graph, but MCP serves assistants and agents and uses OAuth 2.1, while REST offers 39 operations and signs in with email and password. - MCP: one server at `https://mcp.casafari.com/` over Streamable HTTP, with a gateway that checks your account's rights on every call. It offers 22 data tools plus [`list_servers`](/docs/gateway/list_servers). - REST: base URL `https://api.casafari.com`, with no gateway. [`POST /login`](/docs/rest/authentication/login) returns an access token and a refresh token (JWT), and [`GET /refresh-token`](/docs/rest/authentication/refresh-token) renews it. The public OpenAPI description is at https://docs.api.casafari.com/openapi.json. Not everything is available over both. Properties, Alerts and References are REST only, AgentGraph AI is MCP only, and Area Insights and Comparables & Valuation differ in detail. See: [MCP and REST compared](/docs/parity), [REST API](/docs/rest), [Authentication](/docs/authentication). Permalink: /docs/faq/mcp-vs-rest-api ### How does authentication work on Casafari MCP? Does it use OAuth scopes? Casafari MCP is an OAuth 2.1 resource server with no OAuth scopes: a token carries exactly the rights of the Casafari account that signed in. `scopes_supported` in the protected resource metadata is empty on purpose. Rights are per tool and resolved from the account on every call, so `tools/list` shows only what the subscription covers, and any change takes effect on the next request. A person signs in through the authorization code flow with PKCE. An unattended agent uses client credentials issued by Casafari. Tokens are bound to the server's canonical URL as their audience, so every authorization and token request includes `resource`. The REST API works differently: you sign in with email and password to get a JWT. See: [Authentication](/docs/authentication), [casafari.com/auth.md](https://www.casafari.com/auth.md), [REST API](/docs/rest). Permalink: /docs/faq/how-authentication-works ### Who can use Casafari MCP? Anyone with a Casafari account that has an MCP subscription can use Casafari MCP. A token carries exactly that account's rights, and nothing works without one. To connect a client, you sign in with the account in a browser and approve. The assistant then acts with that account's rights. `tools/list` shows only the tools your subscription covers, and rights are resolved on every call. An agent that runs unattended uses client credentials that Casafari issues for the account. If you don't have a Casafari account, get one first. Without one, the sign-in flow has nothing to grant. See: [Connect your assistant](/docs/connect), [Authentication](/docs/authentication), [casafari.com/auth.md](https://www.casafari.com/auth.md). Permalink: /docs/faq/who-can-use ### What are Casafari MCP's rate limits and quotas? The documentation publishes no rate-limit or quota figures; the only documented limit is per product, and once a product's quota is used up, its tools return `Request limit reached for this product.` This message is a tool error, not an HTTP status. Stop calling that product and don't retry; the other products keep working. A missing tool or a refused call means something else: your subscription doesn't cover it. For `5xx` responses, retry with exponential backoff. See: [Authentication](/docs/authentication) (errors table). For quota and rate-limit figures, contact Casafari: https://www.casafari.com/ Permalink: /docs/faq/rate-limits-and-quotas ### Can I read these docs as Markdown, and is there an llms.txt? Yes: add `.md` to any page's URL or send `Accept: text/markdown`, and `/llms.txt` indexes every page and tool. None of it needs a key. - [/llms.txt](/llms.txt) is the index, and [/llms-full.txt](/llms-full.txt) holds the whole reference in one file. - [/tools.json](/tools.json) gives every tool's name, title, input schema and output schema. - You'll also find the [API catalog](/.well-known/api-catalog), [MCP server card](/.well-known/mcp/server-card.json), [agent skill](/.well-known/agent-skills/index.json), [agentic resource manifest](/.well-known/ai-catalog.json) and the sitemap at `/sitemap.xml`. - Markdown responses are served as `text/markdown`, with an `x-markdown-tokens` header that estimates their size. - In a browser that supports `navigator.modelContext`, pages register these WebMCP tools: `search_casafari_mcp_docs`, `get_casafari_tool_reference`, `get_casafari_rest_operation`, `get_casafari_connection_config` and `open_casafari_docs_page`. See: [For AI agents](/docs/agents). Permalink: /docs/faq/machine-readable-docs [All questions](/docs/faq) --- # The property graph **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. ## More than listings Listings are where Casafari starts, not what it delivers. A listing is one advertisement of a property on one source: an agency's own website or a portal. The same flat is usually advertised several times, by more than one agency and on more than one portal, at prices and with descriptions that do not always agree. Counting listings counts advertisements, not properties. Casafari takes those listings, structures them, cleans them and deduplicates them, and merges every listing of a property into one record. The records, the listings behind them, the agencies and agents that advertise them, their places and their history form the property graph: the most complete property index in Europe. ## How the graph is built 1. **Collect.** Listings from agency websites and portals in 16 countries, as they appear and as they change. 2. **Structure.** Every listing into one schema: type, operation, price, area, rooms, features, condition, energy rating and location. 3. **Clean.** Values normalised, places resolved to the location tree and to coordinates, outliers flagged. 4. **Deduplicate.** The same property, advertised by several agencies and portals, recognised as one. 5. **Merge into the graph.** One record per property, linking its listings, agencies, agents, location and history. ## The history of every property Because every listing of a property lands on the same record, the record keeps what happened to it, across every source: - **Price changes**, for sale and for rent: every change, with the old price, the new one and the dates. - **Status changes**: active, reserved, on hold, sold, rented. - **Listing and delisting**: when the property came on the market, on which sources, and when each listing was taken down. - **Time on the market**: for each property, and as distributions for an area. [Alerts](/docs/alerts) deliver the same history as it happens: new properties, price rises and cuts, reservations, delistings and sales, for any set of filters. ## Every asset class, for sale and for rent Residential and commercial property alike, in one taxonomy, with country-specific types mapped onto it: - **Residential**: apartments, studios, duplexes, penthouses, houses, villas, townhouses, chalets, bungalows, country houses, country estates, palaces and rooms. - **Commercial**: offices, retail, restaurants, hotels, industrial premises, warehouses, workshops and other commercial property. - **Buildings**: apartment buildings, office buildings and mixed-use buildings. - **Land**: urban and rural plots. - **Parking**: garages and parking spaces. - **New developments**: apartment and house developments. Each record carries the operations it is offered for, sale and rent, so one property for sale and to let is still one property. ## 16 countries, one schema The API covers Andorra, Austria, Belgium, France, Germany, Greece, Italy, Luxembourg, Monaco, Poland, Portugal, San Marino, Spain, Switzerland, the United Arab Emirates and the United States. Every market is structured the same way: the same property types, the same fields, and one location tree from country down to neighbourhood, with coordinates. A question asked about Lisbon, Madrid or Munich is answered in the same shape. ## What it means for an agent - **Count properties, not advertisements.** A property on three portals and two agency websites is one property, so totals, supply and averages are not inflated by duplicates. - **History comes with the record.** Price cuts, time on the market and delistings are on the property; there is no need to stitch advertisements together. - **One shape everywhere.** The same request works in every country the graph covers. - **Built on it:** [Properties](/docs/properties), [Comparables & Valuation](/docs/comparables-valuation), [Area Insights](/docs/area-insights), [Alerts](/docs/alerts) and [AgentGraph AI](/docs/agentgraph). ## Where it shows in the reference The API's field and operation names keep the word listing, because that is what they hold: `listing_id` is the id of one advertisement, `listings` are the ones merged into a property. The tools' and operations' own descriptions are quoted as each team publishes them. | In the API | What it is | |---|---| | [`property_id`](/docs/rest/properties/get-property-by-id-v1) | The property: one record in the graph. | | [`listings`](/docs/rest/properties/get-property-by-id-v1) | The listings merged into the property, each with its source, agency, price and dates. | | [`primary_listing_id`](/docs/rest/properties/search-properties-v2) | The listing chosen to represent the property. | | [`sale_price_history`, `rent_price_history`](/docs/rest/properties/get-property-by-id-v1) | Every price change, with the old price, the new one and the dates. | | [`sale_active_listings_count`, `rent_active_listings_count`](/docs/comparables-valuation/get-comparables) | How many live listings the property has right now, for sale and for rent. | | [`average_listings_per_property`](/docs/comparables-valuation/get-comparables) | In comparables statistics: how many listings, on average, each comparable property merges. | | [`POST /api/v1/properties/match-by-listings`](/docs/rest/properties/get-property-by-listing-ids-v1) | Send listing ids, get back the property each one belongs to. | | [Alert subtypes `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`](/docs/rest/alerts/search-alerts-v1) | The history as it happens, delivered to a feed or a webhook. | ## Questions about this - [What is Casafari MCP?](/docs/faq/what-is-casafari-mcp) - [What is Casafari?](/docs/faq/what-is-casafari) - [Can I build a market report with Casafari MCP?](/docs/faq/example-market-report) - [How do I look up one property and its price history?](/docs/faq/example-property-lookup) - [What is the Casafari property graph, and where does the data come from?](/docs/faq/what-is-the-property-graph) --- # Connect your assistant You need a Casafari account with MCP access, and a client that supports remote MCP servers over Streamable HTTP with OAuth. The server URL is the same everywhere: ```text https://mcp.casafari.com/ ``` The first time you connect, the client opens Casafari's sign-in page. Sign in with your Casafari account and approve; the assistant then acts with your account's rights. ## Claude 1. Open **Settings → Connectors** and choose **Add custom connector**. 2. Name it `Casafari` and paste `https://mcp.casafari.com/` as the URL. 3. Choose **Connect**, sign in with your Casafari account and approve. On Team and Enterprise plans an owner adds the connector for the organisation first; members then connect their own account. ## ChatGPT 1. Turn on **Developer mode** in ChatGPT's settings (Apps & Connectors, advanced settings). 2. Create a connector, paste `https://mcp.casafari.com/` as the MCP server URL and choose OAuth. 3. Sign in with your Casafari account and approve. ## Claude Code ```bash claude mcp add --transport http casafari https://mcp.casafari.com/ ``` Then run `/mcp` inside Claude Code and choose **Authenticate** for `casafari`. ## Cursor Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project): ```json { "mcpServers": { "casafari": { "url": "https://mcp.casafari.com/" } } } ``` ## VS Code Add to `.vscode/mcp.json`: ```json { "servers": { "casafari": { "type": "http", "url": "https://mcp.casafari.com/" } } } ``` ## Any other client or agent Point the client at `https://mcp.casafari.com/`. A request without a token answers `401` with a `WWW-Authenticate` header that leads to the sign-in metadata, and the client registers itself (dynamic client registration with PKCE). The steps are in [Authentication](/docs/authentication). An agent that runs without a person to sign in uses client credentials that Casafari issues for the account. ## Check it works Ask your assistant: *"Which Casafari products can I use?"* It should call [`list_servers`](/docs/gateway/list_servers) and name the products your subscription covers. ## Questions about this - [What is Casafari MCP?](/docs/faq/what-is-casafari-mcp) - [What is the Casafari MCP server URL?](/docs/faq/mcp-server-url) - [Which AI assistants and MCP clients work with Casafari MCP?](/docs/faq/supported-clients) - [Who can use Casafari MCP?](/docs/faq/who-can-use) - [How do I get access to Casafari MCP, and is there a free trial?](/docs/faq/how-to-get-access) --- # Authentication This page is about signing in to the MCP server. The REST API signs in differently, with an email and password and a bearer token: see [REST API](/docs/rest#get-a-token). The MCP server is an OAuth 2.1 resource server. Access is bound to a Casafari account with an MCP subscription: a token carries exactly that account's rights. Casafari does not use OAuth scopes; rights are per tool and resolved from the account on every call. The canonical, agent-facing version of this page is [casafari.com/auth.md](https://www.casafari.com/auth.md). ## Discovery A request without a token answers: ```http HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://mcp.casafari.com/.well-known/oauth-protected-resource" ``` 1. Fetch the protected resource metadata, [https://mcp.casafari.com/.well-known/oauth-protected-resource](https://mcp.casafari.com/.well-known/oauth-protected-resource). Its `resource` is the server's canonical URL: send it as the `resource` parameter in every authorization and token request, because tokens are bound to it as their audience. 2. Fetch the authorization server metadata, [https://api.casafari.com/.well-known/oauth-authorization-server](https://api.casafari.com/.well-known/oauth-authorization-server), for the registration, authorization and token endpoints. ## Sign in on behalf of a person 1. **Register** (once): `POST` to the registration endpoint with your client name and redirect URIs, `grant_types` `["authorization_code", "refresh_token"]` and `token_endpoint_auth_method` `none`. Keep the `client_id`. 2. **Authorize**: send the person to the authorization endpoint with PKCE (`S256`), `state` and `resource`. They sign in with their Casafari account and approve. 3. **Exchange the code** at the token endpoint, again with `resource` and the PKCE verifier. 4. **Call the server** with `Authorization: Bearer `. 5. **Refresh** with the refresh token when `expires_in` runs out. A `401` with `error="invalid_token"` on a token that used to work means it expired or was revoked: refresh it, and if that fails, authorize again. Keep the client; do not register again. ## Agents without a person An agent that runs unattended uses the client credentials grant. Such a client cannot register itself: Casafari issues a `client_id` and `client_secret` for the account, and the account owner hands them to the agent. ## Errors | Status | Where | Meaning | What to do | |---|---|---|---| | `400 invalid_client_metadata` | Registration | Unsupported grant types, redirect URIs or auth method | Fix the request; never ask for `client_credentials` there | | `401 invalid_client` | Token endpoint | Unknown `client_id` or wrong secret | Check the credential | | `401 invalid_token` | MCP server | Token missing, expired, revoked or bound to another resource | Refresh; if that fails, authorize again | | Tool missing, or a call refused | MCP server | The account has no right to that tool | Do not retry; the subscription does not cover it | | `Request limit reached for this product.` | MCP server | The product's quota is used up | Stop calling that product | | `5xx` | Anywhere | Transient error | Retry with exponential backoff | ## Questions about this - [What is the Casafari MCP server URL?](/docs/faq/mcp-server-url) - [What is the difference between Casafari MCP and the Casafari REST API?](/docs/faq/mcp-vs-rest-api) - [Which AI assistants and MCP clients work with Casafari MCP?](/docs/faq/supported-clients) - [Who can use Casafari MCP?](/docs/faq/who-can-use) - [Do I need an API key for Casafari MCP?](/docs/faq/api-key) --- # For AI agents This site is written for people and for agents alike. Everything on it is available in machine-readable form, and none of it needs a key. ## Read any page as Markdown Add `.md` to a page's URL, or send `Accept: text/markdown` with a normal `GET`. The response is `text/markdown` with an `x-markdown-tokens` header estimating its size. ```bash curl -H "Accept: text/markdown" https://platform.casafari.com/docs/area-insights/get_time_series_data ``` ## Entry points | What | Where | |---|---| | Index of every page and tool | [/llms.txt](/llms.txt) | | The whole reference in one file | [/llms-full.txt](/llms-full.txt) | | One tool's reference | `/docs//.md`, e.g. [/docs/comparables-valuation/get-comparables.md](/docs/comparables-valuation/get-comparables.md) | | One REST operation's reference | `/docs/rest//.md`, e.g. [/docs/rest/properties/search-properties-v2.md](/docs/rest/properties/search-properties-v2.md) | | The REST API, and how it compares with MCP | [/docs/rest.md](/docs/rest.md), [/docs/parity.md](/docs/parity.md) | | REST API description (OpenAPI) | [https://docs.api.casafari.com/openapi.json](https://docs.api.casafari.com/openapi.json) | | All tools as JSON (name, title, input and output schema) | [/tools.json](/tools.json) | | The same tools as OpenAPI (one POST path per tool) | [/mcp/openapi.json](/mcp/openapi.json) | | Data Export: bulk delivery and every entity's fields | [/docs/data-export.md](/docs/data-export.md) | | API catalog (RFC 9727) | [/.well-known/api-catalog](/.well-known/api-catalog) | | MCP server card | [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json), the same card as [mcp.casafari.com's](https://mcp.casafari.com/.well-known/mcp/server-card.json) | | Agent skill: how to use Casafari MCP well | [/.well-known/agent-skills/index.json](/.well-known/agent-skills/index.json) | | Agentic resource manifest (ARD) | [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) | | How to obtain a credential | [casafari.com/auth.md](https://www.casafari.com/auth.md) | | Sitemap | [/sitemap.xml](/sitemap.xml) | ## In the browser (WebMCP) Pages register WebMCP tools where the browser supports `navigator.modelContext`: `search_casafari_mcp_docs`, `get_casafari_tool_reference`, `get_casafari_rest_operation`, `get_casafari_connection_config` and `open_casafari_docs_page`. ## Using the server well - Call [`list_servers`](/docs/gateway/list_servers) before using a product for the first time. - Count properties, not advertisements: each property in the graph already merges every source that advertises it. See [The property graph](/docs/property-graph). - Resolve place names to location ids with [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead); most tools take ids, a circle or a polygon, not names. - The REST API has 39 operations and no gateway: sign in with `POST /login` ([REST API](/docs/rest#get-a-token)). Not everything is in both: [MCP and REST compared](/docs/parity) lists what exists where. - Read each tool's description and input schema before calling it: they are the contract, and these pages are generated from them. ## Questions about this - [How do I build my own application or agent on Casafari MCP?](/docs/faq/build-on-mcp) - [Why does Casafari count properties and not advertisements?](/docs/faq/count-properties-not-advertisements) - [Can I read these docs as Markdown, and is there an llms.txt?](/docs/faq/machine-readable-docs) --- # Casafari MCP: frequently asked questions Answers to what people and agents ask about Casafari MCP: what it is, where it covers, its products and tools, access, connecting a client, sign-in, limits, worked examples, the data and pricing. Every question has a permalink of its own; every answer links the page that documents it. ## What Casafari MCP is ### What is Casafari MCP? Casafari MCP is a single remote MCP server, `https://mcp.casafari.com/`, that gives an AI assistant or agent access to Casafari's real estate data: 22 data tools across 3 products. Casafari describes itself as the AI agent-native real estate data intelligence platform. The server uses Streamable HTTP and signs you in with OAuth 2.1 through your Casafari account. It acts as a gateway: it signs the user in, checks the account's rights on every call, and forwards each tool to the service that owns it. The products available over MCP are [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation), [Area Insights](https://platform.casafari.com/docs/area-insights) and [AgentGraph AI](https://platform.casafari.com/docs/agentgraph). The gateway also adds its own [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers), which shows which products your account can use. The same data is also available through a REST API. See: [Casafari MCP](https://platform.casafari.com/docs), [Connect your assistant](https://platform.casafari.com/docs/connect), [All tools](https://platform.casafari.com/docs/tools), [The property graph](https://platform.casafari.com/docs/property-graph). Permalink: https://platform.casafari.com/docs/faq/what-is-casafari-mcp ### What is Casafari? Casafari is a real estate data intelligence platform whose data is a deduplicated, cleaned property graph, with one record per property and its full history. Casafari gathers property advertisements from agency websites and portals and maps each one to a single schema: type, operation, price, area, rooms, features, condition, energy rating and location. It then cleans the values, detects when several agencies and portals are advertising the same property, and merges them into one record per property. That record holds every price change, status change, appearance and removal, each with its date. Residential and commercial properties, for sale and for rent, share one schema and one location tree. Count properties, not advertisements. Casafari describes the graph as the most complete property index in Europe ([why](https://platform.casafari.com/docs/faq#why-most-complete-property-index)). Casafari calls itself the AI agent-native real estate data intelligence platform. Assistants, agents and applications access the graph through Casafari MCP and the REST API. See [The property graph](https://platform.casafari.com/docs/property-graph) and https://www.casafari.com/. Permalink: https://platform.casafari.com/docs/faq/what-is-casafari ### What is the Casafari MCP server URL? The Casafari MCP server URL is `https://mcp.casafari.com/`. Every client uses the same address, served over Streamable HTTP with OAuth 2.1 sign-in. Paste it wherever your client asks for a remote MCP server URL. The first connection opens Casafari's sign-in page. A request without a token returns `401` with a `WWW-Authenticate` header that points to the sign-in metadata, so a client that supports OAuth discovers the rest on its own. Don't confuse it with the REST API, which lives at `https://api.casafari.com` and uses email and password sign-in. See: [Connect your assistant](https://platform.casafari.com/docs/connect) and [Authentication](https://platform.casafari.com/docs/authentication). Permalink: https://platform.casafari.com/docs/faq/mcp-server-url ### What is the difference between Casafari MCP and the Casafari REST API? Casafari MCP and the REST API serve the same property graph, but MCP serves assistants and agents and uses OAuth 2.1, while REST offers 39 operations and signs in with email and password. - MCP: one server at `https://mcp.casafari.com/` over Streamable HTTP, with a gateway that checks your account's rights on every call. It offers 22 data tools plus [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers). - REST: base URL `https://api.casafari.com`, with no gateway. [`POST /login`](https://platform.casafari.com/docs/rest/authentication/login) returns an access token and a refresh token (JWT), and [`GET /refresh-token`](https://platform.casafari.com/docs/rest/authentication/refresh-token) renews it. The public OpenAPI description is at https://docs.api.casafari.com/openapi.json. Not everything is available over both. Properties, Alerts and References are REST only, AgentGraph AI is MCP only, and Area Insights and Comparables & Valuation differ in detail. See: [MCP and REST compared](https://platform.casafari.com/docs/parity), [REST API](https://platform.casafari.com/docs/rest), [Authentication](https://platform.casafari.com/docs/authentication). Permalink: https://platform.casafari.com/docs/faq/mcp-vs-rest-api ### What is the Casafari MCP gateway, and what does `list_servers` do? The gateway is the Casafari MCP server: it signs you in, checks your rights on every call, and forwards each tool to the service that owns it; `list_servers` is a tool of the gateway itself. [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) takes no input. It returns every tool group your account can use, with each group's title, description, and usage instructions (for example, which tool to start with). Call it before you use a product for the first time. `tools/list` already returns only the tools your subscription covers, and rights are checked again on every call, so a subscription change takes effect on your next request. If `tools/list` is empty or a tool is missing, your subscription doesn't cover it. See: [Gateway](https://platform.casafari.com/docs/gateway) and [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers). Permalink: https://platform.casafari.com/docs/faq/gateway-and-list-servers ### Which AI assistants and MCP clients work with Casafari MCP? Casafari MCP works with any client that supports remote MCP servers over Streamable HTTP with OAuth. The Connect guide has steps for Claude, ChatGPT, Claude Code, Cursor and VS Code. - Claude: add a custom connector with the server URL. - ChatGPT: create a connector in Developer mode and select OAuth. - Claude Code: run `claude mcp add --transport http casafari https://mcp.casafari.com/`. - Cursor and VS Code: add an entry to `mcp.json`. - Any other client or your own agent: point it at `https://mcp.casafari.com/`. It discovers the sign-in metadata from the `401` response and registers itself using dynamic client registration with PKCE. In every case, you sign in with your Casafari account, and the assistant acts with that account's permissions. See: [Connect your assistant](https://platform.casafari.com/docs/connect) and [Authentication](https://platform.casafari.com/docs/authentication). Permalink: https://platform.casafari.com/docs/faq/supported-clients ## Coverage ### Which countries does Casafari cover? Casafari's API permissions list exactly 16 markets, and the documentation names no others. The market a given tool serves is only what that tool's own description says. - Andorra (AD) - United Arab Emirates (AE) - Austria (AT) - Belgium (BE) - Switzerland (CH) - Germany (DE) - Spain (ES) - France (FR) - Greece (GR) - Italy (IT) - Luxembourg (LU) - Monaco (MC) - Poland (PL) - Portugal (PT) - San Marino (SM) - United States (US) A few tools name a market in their own description. See [per-tool coverage](https://platform.casafari.com/docs/faq#per-tool-coverage). The documentation publishes no other country count. See: [Casafari MCP](https://platform.casafari.com/docs), [AgentGraph AI](https://platform.casafari.com/docs/agentgraph), [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation), [`POST /api/v1/references/locations/typeahead`](https://platform.casafari.com/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1). For anything not covered here, contact Casafari: https://www.casafari.com/ Permalink: https://platform.casafari.com/docs/faq/which-countries ### Does Casafari cover Spain and Portugal? Yes, Spain (ES) and Portugal (PT) are two of the 16 markets in Casafari's API permissions, and several tools mention them by name. - The REST typeahead [`POST /api/v1/references/locations/typeahead`](https://platform.casafari.com/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1) is scoped by country code and accepts ES or PT. - The comparables tool [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables) accepts a cadastral reference as its target point, but only for Spain. - Casafari's own example questions are set in Lisbon (comparables within 1 km of Avenida da Liberdade) and Valencia (asking price per m² for flats over three years). Other tools don't mention any market in their descriptions. See: [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation) and [Area Insights](https://platform.casafari.com/docs/area-insights). Permalink: https://platform.casafari.com/docs/faq/coverage-spain-portugal ### Does Casafari cover Germany? Yes: Germany (DE) is one of the 16 markets in Casafari's API permissions, and AgentGraph AI, the product for agencies and agents, is described for Germany. [`agentgraph_find_location`](https://platform.casafari.com/docs/agentgraph/find_location) looks up German cities, districts and states by name and returns their location ids, and [`agentgraph_screen_agencies`](https://platform.casafari.com/docs/agentgraph/screen_agencies) ranks the agencies active in a German area against partner profiles. Casafari's example question is: Which independent agencies in München are growing faster than the market? Tools in the other products don't name a market in their descriptions, so for those the documentation says no more than the permissions list does. See: [AgentGraph AI](https://platform.casafari.com/docs/agentgraph). Permalink: https://platform.casafari.com/docs/faq/coverage-germany ### What if the country I need is not on the list? If your market is not one of the 16 in Casafari's API permissions, this documentation does not cover it, and it publishes no roadmap. The hub names no other country and gives no date for new markets. Don't assume a market is served just because a tool accepts coordinates or a polygon. Coverage is defined by the permissions list and by each tool's own description. See [Which countries does Casafari cover?](https://platform.casafari.com/docs/faq#which-countries). For a market outside the 16, contact Casafari: https://www.casafari.com/ Permalink: https://platform.casafari.com/docs/faq/country-not-listed ### Does every tool cover all 16 countries? There is no per-tool country list: each tool covers what its own description says, and only three places in the documentation name a market. - [AgentGraph AI](https://platform.casafari.com/docs/agentgraph): its tools look up German cities, districts and states, and screen agencies and agents in a German area. - [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables): the cadastral-reference target point works in Spain only, while the coordinate and address inputs name no market. - [`POST /api/v1/references/locations/typeahead`](https://platform.casafari.com/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1): accepts ES or PT country codes. No other tool names a market, and the hub does not say which of the 16 markets each one serves. See: [All tools](https://platform.casafari.com/docs/tools). For a tool-by-tool answer, contact Casafari: https://www.casafari.com/ Permalink: https://platform.casafari.com/docs/faq/per-tool-coverage ## Products and tools ### Which products does Casafari MCP offer, and how many tools are there? Casafari MCP offers 22 data tools across 3 products behind the gateway, plus `list_servers`. Three more products are available over the REST API only, 39 operations in all. Over MCP: - [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation): 1 tool, `comps_get-comparables`. - [Area Insights](https://platform.casafari.com/docs/area-insights): 8 tools, named `ma_…`. - [AgentGraph AI](https://platform.casafari.com/docs/agentgraph): 13 tools, named `agentgraph_…`. - Gateway: [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers), with no prefix. Over REST only: - [Properties](https://platform.casafari.com/docs/properties): 5 operations. - [Alerts](https://platform.casafari.com/docs/alerts): 12 operations. - [References](https://platform.casafari.com/docs/references): 10 operations. Comparables & Valuation and Area Insights also have REST operations (4 and 6, respectively). See [MCP and REST compared](https://platform.casafari.com/docs/parity), and find every tool's schema at `/tools.json`. Permalink: https://platform.casafari.com/docs/faq/which-products ### What is Area Insights? Area Insights is Casafari's product for analysing an area rather than a single home: price, supply and activity over time; distributions by price, bedrooms and time on market; and market analysis. It offers 8 tools over MCP: - [`ma_get_location_typeahead`](https://platform.casafari.com/docs/area-insights/get_location_typeahead): turns a place name (in English) into location ids. - [`ma_get_time_series_data`](https://platform.casafari.com/docs/area-insights/get_time_series_data): one metric per week, month, quarter or year. - [`ma_get_time_series_operations`](https://platform.casafari.com/docs/area-insights/get_time_series_operations): growth and volatility measures such as mean, delta_pct, CAGR, std and cv. - [`ma_get_price_distribution`](https://platform.casafari.com/docs/area-insights/get_price_distribution), [`ma_get_bedrooms_distribution`](https://platform.casafari.com/docs/area-insights/get_bedrooms_distribution), [`ma_get_time_on_market_distribution`](https://platform.casafari.com/docs/area-insights/get_time_on_market_distribution). - [`ma_get_heatmap`](https://platform.casafari.com/docs/area-insights/get_heatmap): a metric for each child location, such as the districts of a city. - `ma_get_current_datetime`: today's date. It offers 6 operations over REST. Casafari's example question: "How has the asking price per m² of flats in Valencia moved over the last three years?" See [Area Insights](https://platform.casafari.com/docs/area-insights). Permalink: https://platform.casafari.com/docs/faq/what-is-area-insights ### What does Comparables & Valuation do? Comparables & Valuation returns comparable properties and estimated prices for a home, matched around a point, an address or a cadastral reference. It draws on properties on the market, past sales and rentals, and official registry records. Over MCP, it has 1 tool, [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables). The tool takes a circle (target point and radius in kilometres) or a closed polygon, an operation (sale or rent), property types and optional filters. It returns: - Ranked comparables with a similarity score - Aggregated statistics (average price, price per m², time on the market) - Estimated prices: fast-sell, fair-market and out-of-market The cadastral-reference input is for Spain only. Over REST, it has 4 operations: [`POST /api/v1/comparables/search`](https://platform.casafari.com/docs/rest/comparables-valuation/search-comparables-v1), [`POST /api/v2/comparables/search`](https://platform.casafari.com/docs/rest/comparables-valuation/search-comparables-v2), [`POST /api/v1/valuation/comparables-prices`](https://platform.casafari.com/docs/rest/comparables-valuation/search-estimated-prices-v1) and the REST-only [`POST /api/v2/comparables/ai-builder`](https://platform.casafari.com/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2). See [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation) and its [REST API](https://platform.casafari.com/docs/rest/comparables-valuation). Permalink: https://platform.casafari.com/docs/faq/what-is-comparables-valuation ### What is AgentGraph AI? AgentGraph AI finds the real estate agencies and agents in Germany worth partnering with, using area screens against partner profiles, full profiles, territory maps, partner briefs and watchlists. It offers 13 MCP tools and no REST operations: - Locate: [`agentgraph_find_location`](https://platform.casafari.com/docs/agentgraph/find_location). - Profiles: [`agentgraph_list_profiles`](https://platform.casafari.com/docs/agentgraph/list_profiles). - Screen: [`agentgraph_screen_agencies`](https://platform.casafari.com/docs/agentgraph/screen_agencies), [`agentgraph_screen_agents`](https://platform.casafari.com/docs/agentgraph/screen_agents). - Detail: `agentgraph_agency_profile`, `agentgraph_agent_profile`, [`agentgraph_partner_brief`](https://platform.casafari.com/docs/agentgraph/partner_brief). - Area: [`agentgraph_territory_map`](https://platform.casafari.com/docs/agentgraph/territory_map), `agentgraph_area_benchmark`. - Watchlist: [`agentgraph_save_to_watchlist`](https://platform.casafari.com/docs/agentgraph/save_to_watchlist), `agentgraph_remove_from_watchlist`, `agentgraph_watchlist`, `agentgraph_watchlist_changes`. Casafari's example question: Which independent agencies in München are growing faster than the market? See [AgentGraph AI](https://platform.casafari.com/docs/agentgraph). Permalink: https://platform.casafari.com/docs/faq/what-is-agentgraph ### Can I search properties over Casafari MCP? No. Properties is available only over the REST API, with 5 operations and no MCP tool, so an assistant can't search the property graph through Casafari MCP. Over REST you can: - search with structured filters: [`POST /api/v2/properties/search`](https://platform.casafari.com/docs/rest/properties/search-properties-v2) (and [`POST /api/v1/properties/search`](https://platform.casafari.com/docs/rest/properties/search-properties-v1)); - fetch a property and its history by id: [`GET /api/v1/properties/search/{property_id}`](https://platform.casafari.com/docs/rest/properties/get-property-by-id-v1); - resolve a portal or agency ad id to its property: [`POST /api/v1/properties/match-by-listings`](https://platform.casafari.com/docs/rest/properties/get-property-by-listing-ids-v1); - create shareable links: [`POST /api/v1/properties/smart-links`](https://platform.casafari.com/docs/rest/properties/create-a-smart-link-beta-v1) (BETA). Each property is a single record with its price and status history. The closest options over MCP are comparables around a point (Comparables & Valuation) and area statistics (Area Insights). See: [Properties](https://platform.casafari.com/docs/properties), [Properties REST API](https://platform.casafari.com/docs/rest/properties), [MCP and REST compared](https://platform.casafari.com/docs/parity). Permalink: https://platform.casafari.com/docs/faq/properties-over-mcp ### Can I get alerts (new properties, price cuts, sales) over Casafari MCP? No. Alerts is available only through the REST API, which has 12 operations; there is no MCP tool. An alert feed tracks the property graph for a set of filters and reports new properties, price rises and cuts, reservations, removals and sales. You can create a feed, read its alerts, or have them delivered to your webhook: - [`POST /alerts-api/feeds`](https://platform.casafari.com/docs/rest/alerts/create-feed) creates a feed, and [`GET /alerts-api/feeds`](https://platform.casafari.com/docs/rest/alerts/list-feeds) returns your feeds. - [`PUT /alerts-api/webhooks`](https://platform.casafari.com/docs/rest/alerts/set-webhook-url) sets the webhook URL, and [`POST /alerts-api/webhooks/rotate-secret`](https://platform.casafari.com/docs/rest/alerts/rotate-signing-secret) rotates the signing secret. - The v1 operations under `/api/v1/listing-alerts/` create, read, update and delete feeds, and search alerts. See: [Alerts](https://platform.casafari.com/docs/alerts), [Alerts REST API](https://platform.casafari.com/docs/rest/alerts), [MCP and REST compared](https://platform.casafari.com/docs/parity). Permalink: https://platform.casafari.com/docs/faq/alerts-over-mcp ### What are the References operations for? References is the REST-only set of 10 operations that return the reference data other requests are built from: property types, features, conditions, agencies, agents, sources, locations and zip-code boundaries. - [`GET /api/v1/references/types`](https://platform.casafari.com/docs/rest/references/get-types-v1), [`GET /api/v1/references/features`](https://platform.casafari.com/docs/rest/references/get-features-v1), [`GET /api/v1/references/conditions`](https://platform.casafari.com/docs/rest/references/get-conditions-v1): the values property filters accept, including which countries each type is available in. - [`GET /api/v1/references/agencies`](https://platform.casafari.com/docs/rest/references/get-agencies-v1), `GET /api/v1/references/agents`, `GET /api/v1/references/sources`: agencies, agents and the sources the graph is built from. - [`POST /api/v1/references/locations`](https://platform.casafari.com/docs/rest/references/get-locations-v1), `GET /api/v1/references/locations/by-coordinates`, `POST /api/v1/references/locations/typeahead`: the location tree, looked up by name, by coordinates or by typeahead scoped to ES or PT. - [`POST /api/v1/references/zipcode-boundary`](https://platform.casafari.com/docs/rest/references/get-zipcode-boundary-by-zipcode-and-country-code-v1): the boundary of a zip code within a country. References has no MCP tool. Over MCP, `ma_get_location_typeahead` resolves place names. See: [References](https://platform.casafari.com/docs/references) and [References REST API](https://platform.casafari.com/docs/rest/references). Permalink: https://platform.casafari.com/docs/faq/what-is-references ### Which tools exist only over MCP, and which operations only over REST? Three Area Insights tools and all 13 AgentGraph AI tools are available only over MCP; Properties, Alerts, References, the comparables AI builder, and two Area Insights operations are available only over REST. MCP only: - [`ma_get_current_datetime`](https://platform.casafari.com/docs/area-insights/get_current_datetime), [`ma_get_time_series_operations`](https://platform.casafari.com/docs/area-insights/get_time_series_operations), and [`ma_get_heatmap`](https://platform.casafari.com/docs/area-insights/get_heatmap). - Every `agentgraph_…` tool. REST only: - All 5 Properties, 12 Alerts, and 10 References operations. - [`POST /api/v2/comparables/ai-builder`](https://platform.casafari.com/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2). - [`POST /market-analytics-api/distributions/properties`](https://platform.casafari.com/docs/rest/area-insights/properties-distribution) and [`POST /market-analytics-api/analysis`](https://platform.casafari.com/docs/rest/area-insights/analysis). Everything else is available over both: comparables search and the Area Insights time series and distributions. See [MCP and REST compared](https://platform.casafari.com/docs/parity). Permalink: https://platform.casafari.com/docs/faq/mcp-only-and-rest-only ### How are Casafari MCP tools named? Casafari MCP tools follow the pattern `_`, such as `comps_get-comparables` or `ma_get_heatmap`. The only tool without a prefix is the gateway's `list_servers`. The group is the product namespace: `comps` for Comparables & Valuation, `ma` for Area Insights, and `agentgraph` for AgentGraph AI. The tool part is whatever name the owning service uses, so it can contain hyphens or underscores. Clients call each tool by its exact name, and the documentation always writes names exactly as they are called. [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) returns the namespaces available to your account, and `/tools.json` gives every tool's name, title, input schema and output schema. See: [All tools](https://platform.casafari.com/docs/tools) and [/tools.json](https://platform.casafari.com/tools.json). Permalink: https://platform.casafari.com/docs/faq/tool-naming ## Access ### Who can use Casafari MCP? Anyone with a Casafari account that has an MCP subscription can use Casafari MCP. A token carries exactly that account's rights, and nothing works without one. To connect a client, you sign in with the account in a browser and approve. The assistant then acts with that account's rights. `tools/list` shows only the tools your subscription covers, and rights are resolved on every call. An agent that runs unattended uses client credentials that Casafari issues for the account. If you don't have a Casafari account, get one first. Without one, the sign-in flow has nothing to grant. See: [Connect your assistant](https://platform.casafari.com/docs/connect), [Authentication](https://platform.casafari.com/docs/authentication), [casafari.com/auth.md](https://www.casafari.com/auth.md). Permalink: https://platform.casafari.com/docs/faq/who-can-use ### How do I get access to Casafari MCP, and is there a free trial? Contact Casafari through the "Contact us" button on its MCP page (https://www.casafari.com/products/property-data-mcp-ai-agents/), since access requires a Casafari account with an MCP subscription. The casafari.com navigation also shows a "Start free trial" button, but the documentation doesn't say what a trial includes. Once you have an account, connecting takes a minute: paste `https://mcp.casafari.com/` into your client, sign in, and approve. Your assistant will then see exactly the tools your subscription covers. See: [Connect your assistant](https://platform.casafari.com/docs/connect). Permalink: https://platform.casafari.com/docs/faq/how-to-get-access ### Do I need an API key for Casafari MCP? No, Casafari MCP doesn't use an API key: you sign in with OAuth 2.1 through your Casafari account, and the token you get carries that account's rights. - Interactive clients (Claude, ChatGPT, Cursor, VS Code, Claude Code) open Casafari's sign-in page the first time you connect, so you never paste a credential. - Your own client registers itself and uses PKCE, so it needs no secret. - An agent with no person to approve uses a `client_id` and `client_secret` that Casafari issues for the account (client credentials grant). - The REST API works differently: [`POST /login`](https://platform.casafari.com/docs/rest/authentication/login) with email and password returns a JWT access token and a refresh token. See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md). Permalink: https://platform.casafari.com/docs/faq/api-key ## Connect a client ### How do I connect Casafari MCP to Claude? In Claude, go to Settings → Connectors, choose Add custom connector, name it `Casafari`, paste `https://mcp.casafari.com/` as the URL, and connect. 1. Open **Settings → Connectors** and choose **Add custom connector**. 2. Name it `Casafari` and paste `https://mcp.casafari.com/` as the URL. 3. Choose **Connect**, sign in with your Casafari account, and approve. On Team and Enterprise, an owner first adds the connector for the organisation, and then members connect their own accounts. To check that it works, ask: "Which Casafari products can I use?" Claude should call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) and name the products your subscription covers. See: [Connect your assistant](https://platform.casafari.com/docs/connect). Permalink: https://platform.casafari.com/docs/faq/connect-claude ### How do I connect Casafari MCP to ChatGPT? In ChatGPT, turn on Developer mode, create a connector with `https://mcp.casafari.com/` as the MCP server URL, choose OAuth, then sign in with your Casafari account and approve. 1. In ChatGPT's settings, turn on **Developer mode** (under Apps & Connectors, in the advanced settings). 2. Create a connector, paste `https://mcp.casafari.com/` as the MCP server URL, and choose OAuth. 3. Sign in with your Casafari account and approve. ChatGPT then acts with your account's permissions, so it sees only the tools your subscription covers. To check, ask which Casafari products you can use. It should call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) and name them. See: [Connect your assistant](https://platform.casafari.com/docs/connect). Permalink: https://platform.casafari.com/docs/faq/connect-chatgpt ### How do I add Casafari MCP to Claude Code? Run `claude mcp add --transport http casafari https://mcp.casafari.com/`, then run `/mcp` in Claude Code and choose Authenticate for `casafari`. 1. In a terminal, run `claude mcp add --transport http casafari https://mcp.casafari.com/`. 2. In Claude Code, run `/mcp`. 3. Choose **Authenticate** for `casafari`, sign in to your Casafari account in the browser, and approve access. The `--transport http` flag selects the Streamable HTTP transport. After you authenticate, Claude Code shows the tools your subscription covers. Call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) first to read each product's instructions. See [Connect your assistant](https://platform.casafari.com/docs/connect). Permalink: https://platform.casafari.com/docs/faq/connect-claude-code ### How do I add Casafari MCP to Cursor? Add a `casafari` entry with the URL `https://mcp.casafari.com/` under `mcpServers` in `~/.cursor/mcp.json`, or in `.cursor/mcp.json` within a project. ```json { "mcpServers": { "casafari": { "url": "https://mcp.casafari.com/" } } } ``` Cursor opens Casafari's sign-in page the first time it connects; sign in with your Casafari account and approve. The server uses Streamable HTTP with OAuth, so no key goes in the file. Once connected, the tools your subscription covers appear; start with [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers). See: [Connect your assistant](https://platform.casafari.com/docs/connect). Permalink: https://platform.casafari.com/docs/faq/connect-cursor ### How do I add Casafari MCP to VS Code? In `.vscode/mcp.json`, add a `casafari` server under `servers` with `"type": "http"` and the URL `https://mcp.casafari.com/`. ```json { "servers": { "casafari": { "type": "http", "url": "https://mcp.casafari.com/" } } } ``` VS Code opens Casafari's sign-in page the first time it connects; sign in with your Casafari account and approve. The server uses Streamable HTTP with OAuth, so no key goes in the file. Once connected, the tools your subscription covers appear; start with [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers). See: [Connect your assistant](https://platform.casafari.com/docs/connect). Permalink: https://platform.casafari.com/docs/faq/connect-vscode ### How do I connect any other MCP client or my own agent? Point the client at `https://mcp.casafari.com/` and let it register itself and sign in with PKCE. The `401` it receives carries a `WWW-Authenticate` header that points to the sign-in metadata. 1. Fetch the protected resource metadata named in the header, then the authorization server metadata it points to. 2. Register once at the registration endpoint (dynamic client registration) and keep the `client_id`. 3. Send the person to the authorization endpoint with PKCE, `state` and `resource`, then exchange the code for tokens. 4. Call the server with `Authorization: Bearer `, and refresh the token when it expires. An agent that runs without a person to sign in can't register itself. Instead, it uses client credentials that Casafari issues for the account. Call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) before using a product. See: [Connect your assistant](https://platform.casafari.com/docs/connect), [Authentication](https://platform.casafari.com/docs/authentication), [casafari.com/auth.md](https://www.casafari.com/auth.md). Permalink: https://platform.casafari.com/docs/faq/connect-other-client ### How do I check that Casafari MCP is connected and working? Ask your assistant which Casafari products you can use: it should call `list_servers` and name the products your subscription covers. If it does, your connection, sign-in and access rights all work. If the assistant can't see the server, check that the URL is exactly `https://mcp.casafari.com/` and that the client completed the OAuth sign-in. If a product or tool you expected is missing, that isn't a connection fault: `tools/list` returns only the tools your subscription covers, so retrying won't help. If a connection that used to work returns a `401` with `invalid_token`, the token has expired or been revoked: let the client refresh it, or sign in again. See: [Connect your assistant](https://platform.casafari.com/docs/connect), [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers), [Why is a tool missing or a call refused?](https://platform.casafari.com/docs/faq#tool-missing-or-refused). Permalink: https://platform.casafari.com/docs/faq/verify-connection ## Authentication ### How does authentication work on Casafari MCP? Does it use OAuth scopes? Casafari MCP is an OAuth 2.1 resource server with no OAuth scopes: a token carries exactly the rights of the Casafari account that signed in. `scopes_supported` in the protected resource metadata is empty on purpose. Rights are per tool and resolved from the account on every call, so `tools/list` shows only what the subscription covers, and any change takes effect on the next request. A person signs in through the authorization code flow with PKCE. An unattended agent uses client credentials issued by Casafari. Tokens are bound to the server's canonical URL as their audience, so every authorization and token request includes `resource`. The REST API works differently: you sign in with email and password to get a JWT. See: [Authentication](https://platform.casafari.com/docs/authentication), [casafari.com/auth.md](https://www.casafari.com/auth.md), [REST API](https://platform.casafari.com/docs/rest). Permalink: https://platform.casafari.com/docs/faq/how-authentication-works ### How does a client discover Casafari's authorization server? A client discovers it in two hops: the `WWW-Authenticate` header on a `401` response points to the protected resource metadata at `https://mcp.casafari.com/.well-known/oauth-protected-resource`, and that document points to the authorization server at `https://api.casafari.com/.well-known/oauth-authorization-server`. 1. Read the protected resource metadata for `resource`, `authorization_servers`, `scopes_supported` (intentionally empty) and `resource_documentation`. `resource` is the server's canonical URL. Send it as the `resource` parameter in every authorization and token request, because tokens are bound to it as their audience. 2. Read the authorization server metadata for `registration_endpoint`, `authorization_endpoint` and `token_endpoint`. Take the supported grant types, code challenge methods and auth methods from this metadata, not from a guide. Read the live documents, not a copy. A token minted without `resource` has no audience, and the server rejects it. See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md). Permalink: https://platform.casafari.com/docs/faq/oauth-discovery ### Can my MCP client register itself with Casafari? Yes, a client that acts for a signed-in person can register itself once at the registration endpoint; a client with no person to sign in cannot, and uses credentials Casafari issues instead. Send a `POST` with `client_name`, your `redirect_uris`, `grant_types` set to `["authorization_code", "refresh_token"]`, and `token_endpoint_auth_method` set to `none`. Each redirect URI must use `https`, `http` on a loopback host, or a private-use scheme, and must not include a fragment. Any other grant type, redirect URI, or auth method is rejected with `400 invalid_client_metadata`, so never request `client_credentials` there. The `201` response contains the `client_id`. Store it and don't register again. A public client has no secret and authenticates with PKCE (`S256`). See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md). Permalink: https://platform.casafari.com/docs/faq/dynamic-client-registration ### How does an agent sign in when no person is there to approve? An agent that runs with no person present signs in with the client credentials grant, using a `client_id` and `client_secret` that Casafari issues for the account. The agent cannot register itself. 1. The account owner gets the credentials from Casafari and gives them to the agent. 2. The agent posts `grant_type=client_credentials` and `resource` to the token endpoint. It authenticates with HTTP Basic (`client_id:client_secret`) or by sending the secret in the form body (`client_secret_post`). 3. It then calls `https://mcp.casafari.com/` with `Authorization: Bearer `, exactly as a user-authorized client does. Requesting `client_credentials` from the registration endpoint fails with `400 invalid_client_metadata`. The token still carries only the account's rights. See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md). Permalink: https://platform.casafari.com/docs/faq/unattended-agents ### What happens when my access token expires? When your access token expires, exchange the refresh token at the token endpoint with `grant_type=refresh_token`, your `client_id`, and `resource`; the `expires_in` value in the token response is the authoritative lifetime. A `401` with `error="invalid_token"` on a token that used to work means it has expired, been revoked, or is bound to another resource. Refresh it, and if the refresh fails, send the person through authorization again. Keep the client and its `client_id`; don't register again. The documentation publishes no token lifetime beyond `expires_in`. For the REST API, [`GET /refresh-token`](https://platform.casafari.com/docs/rest/authentication/refresh-token) renews the JWT, and a `401` from that endpoint means you need to log in again. See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md). Permalink: https://platform.casafari.com/docs/faq/token-expiry-refresh ### How do I authenticate with the Casafari REST API? Authenticate with the Casafari REST API by sending your `email` and `password` as JSON to `POST https://api.casafari.com/login`. It returns a JWT access token and a refresh token; the API doesn't use OAuth. 1. Send `{ "email": …, "password": … }` to [`POST /login`](https://platform.casafari.com/docs/rest/authentication/login). It responds `200` with `access_token` and `refresh_token`. 2. Include `Authorization: Bearer ` when you call any operation. 3. To get a new `access_token`, call [`GET /refresh-token`](https://platform.casafari.com/docs/rest/authentication/refresh-token) with the refresh token as the bearer. A `401` from either endpoint means the credentials are wrong or the refresh token has expired, so log in again. A `422` from `/login` means the body is malformed, so send `email` and `password` as JSON. After you sign in, https://docs.api.casafari.com/ shows which operations your account may call. See: [REST API](https://platform.casafari.com/docs/rest) and [REST authentication](https://platform.casafari.com/docs/rest/authentication). Permalink: https://platform.casafari.com/docs/faq/rest-authentication ## Limits, quotas and errors ### What are Casafari MCP's rate limits and quotas? The documentation publishes no rate-limit or quota figures; the only documented limit is per product, and once a product's quota is used up, its tools return `Request limit reached for this product.` This message is a tool error, not an HTTP status. Stop calling that product and don't retry; the other products keep working. A missing tool or a refused call means something else: your subscription doesn't cover it. For `5xx` responses, retry with exponential backoff. See: [Authentication](https://platform.casafari.com/docs/authentication) (errors table). For quota and rate-limit figures, contact Casafari: https://www.casafari.com/ Permalink: https://platform.casafari.com/docs/faq/rate-limits-and-quotas ### Why is a tool missing from `tools/list`, or a call refused? If a tool is missing from `tools/list` or a call is refused, your account's subscription does not cover that tool, so retrying will not help. `tools/list` returns only the tools your subscription covers, and the gateway checks rights again on every call. A subscription change in either direction takes effect on the next request, so there is nothing to reconnect or clear. To see which products you can use, call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers). This differs from two other errors: - `Request limit reached for this product.` means the product's quota is used up. - `401 invalid_token` means the token has expired or been revoked. See: [Authentication](https://platform.casafari.com/docs/authentication) and [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers). Permalink: https://platform.casafari.com/docs/faq/tool-missing-or-refused ### Which Casafari MCP errors should I retry, and which not? Retry only `5xx` responses, using exponential backoff; every other documented error calls for a fix on your side, not a retry. - `400 invalid_client_metadata` (registration): fix the request, and never request `client_credentials` there. - `401 invalid_client` (token endpoint): check the credential. - `401 invalid_token` (MCP server): refresh the token; if that fails, authorize again. - Tool missing or call refused: don't retry, because your subscription doesn't cover it. - `Request limit reached for this product.`: stop calling that product. - REST `401` on `/login` or `/refresh-token`: log in again. REST `422` on `/login`: send `email` and `password` as JSON. See the errors table in [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md). Permalink: https://platform.casafari.com/docs/faq/which-errors-to-retry ## Use cases and worked examples ### How do I value a home or find comparables with Casafari MCP? To value a home or find comparables, ask your assistant for comparables around an address, as in Casafari's example: a 3-bedroom flat near Avenida da Liberdade, Lisbon, with comparables within 1 km. 1. The assistant calls [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables) with a circle. The target point is the address, coordinates or, in Spain, a cadastral reference, and the call also includes the distance in kilometres, operation `sale`, type `apartment` and `bedrooms`. 2. It returns comparables ranked by similarity, with price, area, status, dates and price-change history. It also returns aggregated statistics and fast-sell, fair-market and out-of-market price estimates. 3. Set `sold_or_rented_after` to a date to include properties sold or rented since then, or to `null` for active properties only. Over REST, [`POST /api/v2/comparables/search`](https://platform.casafari.com/docs/rest/comparables-valuation/search-comparables-v2) and [`POST /api/v1/valuation/comparables-prices`](https://platform.casafari.com/docs/rest/comparables-valuation/search-estimated-prices-v1) do the same job. For area-level questions, first resolve the place with [`ma_get_location_typeahead`](https://platform.casafari.com/docs/area-insights/get_location_typeahead). See: [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation). Permalink: https://platform.casafari.com/docs/faq/example-valuation ### How do I analyse how prices in an area have moved over time? Resolve the place to a location id with `ma_get_location_typeahead`, fetch the series with `ma_get_time_series_data`, then calculate growth and volatility with `ma_get_time_series_operations`. 1. [`ma_get_location_typeahead`](https://platform.casafari.com/docs/area-insights/get_location_typeahead): pass the place name in English and pick the `location_id` you want. Check the breadcrumbs when names repeat. 2. [`ma_get_time_series_data`](https://platform.casafari.com/docs/area-insights/get_time_series_data): request `type_group` `apartment`, `business_type` `sale`, `data_point` `avg_price_psqm` and `date_interval` `month`, with a `date_range` and the location ids. Each point holds one period's value. 3. [`ma_get_time_series_operations`](https://platform.casafari.com/docs/area-insights/get_time_series_operations): request the same segment with operations such as `mean`, `delta_pct`, `cagr`, `std` and `cv`. Casafari's example question: How has the asking price per m² of flats in Valencia moved over the last three years? Over REST, [`POST /market-analytics-api/time-series`](https://platform.casafari.com/docs/rest/area-insights/time-series) returns the series. See: [Area Insights](https://platform.casafari.com/docs/area-insights). Permalink: https://platform.casafari.com/docs/faq/example-price-trend ### How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap? Area Insights has a tool for each distribution (`ma_get_price_distribution`, `ma_get_bedrooms_distribution` and `ma_get_time_on_market_distribution`) plus `ma_get_heatmap`, which shows a metric for each district. - [`ma_get_price_distribution`](https://platform.casafari.com/docs/area-insights/get_price_distribution): returns price intervals, the number of properties in each, and a flag marking the interval that contains the mean. - [`ma_get_bedrooms_distribution`](https://platform.casafari.com/docs/area-insights/get_bedrooms_distribution): returns, for each bedroom count, the number of properties, the average price and the average price per m². - [`ma_get_time_on_market_distribution`](https://platform.casafari.com/docs/area-insights/get_time_on_market_distribution): returns, for each price interval, the average days and months on the market and the number of properties. - [`ma_get_heatmap`](https://platform.casafari.com/docs/area-insights/get_heatmap): returns the chosen `data_point` for the child locations of a `location_id` (the districts of a city), based on active properties only. Available over MCP only. All four take a `type_group`, a `business_type` and a location boundary (ids or a circle). The [price](https://platform.casafari.com/docs/rest/area-insights/price-distribution), [bedrooms](https://platform.casafari.com/docs/rest/area-insights/bedrooms-distribution) and [time on market](https://platform.casafari.com/docs/rest/area-insights/time-on-market-distribution) distributions are also available over REST. See: [Area Insights](https://platform.casafari.com/docs/area-insights). Permalink: https://platform.casafari.com/docs/faq/example-distributions-heatmap ### Can I build a market report with Casafari MCP? Yes: Casafari MCP supplies the figures and your assistant writes the report, though the hub documents tools, not report formats or exports. An area report draws on Area Insights: the time series and its operations for trend and volatility, the distributions of price, bedrooms and time on market, and [`ma_get_heatmap`](https://platform.casafari.com/docs/area-insights/get_heatmap) for the districts. A report on a single home draws on [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables) for comparables and estimated prices. [`ma_get_current_datetime`](https://platform.casafari.com/docs/area-insights/get_current_datetime) gives the assistant today's date for setting date ranges. Count properties rather than advertisements, since each record in the graph already merges every source. No template, PDF export or scheduling is documented. See: [Area Insights](https://platform.casafari.com/docs/area-insights) and [The property graph](https://platform.casafari.com/docs/property-graph). Permalink: https://platform.casafari.com/docs/faq/example-market-report ### How do I find agencies or agents to partner with in a German city? Use AgentGraph AI: find the location, review the partner profiles, screen agencies or agents, open a profile, get a partner brief, then watch the ones you choose. 1. [`agentgraph_find_location`](https://platform.casafari.com/docs/agentgraph/find_location): use this when a name is ambiguous or you want a district. 2. [`agentgraph_list_profiles`](https://platform.casafari.com/docs/agentgraph/list_profiles): see the rules behind each profile. 3. [`agentgraph_screen_agencies`](https://platform.casafari.com/docs/agentgraph/screen_agencies) or [`agentgraph_screen_agents`](https://platform.casafari.com/docs/agentgraph/screen_agents): screen the area, optionally with a profile, postcodes and thresholds. 4. `agentgraph_agency_profile` or `agentgraph_agent_profile`: view one result in full. 5. [`agentgraph_partner_brief`](https://platform.casafari.com/docs/agentgraph/partner_brief): get a one-page brief with a printable page valid for 7 days. 6. [`agentgraph_save_to_watchlist`](https://platform.casafari.com/docs/agentgraph/save_to_watchlist), then [`agentgraph_watchlist_changes`](https://platform.casafari.com/docs/agentgraph/watchlist_changes) (default: the last 7 days). For area context, use `agentgraph_area_benchmark` and `agentgraph_territory_map`. Example from Casafari: "Which independent agencies in München are growing faster than the market?" Germany only. See: [AgentGraph AI](https://platform.casafari.com/docs/agentgraph). Permalink: https://platform.casafari.com/docs/faq/example-find-agencies-germany ### How do I look up one property and its price history? Use the REST API: `GET /api/v1/properties/search/{property_id}` returns a single property with its history, and `POST /api/v1/properties/match-by-listings` resolves an ad id from a portal or agency to its property. 1. If you have an ad id from a portal or agency site, call [`POST /api/v1/properties/match-by-listings`](https://platform.casafari.com/docs/rest/properties/get-property-by-listing-ids-v1) to find the property it belongs to. 2. If you have a property id, call [`GET /api/v1/properties/search/{property_id}`](https://platform.casafari.com/docs/rest/properties/get-property-by-id-v1). The record includes `sale_price_history` and `rent_price_history`, with dates and statuses such as active, reserved, hold, sold and rented. 3. To find properties, use [`POST /api/v2/properties/search`](https://platform.casafari.com/docs/rest/properties/search-properties-v2) with structured filters. 4. To share a property, create a smart link with [`POST /api/v1/properties/smart-links`](https://platform.casafari.com/docs/rest/properties/create-a-smart-link-beta-v1) (BETA). No MCP tool is available for this. See: [Properties](https://platform.casafari.com/docs/properties) and [The property graph](https://platform.casafari.com/docs/property-graph). Permalink: https://platform.casafari.com/docs/faq/example-property-lookup ### How do I turn a place name into a location id? Use `ma_get_location_typeahead` to turn an English place name into location ids. Most Casafari tools take a location as ids, a circle or a polygon rather than a name. - Over MCP, [`ma_get_location_typeahead`](https://platform.casafari.com/docs/area-insights/get_location_typeahead) returns each match with its `location_id`, administrative level and breadcrumbs. If several places share a name, add more detail to the request. The ids it returns work with the Area Insights tools. - For Germany, [`agentgraph_find_location`](https://platform.casafari.com/docs/agentgraph/find_location) finds cities, districts and states. The AgentGraph AI tools also accept a name or a postcode directly. - Over REST, [`POST /api/v1/references/locations/typeahead`](https://platform.casafari.com/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1) is scoped to ES or PT. [`GET /api/v1/references/locations/by-coordinates`](https://platform.casafari.com/docs/rest/references/get-location-by-passed-coordinates-v1) resolves a point, and [`POST /api/v1/references/locations`](https://platform.casafari.com/docs/rest/references/get-locations-v1) reads the location tree. `comps_get-comparables` doesn't need an id. It takes coordinates, an address or a cadastral reference. See: [Area Insights](https://platform.casafari.com/docs/area-insights) and [References](https://platform.casafari.com/docs/references). Permalink: https://platform.casafari.com/docs/faq/location-ids ### How do I get alerts delivered to a webhook? Use the REST API: create a feed with `POST /alerts-api/feeds`, set your webhook URL with `PUT /alerts-api/webhooks`, and rotate its signing secret with `POST /alerts-api/webhooks/rotate-secret`. 1. [`POST /alerts-api/feeds`](https://platform.casafari.com/docs/rest/alerts/create-feed) creates a feed for a set of filters. [`GET /alerts-api/feeds`](https://platform.casafari.com/docs/rest/alerts/list-feeds) and [`GET /alerts-api/feeds/{feed_id}`](https://platform.casafari.com/docs/rest/alerts/get-feed) read feeds, and [`DELETE /alerts-api/feeds/{feed_id}`](https://platform.casafari.com/docs/rest/alerts/delete-feed) removes one. 2. [`PUT /alerts-api/webhooks`](https://platform.casafari.com/docs/rest/alerts/set-webhook-url) sets the URL that alerts are delivered to. 3. [`POST /alerts-api/webhooks/rotate-secret`](https://platform.casafari.com/docs/rest/alerts/rotate-signing-secret) rotates the secret used to sign deliveries. The v1 operations under `/api/v1/listing-alerts/` create, read, update and delete feeds and search alerts without a webhook. Alerts cover new properties, price rises and cuts, reservations, removals and sales. There is no MCP tool. See: [Alerts](https://platform.casafari.com/docs/alerts) and [Alerts REST API](https://platform.casafari.com/docs/rest/alerts). Permalink: https://platform.casafari.com/docs/faq/alerts-webhook ### How do I build my own application or agent on Casafari MCP? Connect to `https://mcp.casafari.com/` over Streamable HTTP, complete OAuth 2.1 (discovery, registration, PKCE authorization, and token), then call `list_servers` and read each tool's schema in `/tools.json`. 1. Discover: the `401` response points to the protected resource metadata, which in turn points to the authorization server metadata. 2. Register once with dynamic client registration and keep the `client_id`. An unattended agent uses client credentials issued by Casafari instead. 3. Authorize with PKCE and `resource`, exchange the code, then call with `Authorization: Bearer `. Refresh when `expires_in` runs out. 4. Call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) before using a product. Read each tool's description and input schema, because they are the contract. Machine-readable helpers: [/tools.json](https://platform.casafari.com/tools.json), the [MCP server card](https://platform.casafari.com/.well-known/mcp/server-card.json), and the [agent skill](https://platform.casafari.com/.well-known/agent-skills/index.json). See [Authentication](https://platform.casafari.com/docs/authentication) and [For AI agents](https://platform.casafari.com/docs/agents). Permalink: https://platform.casafari.com/docs/faq/build-on-mcp ### How do I build on the Casafari REST API? The Casafari REST API lives at `https://api.casafari.com`. It has 39 operations and no gateway, uses a JWT from `POST /login`, and publishes a public OpenAPI description at https://docs.api.casafari.com/openapi.json. 1. Read the OpenAPI document for the base catalogue. After you sign in, https://docs.api.casafari.com/ shows your account's own operations. 2. Call [`POST /login`](https://platform.casafari.com/docs/rest/authentication/login) with your email and password, send the access token as a bearer token, and renew it with [`GET /refresh-token`](https://platform.casafari.com/docs/rest/authentication/refresh-token). 3. Build reference lookups from [References](https://platform.casafari.com/docs/references), then call the product operations you need: Properties, Comparables & Valuation, Area Insights and Alerts. [MCP and REST compared](https://platform.casafari.com/docs/parity) shows what exists only over REST, such as Properties and Alerts, and only over MCP, such as AgentGraph AI. The API also appears in the hub's [API catalog](https://platform.casafari.com/.well-known/api-catalog). See: [REST API](https://platform.casafari.com/docs/rest). Permalink: https://platform.casafari.com/docs/faq/build-on-rest ## The data ### What is the Casafari property graph, and where does the data come from? The property graph is Casafari's data model: it collects property advertisements from agency websites and portals as they appear and change, then structures, cleans, deduplicates and merges them into one record per property. 1. Collect: gather advertisements from agency websites and portals as they appear and as they change. 2. Structure: map each advertisement to a single schema covering type, operation, price, area, rooms, features, condition, energy rating and location. 3. Clean: normalise values, resolve places to the location tree and to coordinates, and flag outliers. 4. Deduplicate: recognise a property advertised by several agencies and portals as one property. 5. Merge: build one record per property that links its advertisements, agencies, agents, location and history. Residential and commercial properties, for sale and for rent, share one schema and one location tree. [`GET /api/v1/references/sources`](https://platform.casafari.com/docs/rest/references/get-sources-v1) returns the sources the graph is built from. See: [The property graph](https://platform.casafari.com/docs/property-graph). Permalink: https://platform.casafari.com/docs/faq/what-is-the-property-graph ### Why is Casafari the most complete property index in Europe? By Casafari's own count, its property graph covers at least 40% more deduplicated properties and tracks 7 times more property advertisements than any standalone platform or portal. - **Deduplicated properties.** Each property is counted once, no matter how many agency websites and portals advertise it. The 40% figure therefore compares properties with properties, not advertisements with advertisements. - **Advertisements tracked.** Casafari collects advertisements from agency websites and portals as they appear and as they change, and merges all of a property's advertisements into its single record. - **One record per property.** Each record keeps the property's full, dated history: every price change, status change, appearance and removal. Source: Casafari, 2026-10-08. See: [The property graph](https://platform.casafari.com/docs/property-graph). Permalink: https://platform.casafari.com/docs/faq/why-most-complete-property-index ### Why does Casafari count properties and not advertisements? Each record in the graph already merges every source that advertises the property, so counting advertisements would count the same home several times. A property is often advertised by several agencies and on several portals. Casafari recognises these advertisements as one property and keeps a single record linked to all of them, so counting records means counting properties. Area Insights distributions and time series report this count as `properties_count`, and a comparables result returns each property once, with its number of active advertisements as a field. When you summarise supply or activity in an area, report properties. See: [The property graph](https://platform.casafari.com/docs/property-graph) and [For AI agents](https://platform.casafari.com/docs/agents). Permalink: https://platform.casafari.com/docs/faq/count-properties-not-advertisements ### Does Casafari keep price and status history? Yes, every property record carries its full dated history of price changes, status changes, appearances and removals in `sale_price_history` and `rent_price_history`. Statuses include active, reserved, hold, sold and rented. Over REST, [`GET /api/v1/properties/search/{property_id}`](https://platform.casafari.com/docs/rest/properties/get-property-by-id-v1) returns a property along with its history. Over MCP, each comparable from [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables) includes its last price change, total price change, time on market and sold or rented dates, and the Area Insights time series count price rises and cuts per period. To follow changes as they happen, an [Alerts](https://platform.casafari.com/docs/alerts) feed reports new properties, price rises and cuts, reservations, removals and sales over REST. See: [The property graph](https://platform.casafari.com/docs/property-graph). Permalink: https://platform.casafari.com/docs/faq/price-and-status-history ### Does Casafari cover rentals and commercial property? Yes: the property graph covers residential and commercial property, for sale and for rent, in a single schema and location tree. Each record has a sale side and a rent side, each with its own status, price, price per m² and history (`sale_price_history`, `rent_price_history`). Tools take an operation: `sale` or `rent` in `comps_get-comparables`, `business_type` in the Area Insights tools, and `operation` in AgentGraph AI. Property types cover apartments, houses, rooms, buildings, commercial (retail, office, warehouse, hotel, restaurant), plots, garages and parking. `GET /api/v1/references/types` returns the full list and shows which countries each type is available in. In the Area Insights tools, `type_group` accepts `apartment` or `house`. See: [The property graph](https://platform.casafari.com/docs/property-graph) and [`GET /api/v1/references/types`](https://platform.casafari.com/docs/rest/references/get-types-v1). Permalink: https://platform.casafari.com/docs/faq/rentals-and-commercial ### How often is Casafari's data updated? Casafari monitors more than 10,000 real estate sources, refreshing the top portals every hour and all other sources daily, according to the API and MCP team's published statement (https://docs.api.casafari.com/llms.txt). - **Area Insights:** the index is updated daily. - **AgentGraph AI:** watchlist entries are re-measured daily. - **Each property record** stores the date of every price change, status change, appearance and removal, so you can see when it last changed. See [Area Insights](https://platform.casafari.com/docs/area-insights), [AgentGraph AI](https://platform.casafari.com/docs/agentgraph) and [The property graph](https://platform.casafari.com/docs/property-graph). Permalink: https://platform.casafari.com/docs/faq/data-refresh-frequency ## Pricing and terms ### How much does Casafari MCP cost? Casafari doesn't publish prices for Casafari MCP or the REST API. Its MCP page describes "flexible pricing based on your AI application needs" and asks you to contact Casafari. Access is tied to a Casafari account and the matching subscription. A token carries exactly that account's rights, `tools/list` shows only the tools it covers, and each product has a quota, though the figure isn't published. See: [How do I get access?](https://platform.casafari.com/docs/faq#how-to-get-access) and the [Casafari MCP page](https://www.casafari.com/products/property-data-mcp-ai-agents/). For a quote, contact Casafari through the MCP page: https://www.casafari.com/products/property-data-mcp-ai-agents/ Permalink: https://platform.casafari.com/docs/faq/pricing ### Is there an SLA, and what are the contract terms? Casafari publishes no standard SLA or uptime figure: its Terms and Conditions allow service levels to be set for each customer in an Order Form, and its Terms of Use do not promise uninterrupted service. - **Licence.** Limited, non-exclusive and non-transferable, with no right to sublicense, for the client's own users with individual active accounts. - **No redistribution.** The services may not be sold, rented, leased, licensed, sublicensed or distributed to another party. - **No automated bulk access.** Excessive or automated access through bots, scripts or scraping tools is not allowed, and neither is sharing credentials. - **Storage.** Casafari's API page says API results may not be stored indefinitely for reuse; long-term access requires a custom agreement. - **Support.** support@casafari.com. The errors table covers the operational side: retry `5xx` responses with exponential backoff, and note that a subscription change takes effect on the next request. See [Terms and Conditions](https://www.casafari.com/terms-and-conditions/), [Terms of Use](https://www.casafari.com/terms-of-use/) and [Authentication](https://platform.casafari.com/docs/authentication) (errors table). To arrange an Order Form with service levels, contact Casafari: https://www.casafari.com/products/property-data-mcp-ai-agents/ Permalink: https://platform.casafari.com/docs/faq/sla-and-contract-terms ## For agents and machine readers ### Can I read these docs as Markdown, and is there an llms.txt? Yes: add `.md` to any page's URL or send `Accept: text/markdown`, and `/llms.txt` indexes every page and tool. None of it needs a key. - [/llms.txt](https://platform.casafari.com/llms.txt) is the index, and [/llms-full.txt](https://platform.casafari.com/llms-full.txt) holds the whole reference in one file. - [/tools.json](https://platform.casafari.com/tools.json) gives every tool's name, title, input schema and output schema. - You'll also find the [API catalog](https://platform.casafari.com/.well-known/api-catalog), [MCP server card](https://platform.casafari.com/.well-known/mcp/server-card.json), [agent skill](https://platform.casafari.com/.well-known/agent-skills/index.json), [agentic resource manifest](https://platform.casafari.com/.well-known/ai-catalog.json) and the sitemap at `/sitemap.xml`. - Markdown responses are served as `text/markdown`, with an `x-markdown-tokens` header that estimates their size. - In a browser that supports `navigator.modelContext`, pages register these WebMCP tools: `search_casafari_mcp_docs`, `get_casafari_tool_reference`, `get_casafari_rest_operation`, `get_casafari_connection_config` and `open_casafari_docs_page`. See: [For AI agents](https://platform.casafari.com/docs/agents). Permalink: https://platform.casafari.com/docs/faq/machine-readable-docs --- # All tools 22 MCP tools in 3 products, plus the gateway's `list_servers`. Your account sees the ones its subscription covers. The REST API's 39 operations are listed in the [REST API reference](/docs/rest). ## Gateway | Tool | Title | |---|---| | [`list_servers`](/docs/gateway/list_servers) | List Servers | ## Comparables & Valuation | Tool | Title | |---|---| | [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) | Get Comparables | ## Area Insights | Tool | Title | |---|---| | [`ma_get_current_datetime`](/docs/area-insights/get_current_datetime) | Get Current Datetime | | [`ma_get_time_series_data`](/docs/area-insights/get_time_series_data) | Get Time Series Data | | [`ma_get_time_series_operations`](/docs/area-insights/get_time_series_operations) | Get Time Series Operations | | [`ma_get_price_distribution`](/docs/area-insights/get_price_distribution) | Get Price Distribution | | [`ma_get_bedrooms_distribution`](/docs/area-insights/get_bedrooms_distribution) | Get Bedrooms Distribution | | [`ma_get_time_on_market_distribution`](/docs/area-insights/get_time_on_market_distribution) | Get Time on Market Distribution | | [`ma_get_heatmap`](/docs/area-insights/get_heatmap) | Get Heatmap | | [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead) | Get Location Typeahead | ## AgentGraph AI | Tool | Title | |---|---| | [`agentgraph_find_location`](/docs/agentgraph/find_location) | Find a German location | | [`agentgraph_list_profiles`](/docs/agentgraph/list_profiles) | Partner profiles | | [`agentgraph_screen_agencies`](/docs/agentgraph/screen_agencies) | Screen agencies in an area | | [`agentgraph_screen_agents`](/docs/agentgraph/screen_agents) | Screen agents in an area | | [`agentgraph_agency_profile`](/docs/agentgraph/agency_profile) | Agency in full | | [`agentgraph_agent_profile`](/docs/agentgraph/agent_profile) | Agent in full | | [`agentgraph_partner_brief`](/docs/agentgraph/partner_brief) | Partner brief | | [`agentgraph_territory_map`](/docs/agentgraph/territory_map) | Territory map | | [`agentgraph_save_to_watchlist`](/docs/agentgraph/save_to_watchlist) | Save to watchlist | | [`agentgraph_remove_from_watchlist`](/docs/agentgraph/remove_from_watchlist) | Remove from watchlist | | [`agentgraph_watchlist`](/docs/agentgraph/watchlist) | Watchlist | | [`agentgraph_watchlist_changes`](/docs/agentgraph/watchlist_changes) | What changed | | [`agentgraph_area_benchmark`](/docs/agentgraph/area_benchmark) | Area benchmark | ## Questions about this - [What is Casafari MCP?](/docs/faq/what-is-casafari-mcp) - [Does every tool cover all 16 countries?](/docs/faq/per-tool-coverage) - [How are Casafari MCP tools named?](/docs/faq/tool-naming) --- # REST API The same data as the MCP tools, over HTTP. This reference is generated from the API's public OpenAPI description (OpenAPI 3.1.0, API version 0.1.0): 35 paths and 39 operations, snapshot taken 2026-10-08. Operations are grouped by product, the same way the MCP tools are; [MCP and REST compared](/docs/parity) shows where the two overlap and where they do not. ## Base URL and authentication | | | |---|---| | Base URL | `https://api.casafari.com` | | Format | JSON requests and responses | | Authentication | A bearer token (JWT) that you get with your account's email and password. REST does not use OAuth; that is for [MCP](/docs/authentication). | | OpenAPI description | [https://docs.api.casafari.com/openapi.json](https://docs.api.casafari.com/openapi.json) (public, no sign-in needed) | | Interactive docs | [https://docs.api.casafari.com/](https://docs.api.casafari.com/) | The API description says about the token: > The API endpoints require an authentication token to be provided with each request. The token must be sent via the `Authorization` HTTP header, containing the keyword `Bearer` followed by your authentication token. The public description lists the base catalogue. What your account can call depends on its subscription, and the interactive docs show your account's own list after you sign in. For agents, [auth.md](https://www.casafari.com/auth.md) covers both ways of signing in. ### Get a token 1. Call [`POST /login`](/docs/rest/authentication/login) with your account's email and password. The response has an `access_token` and a `refresh_token`. 2. Send `Authorization: Bearer ` with every other request. 3. When the access token expires, call [`GET /refresh-token`](/docs/rest/authentication/refresh-token) with the refresh token as the bearer. A `401` from it means the refresh token has expired: log in again. ```bash curl -X POST "https://api.casafari.com/login" \ -H "Content-Type: application/json" \ -d '{ "email": "", "password": "" }' ``` Then, with the token in an environment variable (`$CASAFARI_TOKEN` in every example on this site is a placeholder, never a credential): ```bash curl "https://api.casafari.com/api/v1/references/types" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Operations by product ### [Properties](/docs/rest/properties) - [`POST /api/v1/properties/match-by-listings`](/docs/rest/properties/get-property-by-listing-ids-v1): Get property by listing IDs (v1). Returns a mapping properties IDs to listing IDs. - [`POST /api/v1/properties/search`](/docs/rest/properties/search-properties-v1): Search properties (v1) - [`GET /api/v1/properties/search/{property_id}`](/docs/rest/properties/get-property-by-id-v1): Get property by ID (v1). Returns a property object. - [`POST /api/v1/properties/smart-links`](/docs/rest/properties/create-a-smart-link-beta-v1): Create a smart link (BETA) (v1). Generates a smart link that provides detailed property information with customizable components, branding, and user/company information overrides. - [`POST /api/v2/properties/search`](/docs/rest/properties/search-properties-v2): Search properties (v2) ### [Comparables & Valuation](/docs/rest/comparables-valuation) - [`POST /api/v1/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v1): Search comparables (v1). Returns comparable properties by the given parameters. - [`POST /api/v2/comparables/ai-builder`](/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2): Initialize an AI Builder session (v2). Initializes an AI Builder session from a saved CMA (valuation) and returns the generated report ID along with the URL of the AI Builder session. - [`POST /api/v2/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v2): Search comparables (v2). Returns comparable properties by the given parameters. - [`POST /api/v1/valuation/comparables-prices`](/docs/rest/comparables-valuation/search-estimated-prices-v1): Search estimated prices (v1). Returns estimated prices by the given parameters. ### [Area Insights](/docs/rest/area-insights) - [`POST /market-analytics-api/time-series`](/docs/rest/area-insights/time-series): Time Series. Returns time series data for the real estate market. - [`POST /market-analytics-api/distributions/bedrooms`](/docs/rest/area-insights/bedrooms-distribution): Bedrooms Distribution. Returns property distribution based on the number of bedrooms. - [`POST /market-analytics-api/distributions/prices`](/docs/rest/area-insights/price-distribution): Price Distribution. Returns the number of properties distributed across price ranges. - [`POST /market-analytics-api/distributions/properties`](/docs/rest/area-insights/properties-distribution): Properties Distribution. Returns the properties lightweight data sample and distribution quartiles. - [`POST /market-analytics-api/distributions/time-on-market`](/docs/rest/area-insights/time-on-market-distribution): Time On Market Distribution. Returns time on market (days and months) distribution by price ranges. - [`POST /market-analytics-api/analysis`](/docs/rest/area-insights/analysis): Analysis. Market analysis based on the requested property parameters. ### [Alerts](/docs/rest/alerts) - [`GET /api/v1/listing-alerts/feeds`](/docs/rest/alerts/get-feeds-list-v1): Get feeds list (v1). Returns all alerts feeds for currently authenticated user. - [`POST /api/v1/listing-alerts/feeds`](/docs/rest/alerts/create-feed-v1): Create feed (v1). Create alerts feed for currently authenticated user. - [`GET /api/v1/listing-alerts/feeds/{id}`](/docs/rest/alerts/get-alerts-by-feed-v1): Get alerts by feed (v1). Returns paginated list of alerts (by feed ID) for currently authenticated user. - [`DELETE /api/v1/listing-alerts/feeds/{id}`](/docs/rest/alerts/delete-feed-v1): Delete feed (v1). Delete alerts feed (by feed ID) for currently authenticated user. - [`PUT /api/v1/listing-alerts/feeds/{id}/update`](/docs/rest/alerts/update-feed-v1): Update feed (v1). Update alerts feed by id. - [`POST /api/v1/listing-alerts/search`](/docs/rest/alerts/search-alerts-v1): Search alerts (v1). Returns paginated list of alerts (by requested parameters) for currently authenticated user. - [`GET /alerts-api/feeds`](/docs/rest/alerts/list-feeds): List feeds. Returns a paginated list of feeds, sorted newest first. - [`POST /alerts-api/feeds`](/docs/rest/alerts/create-feed): Create feed. Create a new alert feed that delivers matching real estate events to your webhook URL. - [`GET /alerts-api/feeds/{feed_id}`](/docs/rest/alerts/get-feed): Get feed. Returns the feed configuration in the same format as it was originally created. - [`DELETE /alerts-api/feeds/{feed_id}`](/docs/rest/alerts/delete-feed): Delete feed. Permanently removes the feed. - [`PUT /alerts-api/webhooks`](/docs/rest/alerts/set-webhook-url): Set webhook URL. Sets (or replaces) the delivery URL for all your alert feeds. - [`POST /alerts-api/webhooks/rotate-secret`](/docs/rest/alerts/rotate-signing-secret): Rotate signing secret. Issues a new current signing secret. ### [References](/docs/rest/references) - [`GET /api/v1/references/agencies`](/docs/rest/references/get-agencies-v1): Get agencies (v1). Returns a list of all possible agencies with user restrictions. - [`GET /api/v1/references/agents`](/docs/rest/references/get-agents-v1): Get agents (v1). Returns a list of all possible agents with user restrictions. - [`GET /api/v1/references/conditions`](/docs/rest/references/get-conditions-v1): Get conditions (v1). Returns a list of all possible estate conditions. - [`GET /api/v1/references/features`](/docs/rest/references/get-features-v1): Get features (v1). Returns a list of all possible property features. - [`POST /api/v1/references/locations`](/docs/rest/references/get-locations-v1): Get locations (v1). Returns a list of all possible locations with user restrictions. - [`GET /api/v1/references/locations/by-coordinates`](/docs/rest/references/get-location-by-passed-coordinates-v1): Get location by passed coordinates (v1). Returns a location for the given coordinates with user restrictions. - [`POST /api/v1/references/locations/typeahead`](/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1): Get locations typeahead suggestions scoped by country code (v1). Returns location typeahead suggestions within the given country (ES or PT). - [`GET /api/v1/references/sources`](/docs/rest/references/get-sources-v1): Get sources (v1). Returns a list of all domains for the requested location. - [`GET /api/v1/references/types`](/docs/rest/references/get-types-v1): Get types (v1). Returns a list of all possible estate types. - [`POST /api/v1/references/zipcode-boundary`](/docs/rest/references/get-zipcode-boundary-by-zipcode-and-country-code-v1): Get zipcode boundary by zipcode and country code (v1). Get zipcode boundary by zipcode and country code. ### [Authentication](/docs/rest/authentication) - [`POST /login`](/docs/rest/authentication/login): Login - [`GET /refresh-token`](/docs/rest/authentication/refresh-token): Refresh Token ## Status codes Every operation documents its own responses. Across the description: | Status | Meaning | Operations that can return it | |---|---|---| | `200` | OK | 38 | | `201` | Created | 1 | | `204` | No Content | 5 | | `400` | Bad Request | 15 | | `401` | Unauthorized | 25 | | `403` | Forbidden | 25 | | `404` | Not Found | 8 | | `409` | Conflict | 1 | | `422` | Validation Error | 13 | ## Read this reference as Markdown Add `.md` to any page's URL, or send `Accept: text/markdown`. [/llms.txt](/llms.txt) lists every operation next to every MCP tool. ## Questions about this - [What is the difference between Casafari MCP and the Casafari REST API?](/docs/faq/mcp-vs-rest-api) - [How does authentication work on Casafari MCP? Does it use OAuth scopes?](/docs/faq/how-authentication-works) - [How do I authenticate with the Casafari REST API?](/docs/faq/rest-authentication) - [How do I build on the Casafari REST API?](/docs/faq/build-on-rest) --- # Authentication Sign in with your account's email and password to get the token the other operations need, and refresh it. 2 operations, from the public OpenAPI description. Base URL `https://api.casafari.com`; every operation but sign-in needs a bearer token (see [the REST API overview](/docs/rest#get-a-token)). ## Operations - [`POST /login`](/docs/rest/authentication/login): Login - [`GET /refresh-token`](/docs/rest/authentication/refresh-token): Refresh Token ## Questions about this - [How do I authenticate with the Casafari REST API?](/docs/faq/rest-authentication) --- # Login `POST https://api.casafari.com/login` REST API · Authentication. No token needed: this is how you get one. See [the REST API overview](/docs/rest#get-a-token). ## Request body Content type `application/json`. Required. Type: `object`. - `email` (string, required) - `password` (string, required) at least 1 character. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/login" \ -H "Content-Type: application/json" \ -d '{ "email": "", "password": "" }' ``` ## Responses ### 200 Successful Response Type: `object`. - `access_token` (string, required) - `refresh_token` (string, required) ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [What is the difference between Casafari MCP and the Casafari REST API?](/docs/faq/mcp-vs-rest-api) - [Do I need an API key for Casafari MCP?](/docs/faq/api-key) - [How do I authenticate with the Casafari REST API?](/docs/faq/rest-authentication) - [How do I build on the Casafari REST API?](/docs/faq/build-on-rest) --- # Refresh Token `GET https://api.casafari.com/refresh-token` REST API · Authentication. Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/refresh-token" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 Successful Response Type: `object`. - `access_token` (string, required) ## Questions about this - [What is the difference between Casafari MCP and the Casafari REST API?](/docs/faq/mcp-vs-rest-api) - [What happens when my access token expires?](/docs/faq/token-expiry-refresh) - [How do I authenticate with the Casafari REST API?](/docs/faq/rest-authentication) - [How do I build on the Casafari REST API?](/docs/faq/build-on-rest) --- # Data Export Bulk delivery of Casafari's data as files, for loading into your own warehouse rather than calling the API. ## Overview Casafari Data Export delivers real estate market data as Avro files to a dedicated Google Cloud Storage (GCS) bucket provisioned for your account. Five entity types are exported: **Property**, **Listing**, **Alert**, **Location** and **ListingPhoto**. The set of entities enabled for your account is defined by your contract. ## Data delivery - Data is delivered to one GCS bucket per country. Bucket names are provided by Casafari during onboarding. - Inside a bucket, files are grouped by entity type: ``` properties/ listings/ listing_photos/ alerts/ locations/ ``` - File names follow the pattern `{revision}_{salt}_{timestamp}.avro`, e.g. `latest_1f3a9c..._2026_07_29_10_15_30_123456.avro`: - `revision` — `latest` for full snapshots, `latest_delta` for incremental updates; - `salt` — a unique hex identifier of the export batch; - `timestamp` — file creation time, `YYYY_MM_DD_HH_MM_SS_ffffff`. ## Data format Files are standard [Avro Object Container Files](https://avro.apache.org/docs/current/specification/): the writer schema is embedded in every file, and each field carries a `doc` attribute with its description, so any Avro library or tool can read the files and inspect the schema. Optional fields are declared as `["null", ...]` unions with a `null` default. ## Sync semantics - **Full sync** produces a complete snapshot of every enabled entity. Previous files in the entity folders are removed and replaced with a new set of `latest_*` files. - **Delta sync** periodically uploads `latest_delta_*` files containing records created or updated since the previous run. - To maintain an up-to-date copy: load the latest full snapshot, then apply delta files in file-timestamp order, upserting records by entity key. ## Sync status A file named `sync_status.json` at the root of the bucket reports the progress of full and delta syncs, so you can start processing as soon as a sync is done instead of waiting a fixed amount of time. It is written when a sync starts and updated when the sync finishes. ```json { "full": { "status": "finished", "started_at": "2026-09-01T02:00:00+00:00", "finished_at": "2026-09-01T06:30:00+00:00", "last_finished_at": "2026-09-01T06:30:00+00:00" }, "delta": { "status": "processing", "started_at": "2026-09-11T02:00:00+00:00", "finished_at": null, "last_finished_at": "2026-09-10T03:10:00+00:00" } } ``` The file has two sections, `full` and `delta`, with the same fields. All timestamps are ISO 8601 in UTC. | Field | Description | |---|---| | status | `processing` while files are still being written to the bucket, `finished` once the run is done. | | started_at | Start time of the current (or last) run. | | finished_at | End time of that run; `null` while it is still in progress. | | last_finished_at | Time data was last delivered successfully. **This is the field to rely on.** | ### Recommended usage 1. Read `sync_status.json` and pick the section you track (`full` or `delta`). 2. Start processing files only when `status` is `finished`. 3. Make sure the run actually delivered data: `last_finished_at` must be later than `started_at`. If it is earlier, the run did not complete in time — see *Timeouts* below. 4. To detect new data since your last import, compare `last_finished_at` with the value you saw last time. If it moved forward, there is new data. 5. Poll the file every 5–15 minutes; checking more often is not necessary. 6. If the file is missing or cannot be read, retry later. **Never treat that as `finished`.** ### Timeouts A sync can take several hours, so a long `processing` status is normal. A sync should always complete well within 12 hours. As a safeguard, if a run is still open after 12 hours, it is closed in this file so the status never stays stuck on `processing`: `status` becomes `finished` while `last_finished_at` keeps its previous value. This only affects the file — the sync itself keeps running. This is not expected to happen; if you ever notice it, please contact your Casafari account manager. ## Entities and keys | Entity | Key | Notes | |---|---|---| | Property | property_id + property_unit_id | The pair uniquely identifies a property. | | Listing | listing_id | References its property via property_id + property_unit_id. | | Alert | alert_id | Change events; reference listing_id and property_id. | | Location | location_id | Location tree; parent_id points to the parent location. | | ListingPhoto | listing_id | A list of image URLs per listing. | The full field reference for every entity is provided in the schema definitions below. ## Support For questions about the data or delivery, contact your Casafari account manager. ## Entities | Entity | Fields | What it holds | |---|---|---| | [Property](/docs/data-export/property) | 70 | Every field of the Property entity in the export files, with its type and meaning. | | [Listing](/docs/data-export/listing) | 59 | Every field of the Listing entity in the export files, with its type and meaning. | | [Alert](/docs/data-export/alert) | 9 | Every field of the Alert entity in the export files, with its type and meaning. | | [Location](/docs/data-export/location) | 5 | Every field of the Location entity in the export files, with its type and meaning. | | [ListingPhoto](/docs/data-export/listing-photo) | 4 | Every field of the ListingPhoto entity in the export files, with its type and meaning. | Source: the API team's own description, [https://docs.api.casafari.com/data-export](https://docs.api.casafari.com/data-export). --- # Property Every field of the Property entity in the export files, with its type and meaning. Part of [Data Export](/docs/data-export). Files under `propertys/`. ## Fields - `type` (string, required): Property type. - `type_group` (string, required): Property type group. - `title` (string, required): Property title. - `business_type` (string[], required): Operation type. Values: `sale`, `rent`. - `changed_at` (string, required): The date and time when the property was last updated. - `created_at` (string, required): The date and time when the property was added. - `sold_at` (string, required): Date when the property was sold. - `rented_at` (string, required): Date when the property was rented. - `sale_hold_at` (string, optional, nullable): Date when the property was put on hold on the sales market. - `rent_hold_at` (string, optional, nullable): Date when the property was put on hold on the rental market. - `location_id` (integer, required): ID of the location. - `locations_structure` (integer[], required): Location ids of parent locations (including listing location) up to the country. - `zip_codes` (string[], required): The location zip codes. - `zip_code` (string, optional, nullable): The location zip code. - `address` (string, required): Property address. - `coordinates` (object, required): Property coordinates. - `longitude` (number, required): Longitude. - `latitude` (number, required): Latitude. - `total_area` (integer, required): Total area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `bathrooms` (integer, required): Number of bathrooms. - `rooms` (integer, required): Number of rooms. - `construction_year` (integer, required): Construction year. - `sale_price` (integer, required): Current sale price, in the currency specified in the `sale_currency` field. - `sale_status` (string, required): Current sale status of the property. Values: `active`, `reserved`, `sold`, `hold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `rent_price` (integer, required): Current rent price, in the currency specified in the `rent_currency` field. - `rent_status` (string, required): Current rent status of the property. Values: `active`, `reserved`, `rented`, `hold`, `none`. - `rent_currency` (string, required): Rent price currency code. - `features` (object, required): Property features. - `views` (string[], optional, nullable): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `directions` (string[], optional, nullable): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], optional, nullable): Property characteristics. Values: `balcony`, `elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `no_elevator`, `rented_out`, `life_annuity`, `business_transfer`, `smoke_outlet`. - `floor` (string, optional, nullable): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional, nullable): Property view orientation. Values: `interior`, `exterior`. - `condition` (string, required): Property condition. - `energy_certificate` (string, required): Energy certificate. Values: `UNKNOWN`, `A`, `A+`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `is_private` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `property_id` (integer, required): ID of the property. - `property_unit_id` (integer, required): Property sub-identifier. Along with the property_id, it ensures the uniqueness of the property. - `primary_listing_id` (integer, required): Primary listing (ad) ID of the property which is defined after the matching into property. - `floor_number` (integer, required): Exact floor number. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `month`, `year`, `none`, `fortnight`. - `sale_time_on_market` (object, required): Information about the property last activity on the sales market. - `date_start` (string, required): Start date of activity on the market. - `date_end` (string, required): End date of activity on the market. - `days_on_market` (integer, required): Number of days property was/is on the market. - `has_untracked_period` (boolean, required): Whether the property was already on the market when it started being tracked. - `rent_time_on_market` (object, required): Information about the property last activity on the rental market. - `date_start` (string, required): Start date of activity on the market. - `date_end` (string, required): End date of activity on the market. - `days_on_market` (integer, required): Number of days property was/is on the market. - `has_untracked_period` (boolean, required): Whether the property was already on the market when it started being tracked. - `listings_ids` (integer[], required): List of listing (ad) ID of the property. - `administrative_level` (string, required): Location administrative level. - `rent_price_base` (integer, required): Current rent price, in Euros. - `rent_price_per_sqm` (number, required): Current rent price per square meter, in the currency specified in the `rent_currency` field. - `sale_price_base` (integer, required): Current sale price, in Euros. - `sale_price_per_sqm` (number, required): Current sale price per square meter, in the currency specified in the `sale_currency` field. - `sale_price_last_change` (object, required): Information about the last change of sale price. - `alert_date` (string, required): Date of the change. - `old_value_int` (integer, required): Value before change. - `new_value_int` (integer, required): Value after change. - `rent_price_last_change` (object, required): Information about the last change of rent price. - `alert_date` (string, required): Date of the change. - `old_value_int` (integer, required): Value before change. - `new_value_int` (integer, required): Value after change. - `appeared_at` (string, required): Creation date and time of the first listing. --- # Listing Every field of the Listing entity in the export files, with its type and meaning. Part of [Data Export](/docs/data-export). Files under `listings/`. ## Fields - `type` (string, required): Property type. - `type_group` (string, required): Property type group. - `title` (string, required): Property title. - `business_type` (string[], required): Operation type. Values: `sale`, `rent`. - `changed_at` (string, required): The date and time when the property was last updated. - `created_at` (string, required): The date and time when the property was added. - `sold_at` (string, required): Date when the property was sold. - `rented_at` (string, required): Date when the property was rented. - `sale_hold_at` (string, optional, nullable): Date when the property was put on hold on the sales market. - `rent_hold_at` (string, optional, nullable): Date when the property was put on hold on the rental market. - `location_id` (integer, required): ID of the location. - `locations_structure` (integer[], required): Location ids of parent locations (including listing location) up to the country. - `zip_codes` (string[], required): The location zip codes. - `zip_code` (string, optional, nullable): The location zip code. - `address` (string, required): Property address. - `coordinates` (object, required): Property coordinates. - `longitude` (number, required): Longitude. - `latitude` (number, required): Latitude. - `total_area` (integer, required): Total area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `bathrooms` (integer, required): Number of bathrooms. - `rooms` (integer, required): Number of rooms. - `construction_year` (integer, required): Construction year. - `sale_price` (integer, required): Current sale price, in the currency specified in the `sale_currency` field. - `sale_status` (string, required): Current sale status of the property. Values: `active`, `reserved`, `sold`, `hold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `rent_price` (integer, required): Current rent price, in the currency specified in the `rent_currency` field. - `rent_status` (string, required): Current rent status of the property. Values: `active`, `reserved`, `rented`, `hold`, `none`. - `rent_currency` (string, required): Rent price currency code. - `features` (object, required): Property features. - `views` (string[], optional, nullable): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `directions` (string[], optional, nullable): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], optional, nullable): Property characteristics. Values: `balcony`, `elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `no_elevator`, `rented_out`, `life_annuity`, `business_transfer`, `smoke_outlet`. - `floor` (string, optional, nullable): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional, nullable): Property view orientation. Values: `interior`, `exterior`. - `condition` (string, required): Property condition. - `energy_certificate` (string, required): Energy certificate. Values: `UNKNOWN`, `A`, `A+`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `is_private` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `listing_id` (integer, required): ID of the listing (ad). - `property_id` (integer, required): ID of the property. - `property_unit_id` (integer, required): Property sub-identifier. Along with the property_id, it ensures the uniqueness of the property. - `uuid` (string, required): Unique ID of the listing on the source site. - `ref` (string, required): The listing reference number. - `external_ref` (string, required): The additional listing reference number. - `listing_url` (string, required): URL of the listing. Available only for currently active listings. - `listing_refs` (string[], required): List of reference numbers from listings. - `description` (string, required): Listing description. - `is_bank` (boolean, required): Whether the listing is a bank listing. - `is_auction` (boolean, required): Whether the listing is an auction listing. - `is_new_development` (boolean, required): Whether the listing is a new development listing. - `agency` (string, required): The company or agency that manages the listing. - `source_id` (integer, required): ID of the source linked to the company. - `source_name` (string, required): The name of the source where the listing is displayed. - `contacts_info` (object, required): Information about listing contacts. - `name` (string, required): The owner name. Only for FSBO listings. - `email` (string, required): The email contact. - `phone` (string, required): The phone contact. --- # Alert Every field of the Alert entity in the export files, with its type and meaning. Part of [Data Export](/docs/data-export). Files under `alerts/`. ## Fields - `alert_id` (integer, required): ID of the alert. - `property_id` (integer, required): ID of the property. - `property_unit_id` (integer, required): Property sub-identifier. Along with the property_id, it ensures the uniqueness of the property. - `listing_id` (integer, required): ID of the listing (ad). - `alert_type` (string, required): The type of the alert. Values: `sale_price`, `sale_status`, `rent_price`, `rent_status`, `new`. - `alert_subtype` (string, required): The subtype of the alert. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`, `na`. - `old_value` (string, required): Value before change. - `new_value` (string, required): Value after change. - `alert_date` (string, required): Date when the alert occurred. --- # Location Every field of the Location entity in the export files, with its type and meaning. Part of [Data Export](/docs/data-export). Files under `locations/`. ## Fields - `location_id` (integer, required): ID of the location. - `parent_id` (integer, required): ID of the parent location. - `name` (string, required): Name of the location. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], required): The location zip codes. --- # ListingPhoto Every field of the ListingPhoto entity in the export files, with its type and meaning. Part of [Data Export](/docs/data-export). Files under `listing_photos/`. ## Fields - `listing_id` (integer, required): ID of the listing (ad). - `urls` (object[], required): List of the image URLs. - `original` (string, required): Original image URL. - `thumbnail` (string, required): Thumbnail image URL. --- # MCP and REST compared Casafari's data can be reached two ways: the MCP server at `https://mcp.casafari.com/` and the REST API at `https://api.casafari.com`. They overlap, but neither contains the other. This page lines them up product by product. It is generated from the tool definitions and from the public OpenAPI description, so it changes when either does. **How to read it.** *Equivalent* means the same operation is offered over both interfaces. *Related* means the two do part of the same job in different ways, so neither replaces the other. A dash means the other interface has nothing for it. "REST" here is the public OpenAPI description; your account's own specification at [docs.api.casafari.com](https://docs.api.casafari.com/) may list more. ## By product | Product | MCP tools | REST operations | Linked tools | Linked operations | Available over | |---|---|---|---|---|---| | [Properties](#properties) | 0 | 5 | 0 | 0 | REST only | | [Comparables & Valuation](#comparables-valuation) | 1 | 4 | 1 | 3 | Both | | [Area Insights](#area-insights) | 8 | 6 | 5 | 4 | Both | | [Alerts](#alerts) | 0 | 12 | 0 | 0 | REST only | | [References](#references) | 0 | 10 | 0 | 1 | REST only | | [AgentGraph AI](#agentgraph-ai) | 13 | 0 | 0 | 0 | MCP only | | **Total** | 22 | 37 | 6 | 8 | | The gateway's own tool, `list_servers`, has no REST counterpart: there is no gateway over REST. Sign-in operations (`POST /login`, `GET /refresh-token`) belong to no product and are described in [REST API](/docs/rest#get-a-token); MCP signs in with OAuth instead ([Authentication](/docs/authentication)). ## Gaps ### Only over MCP - **Area Insights**: [`ma_get_current_datetime`](/docs/area-insights/get_current_datetime), [`ma_get_time_series_operations`](/docs/area-insights/get_time_series_operations), [`ma_get_heatmap`](/docs/area-insights/get_heatmap). - **AgentGraph AI**: all 13 tools. ### Only over REST - **Properties**: all 5 operations. - **Comparables & Valuation**: [`POST /api/v2/comparables/ai-builder`](/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2). - **Area Insights**: [`POST /market-analytics-api/distributions/properties`](/docs/rest/area-insights/properties-distribution), [`POST /market-analytics-api/analysis`](/docs/rest/area-insights/analysis). - **Alerts**: all 12 operations. - **References**: [`GET /api/v1/references/agencies`](/docs/rest/references/get-agencies-v1), [`GET /api/v1/references/agents`](/docs/rest/references/get-agents-v1), [`GET /api/v1/references/conditions`](/docs/rest/references/get-conditions-v1), [`GET /api/v1/references/features`](/docs/rest/references/get-features-v1), [`POST /api/v1/references/locations`](/docs/rest/references/get-locations-v1), [`GET /api/v1/references/locations/by-coordinates`](/docs/rest/references/get-location-by-passed-coordinates-v1), [`GET /api/v1/references/sources`](/docs/rest/references/get-sources-v1), [`GET /api/v1/references/types`](/docs/rest/references/get-types-v1), [`POST /api/v1/references/zipcode-boundary`](/docs/rest/references/get-zipcode-boundary-by-zipcode-and-country-code-v1). ## Product by product ### Properties Over MCP: 0 tools. Over REST: 5 operations. Available over REST only. [Properties](/docs/properties). MCP has no tool for Properties. ### Comparables & Valuation Over MCP: 1 tool. Over REST: 4 operations. Available over both. [Comparables & Valuation](/docs/comparables-valuation). | MCP tool | REST operation | How they relate | |---|---|---| | [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) | [`POST /api/v2/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v2) | Equivalent. 26 request fields in common; REST only: `coordinates`, `target_point`, `distance`, `business_type`, `comparables_type`, `property_type`, `floor`, `view`, 3 more. | | [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) | [`POST /api/v1/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v1) | Related. The v1 version of the comparables search. | | [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) | [`POST /api/v1/valuation/comparables-prices`](/docs/rest/comparables-valuation/search-estimated-prices-v1) | Related. The tool's response includes estimated price ranges; REST returns estimated prices from this separate operation. | | — | [`POST /api/v2/comparables/ai-builder`](/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2) | Only over REST | ### Area Insights Over MCP: 8 tools. Over REST: 6 operations. Available over both. [Area Insights](/docs/area-insights). | MCP tool | REST operation | How they relate | |---|---|---| | [`ma_get_current_datetime`](/docs/area-insights/get_current_datetime) | — | Only over MCP | | [`ma_get_time_series_data`](/docs/area-insights/get_time_series_data) | [`POST /market-analytics-api/time-series`](/docs/rest/area-insights/time-series) | Equivalent. 19 request fields in common; REST only: `types`; MCP only: `type_group`, `alias`. | | [`ma_get_time_series_operations`](/docs/area-insights/get_time_series_operations) | — | Only over MCP | | [`ma_get_price_distribution`](/docs/area-insights/get_price_distribution) | [`POST /market-analytics-api/distributions/prices`](/docs/rest/area-insights/price-distribution) | Equivalent. 16 request fields in common; REST only: `types`; MCP only: `type_group`. | | [`ma_get_bedrooms_distribution`](/docs/area-insights/get_bedrooms_distribution) | [`POST /market-analytics-api/distributions/bedrooms`](/docs/rest/area-insights/bedrooms-distribution) | Equivalent. 16 request fields in common; REST only: `types`; MCP only: `type_group`. | | [`ma_get_time_on_market_distribution`](/docs/area-insights/get_time_on_market_distribution) | [`POST /market-analytics-api/distributions/time-on-market`](/docs/rest/area-insights/time-on-market-distribution) | Equivalent. 17 request fields in common; REST only: `types`; MCP only: `type_group`. | | [`ma_get_heatmap`](/docs/area-insights/get_heatmap) | — | Only over MCP | | [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead) | [`POST /api/v1/references/locations/typeahead`](/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1) | Related. In [References](/docs/parity#references). Both turn a place name into location ids. The MCP tool takes an English name; REST takes `country_codes` (ES or PT) and a response `lang`. | | — | [`POST /market-analytics-api/distributions/properties`](/docs/rest/area-insights/properties-distribution) | Only over REST | | — | [`POST /market-analytics-api/analysis`](/docs/rest/area-insights/analysis) | Only over REST | ### Alerts Over MCP: 0 tools. Over REST: 12 operations. Available over REST only. [Alerts](/docs/alerts). MCP has no tool for Alerts. ### References Over MCP: 0 tools. Over REST: 10 operations. Available over REST only. [References](/docs/references). MCP has no tool for References, except where a tool of another product covers one operation (below). | MCP tool | REST operation | How they relate | |---|---|---| | — | [`GET /api/v1/references/agencies`](/docs/rest/references/get-agencies-v1) | Only over REST | | — | [`GET /api/v1/references/agents`](/docs/rest/references/get-agents-v1) | Only over REST | | — | [`GET /api/v1/references/conditions`](/docs/rest/references/get-conditions-v1) | Only over REST | | — | [`GET /api/v1/references/features`](/docs/rest/references/get-features-v1) | Only over REST | | — | [`POST /api/v1/references/locations`](/docs/rest/references/get-locations-v1) | Only over REST | | — | [`GET /api/v1/references/locations/by-coordinates`](/docs/rest/references/get-location-by-passed-coordinates-v1) | Only over REST | | [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead) | [`POST /api/v1/references/locations/typeahead`](/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1) | Related. In [Area Insights](/docs/parity#area-insights). Both turn a place name into location ids. The MCP tool takes an English name; REST takes `country_codes` (ES or PT) and a response `lang`. | | — | [`GET /api/v1/references/sources`](/docs/rest/references/get-sources-v1) | Only over REST | | — | [`GET /api/v1/references/types`](/docs/rest/references/get-types-v1) | Only over REST | | — | [`POST /api/v1/references/zipcode-boundary`](/docs/rest/references/get-zipcode-boundary-by-zipcode-and-country-code-v1) | Only over REST | ### AgentGraph AI Over MCP: 13 tools. Over REST: 0 operations. Available over MCP only. [AgentGraph AI](/docs/agentgraph). The public REST description has no operation for AgentGraph AI, so all 13 tools can be reached over MCP only. ## Questions about this - [What is the difference between Casafari MCP and the Casafari REST API?](/docs/faq/mcp-vs-rest-api) - [Which products does Casafari MCP offer, and how many tools are there?](/docs/faq/which-products) - [Can I search properties over Casafari MCP?](/docs/faq/properties-over-mcp) - [Can I get alerts (new properties, price cuts, sales) over Casafari MCP?](/docs/faq/alerts-over-mcp) - [Which tools exist only over MCP, and which operations only over REST?](/docs/faq/mcp-only-and-rest-only) --- # Properties Search the property graph, where every property is one record with its price and status history. Over REST: search by structured filters, fetch a property and its history by id, resolve a portal or agency ad id to the property it belongs to, create shareable links. 5 REST operations. ## REST API 5 operations in the public OpenAPI description, all under `https://api.casafari.com` with a bearer token ([how to get one](/docs/rest#get-a-token)). The same list with more detail: [Properties REST API](/docs/rest/properties). - [`POST /api/v1/properties/match-by-listings`](/docs/rest/properties/get-property-by-listing-ids-v1): Get property by listing IDs (v1). Returns a mapping properties IDs to listing IDs. - [`POST /api/v1/properties/search`](/docs/rest/properties/search-properties-v1): Search properties (v1) - [`GET /api/v1/properties/search/{property_id}`](/docs/rest/properties/get-property-by-id-v1): Get property by ID (v1). Returns a property object. - [`POST /api/v1/properties/smart-links`](/docs/rest/properties/create-a-smart-link-beta-v1): Create a smart link (BETA) (v1). Generates a smart link that provides detailed property information with customizable components, branding, and user/company information overrides. - [`POST /api/v2/properties/search`](/docs/rest/properties/search-properties-v2): Search properties (v2) ## MCP and REST compared Over MCP: 0 tools. Over REST: 5 operations. Available over REST only: MCP has no tool for it. Details: [MCP and REST compared](/docs/parity#properties). ## Questions about this - [Which products does Casafari MCP offer, and how many tools are there?](/docs/faq/which-products) - [Can I search properties over Casafari MCP?](/docs/faq/properties-over-mcp) - [How do I look up one property and its price history?](/docs/faq/example-property-lookup) --- # Properties REST API Search the property graph, where every property is one record with its price and status history. Over REST: search by structured filters, fetch a property and its history by id, resolve a portal or agency ad id to the property it belongs to, create shareable links. 5 operations, from the public OpenAPI description. Base URL `https://api.casafari.com`; every operation but sign-in needs a bearer token (see [the REST API overview](/docs/rest#get-a-token)). Over MCP, Properties has no tools: see [MCP and REST compared](/docs/parity#properties). ## Operations - [`POST /api/v1/properties/match-by-listings`](/docs/rest/properties/get-property-by-listing-ids-v1): Get property by listing IDs (v1). Returns a mapping properties IDs to listing IDs. - [`POST /api/v1/properties/search`](/docs/rest/properties/search-properties-v1): Search properties (v1) - [`GET /api/v1/properties/search/{property_id}`](/docs/rest/properties/get-property-by-id-v1): Get property by ID (v1). Returns a property object. - [`POST /api/v1/properties/smart-links`](/docs/rest/properties/create-a-smart-link-beta-v1): Create a smart link (BETA) (v1). Generates a smart link that provides detailed property information with customizable components, branding, and user/company information overrides. - [`POST /api/v2/properties/search`](/docs/rest/properties/search-properties-v2): Search properties (v2) ## Questions about this - [Can I search properties over Casafari MCP?](/docs/faq/properties-over-mcp) --- # Get property by listing IDs (v1) `POST https://api.casafari.com/api/v1/properties/match-by-listings` [Properties](/docs/properties) · [REST API](/docs/rest/properties). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#properties). ## Description Returns a mapping properties IDs to listing IDs. ## Request body Content type `application/json`. Optional. Type: `object`. - `listing_ids` (integer[], required): List of listing IDs. at most 100 items; ≥ 1. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/properties/match-by-listings" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "listing_ids": [ 1, 2, 3, 4 ] }' ``` ## Responses ### 200 OK Type: `object`. - `property_id` (integer, required): ID of the property. - `listing_ids` (integer[], required): List of listing IDs. 1–2147483647. Example from the API description (long arrays shortened): ```json [ { "property_id": 12, "listing_ids": [ 1, 2 ] }, { "property_id": 34, "listing_ids": [ 3, 4 ] } ] ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [Can I search properties over Casafari MCP?](/docs/faq/properties-over-mcp) - [How do I look up one property and its price history?](/docs/faq/example-property-lookup) --- # Search properties (v1) `POST https://api.casafari.com/api/v1/properties/search` [Properties](/docs/properties) · [REST API](/docs/rest/properties). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#properties). ## Description Search properties. ## Query parameters - `limit` (integer, optional): Number of results to return per page. ≤ 100; default 20. - `offset` (integer, optional): The initial index from which to return the results. ≤ 50000. - `order` (string, optional): The order of search results. Values: `asc`, `desc`. default "asc". - `order_by` (string, optional): The field by which to sort the results. Values: `price`, `price_per_sqm`, `total_area`, `plot_area`, `bedrooms`, `construction_year`, `last_update`, `time_on_market`. ## Request body Content type `application/json`. Optional. Type: `object`. - `search_operations` (string[], required): Search business types for which the property is available. Values: `sale`, `sold`, `sale_hold`, `rent`, `rented`, `rent_hold`. - `location_ids` (integer[], optional): List of location IDs, as returned by the POST /api/v1/references/locations endpoint. at most 100 items; 1–2147483647. - `custom_location_boundary` (object, optional): Custom location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided. - `polygon` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. **This field is deprecated and will be removed in the next major update.** **Please, use `polygons` field instead.** at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to the properties. 0.05–50; default 5. - `target_point` (object, required): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. - `coordinates` (object, optional): Target point coordinates to search around. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `address` (string, optional): Address of the property to define the point to search around. - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `province` (string, optional): Name of the estate's province. - `municipality` (string, optional): Name of the estate's municipality. - `polygons` (object[][], optional): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. at most 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `conditions` (string[], optional): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `property_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for property of interest. - `property_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for property of interest. - `created_date_from` (string (date-time), optional): Created date from (in the format `YYYY-MM-DDTHH:mm:ss`). - `created_date_to` (string (date-time), optional): Created date to (in the format `YYYY-MM-DDTHH:mm:ss`). - `updated_date_from` (string (date-time), optional): Updated date from (in the format `YYYY-MM-DDTHH:mm:ss`). - `updated_date_to` (string (date-time), optional): Updated date to (in the format `YYYY-MM-DDTHH:mm:ss`). - `price_from` (integer, optional): Minimum price value. 1–2147483647. - `price_to` (integer, optional): Maximum price value. 1–2147483647. - `price_per_sqm_from` (integer, optional): Minimum value for price per square meter. 1–2147483647. - `price_per_sqm_to` (integer, optional): Maximum value for price per square meter. 1–2147483647. - `bedrooms_from` (integer, optional): Minimum number of bedrooms. 0–15000. - `bedrooms_to` (integer, optional): Maximum number of bedrooms. 0–15000. - `bathrooms_from` (integer, optional): Minimum number of bathrooms. 1–15000. - `bathrooms_to` (integer, optional): Maximum number of bathrooms. 1–15000. - `total_area_from` (integer, optional): Minimum total area. 1–10000000. - `total_area_to` (integer, optional): Maximum total area. 1–10000000. - `plot_area_from` (integer, optional): Minimum plot area. 1–10000000. - `plot_area_to` (integer, optional): Maximum plot area. 1–10000000. - `construction_year_from` (integer, optional): Minimum construction year. 1–3000. - `construction_year_to` (integer, optional): Maximum construction year. 1–3000. - `floor` (string, optional): Floor type. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (object, optional): Property characteristics. **The field was changed from Array of strings to object.** **Backwards compatibility is still supported.** - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `types` (string[], optional): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `property_types` (string[], optional): Property types, as returned by the GET /api/v1/references/types endpoint. **This field is deprecated and will be removed in the next major update.** **Please, use `types` field instead.** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `private` (boolean, optional): Whether to return properties listed by a private individual, as opposed to an agent or a professional. - `auction` (boolean, optional): Whether to return auction properties. (If the `bank` filter is also set, the result will contain both `auction` and `bank` properties) - `bank` (boolean, optional): Whether to return bank properties. (If the `auction` filter is also set, the result will contain both `bank` and `auction` properties) - `casafari_connect` (boolean, optional): Whether to return properties that have at least one listing with a company connected to Casafari Connect. - `listing_agents` (string[], optional): Return properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint. - `with_agencies` (string[], optional): Return properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclusive` (boolean, optional): Whether to return properties that are available on market exclusively from a single agency or private individual. Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `energy_certificate` (string, optional): Energy certificate. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_certificates` (string[], optional): List of energy certificates. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_ratings` (string[], optional): List of energy ratings. Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `days_on_market_from` (integer, optional): Minimum days on market value. 1–10000. - `days_on_market_to` (integer, optional): Maximum days on market value. 1–10000. - `gross_yield_from` (number, optional): Minimum gross yield value. 1–20. - `gross_yield_to` (number, optional): Maximum gross yield value. 1–20. - `rooms_from` (integer, optional): Minimum number of rooms. 1–15000. - `rooms_to` (integer, optional): Maximum number of rooms. 1–15000. - `number_of_parkings_from` (integer, optional): Minimum number of parking spaces. 1–15000. - `number_of_parkings_to` (integer, optional): Maximum number of parking spaces. 1–15000. - `living_area_from` (integer, optional): Minimum living area. 1–10000000. - `living_area_to` (integer, optional): Maximum living area. 1–10000000. - `floor_numbers` (integer[], optional): Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250. -250–250. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/properties/search" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "search_operations": [ "rented", "rent" ], "conditions": [ "used" ], "location_ids": [ 499 ], "custom_location_boundary": { "circle": { "distance": 30, "target_point": { "coordinates": { "latitude": 38.71, "longitude": -9.17 } } } }, "price_from": 800, "price_to": 10000, "price_per_sqm_from": 5, "price_per_sqm_to": 50, "bedrooms_from": 1, "bedrooms_to": 3, "bathrooms_from": 1, "bathrooms_to": 2, "rooms_from": 1, "rooms_to": 4, "number_of_parkings_from": 1, "number_of_parkings_to": 2, "total_area_from": 30, "total_area_to": 1000, "living_area_from": 20, "living_area_to": 800, "floor_numbers": [ 1, 2, 3 ], "views": [ "city" ], "directions": [ "west", "south" ], "floors": [ "middle", "top" ], "energy_ratings": [ "A", "B", "C" ], "casafari_connect": true }' ``` ## Responses ### 200 OK Type: `object[]`. - `count` (integer, optional) - `next` (string (uri), optional, nullable) - `previous` (string (uri), optional, nullable) - `results` (object, optional) - `property_id` (integer, required): ID of the property. - `primary_listing_id` (integer, required): Primary listing (ad) ID of the property which is defined after the matching into property. - `type` (string, required): Property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Property type group, as returned by the GET /api/v1/references/types endpoint. - `operations` (string[], required): Operation types for which property is available. Values: `sale`, `rent`. - `location` (object, required): Information about property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required): Information about all the parent locations (including property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `coordinates` (object, required): Property coordinates. - `latitude` (number, required): Latitude. - `longitude` (number, required): Longitude. - `total_area` (integer, required): Total area. - `living_area` (integer, required): Living area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bathrooms` (integer, required): Number of bathrooms. - `bedrooms` (integer, required): Number of bedrooms. - `rooms` (integer, required): Number of rooms. - `number_of_parkings` (integer, optional, nullable): Number of parking spaces. - `floor_number` (integer, required): Exact floor number. Negative values indicate underground floors (e.g. basements). - `rent_currency` (string, required): Rent price currency code. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `fortnight`, `month`, `year`, `none`. - `rent_price` (integer, required): Current rent price, in the currency of the listings (specified by the `rent_currency` field). - `rent_status` (string, required): Current rent status of the property. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price` (integer, required): Current sale price, in the currency of the listings (specified by the `sale_currency` field). - `sale_status` (string, required): Current sale status of the property. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `is_private_property` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `features` (object, required): Property features, as returned by the GET /api/v1/references/features endpoint. - `floor` (string, required): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, required): Property view orientation. Values: `exterior`, `interior`. - `view` (string, required): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], required): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, required): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], required): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], required): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `condition` (string, required): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `sale_time_on_market` (object, required): Information about the property last activity on the sales market. - `date_start` (string (date), required): Start date of activity on the market. - `date_end` (string (date), required): End date of activity on the market. - `days_on_market` (integer, required): Number of days property was / is on the market. - `has_untracked_period` (boolean, required): Whether the property was already on the market when it started being tracked. - `rent_time_on_market` (object, required): Information about the property last activity on the rental market. - `date_start` (string (date), required): Start date of activity on the market. - `date_end` (string (date), required): End date of activity on the market. - `days_on_market` (integer, required): Number of days property was / is on the market. - `has_untracked_period` (boolean, required): Whether the property was already on the market when it started being tracked. - `listings` (object[], required): The list of listings related to the property. - `listing_id` (integer, required): ID of the listing (ad). - `total_area` (integer, required): Total area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `bathrooms` (integer, required): Number of bathrooms. - `rooms` (integer, required): Number of rooms. - `sale_status` (string, required): Current sale status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price` (integer, required): Current sale price, in the currency of the listing (specified by the `sale_currency` field). - `sale_price_base` (integer, required): Current sale price, in Euros. - `rent_status` (string, required): Current rent status of the listing. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `rent_currency` (string, required): Rent price currency code. - `rent_price` (integer, required): Current rent price, in the currency of the listing (specified by the `rent_currency` field). - `rent_price_base` (integer, required): Current rent price, in Euros. - `agency_legal_id` (string, required): Agency legal identifier specified on the source. Only for France and its overseas territories(DROM and COM). - `agency` (string, required): The company that manages the listing. - `listing_url` (string, optional, nullable): URL of the listing. Available only for currently active listings. - `listing_old_url` (string, optional, nullable): Old URL of the listing. Available only for currently inactive listings. - `description` (string, required): Property description. - `listing_uid` (string, required): Unique ID of the listing on the source site. - `construction_year` (integer, required): Construction year. - `source_name` (string, required): The name of the source where the listing is displayed. - `contacts_info` (object, required): Information about listing contacts. - `name` (string, required): The owner name. Only for FSBO listings. - `email` (string (email), required): The email contact. - `phone` (string, required): The phone contact. - `energy_certificate` (string, required): Energy certificate classification that attests to the energy efficiency of a property. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** - `energy_rating` (string, required): Energy rating that attests to the energy efficiency of a property. - `heating_type` (string, required): Type of heating. - `ceiling_label` (string, required): Ceiling height in meters. Available only for Germany. - `commission` (number, required): Commission percentage. Available only for Germany. - `min_rent_area` (integer, required): Minimum rental area in square meters (mainly applicable to commercial properties). Available only for Germany. - `companies` (object[], required): Companies to which the listing belongs. - `name` (string, required): Company name. - `casafari_connect_on` (boolean, required): Whether the company is connected to Casafari Connect. - `created_at` (string (date), required): The datetime when the listing was added. - `floor_number` (integer, required): Exact floor number. Negative values indicate underground floors (e.g. basements). - `is_private` (boolean, required): Whether the listing is listed by a private individual, as opposed to an agent or a professional. - `casafari_connect` (boolean, required): Whether the company is connected to Casafari Connect. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `history` (object[], optional): List of sale and rent price history data. **This field is deprecated and will be removed in the next major update.** **Please, use `sale_price_history and rent_price_history` field instead.** default []. - `sale_price` (integer, required): Sale price, in the currency of the listings (specified by the `sale_currency` field). - `sale_currency` (string, required): Sale price currency code. - `rent_price` (integer, required): Rent price, in the currency of the listings (specified by the `rent_currency` field). - `rent_currency` (string, required): Rent price currency code. - `changed_at` (string (date), required): Date when the estate was last updated. - `sale_price_history` (object[], optional): List of sale price history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `sale_price_old` (integer, required): Old sale price, in the currency of the listings. - `sale_price_new` (integer, required): New sale price, in the currency of the listings. - `rent_price_history` (object[], optional): List of rent price history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `rent_price_old` (integer, required): Old rent price, in the currency of the listings. - `rent_price_new` (integer, required): New rent price, in the currency of the listings. - `sale_status_history` (object[], optional): List of sale status history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `sale_status_old` (string, required): Old sale status, in the currency of the listings. - `sale_status_new` (string, required): New sale status, in the currency of the listings. - `rent_status_history` (object[], optional): List of rent status history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `rent_status_old` (string, required): Old rent status, in the currency of the listings. - `rent_status_new` (string, required): New rent status, in the currency of the listings. - `property_url` (string, optional, nullable): URL of the property in the CASAFARI website. - `address` (string, required): Property address. - `zip_code` (string, required): The location zip code. - `distance` (number, optional, nullable): Distance in kilometers from target point to the property.Available only when the `custom_location_boundary.circle` field is defined in the request. - `description` (string, required): Property description. - `construction_year` (integer, required): Construction year. - `rent_price_base` (integer, required): Current rent price, in Euros. - `rent_price_per_sqm` (number, required): Current rent price per square meter, in the currency of the listings (specified by the `rent_currency` field). - `rent_price_per_sqm_base` (number, required): Current rent price per square meter, in Euros. - `sale_price_base` (integer, required): Current sale price, in Euros. - `sale_price_per_sqm` (number, required): Current sale price per square meter, in the currency of the listings (specified by the `sale_currency` field). - `sale_price_per_sqm_base` (number, required): Current sale price per square meter, in Euros. - `is_auction_property` (boolean, required): Whether the property is an auction property. - `is_bank_property` (boolean, required): Whether the property is a bank property. - `changed_at` (string (date), required): The date and time when the property was last updated. - `sale_price_last_change` (object, required): Information about the last change of sale price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `rent_price_last_change` (object, required): Information about the last change of rent price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `pictures` (string[], optional): List of the original picture image URLs. - `gross_yield` (number, required): Gross yield in percentage. - `title` (string, required): Property title. - `energy_certificate` (string, required): Energy certificate classification that attests to the energy efficiency of a property. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** - `energy_rating` (string, required): Energy rating that attests to the energy efficiency of a property. - `ceiling_label` (string, required): Ceiling height in meters. Available only for Germany. - `min_rent_area` (integer, required): Minimum rental area in square meters (mainly applicable to commercial properties). Available only for Germany. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `casafari_connect` (boolean, required): Whether the company is connected to Casafari Connect. - `source_floor_numbers` (integer[], optional): List of property floor numbers based on listings data. Negative values indicate underground floors (e.g. basements). default []. - `retail_data` (object, optional, nullable): Retail-related attributes of the property. Null for non-commercial properties or if the retail data is not available. - `facade_measurements` (object, required): Facade measurements of the commercial property (height, length, surface in meters). - `height` (number, required): Facade height in meters. - `length` (number, required): Facade length in meters. - `surface` (number, required): Facade surface area in square meters. - `transfer_price_range` (object, required): Price range if the property is available for transfer. - `gte` (integer, required): Lower bound of the transfer price range. - `lte` (integer, required): Upper bound of the transfer price range. - `is_street_level` (boolean, required): Whether the commercial entrance is situated at the street level, without having to go upstairs/downstairs to reach it. - `number_of_floors` (integer, required): The number of commercial property floors. - `number_of_premises` (integer, required): The number of property usable rooms/premises. - `possible_business_types` (string[], required): What kind of business can/did run in this commercial property (e.g. cafe, restaurant, grocery store, dental clinic). ### 400 Bad Request Type: `object`. - `errors` (object, optional): Description of the errors encountered. ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [Can I search properties over Casafari MCP?](/docs/faq/properties-over-mcp) --- # Get property by ID (v1) `GET https://api.casafari.com/api/v1/properties/search/{property_id}` [Properties](/docs/properties) · [REST API](/docs/rest/properties). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#properties). ## Description Returns a property object. ## Path parameters - `property_id` (string, required) ## Query parameters - `limit` (integer, optional): Number of results to return per page. - `offset` (integer, optional): Offset from which to start the search. Maximum value is 50000. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/properties/search/" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object[]`. - `count` (integer, optional) - `next` (string (uri), optional, nullable) - `previous` (string (uri), optional, nullable) - `results` (object, optional) - `property_id` (integer, required): ID of the property. - `primary_listing_id` (integer, required): Primary listing (ad) ID of the property which is defined after the matching into property. - `type` (string, required): Property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Property type group, as returned by the GET /api/v1/references/types endpoint. - `operations` (string[], required): Operation types for which property is available. Values: `sale`, `rent`. - `location` (object, required): Information about property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required): Information about all the parent locations (including property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `coordinates` (object, required): Property coordinates. - `latitude` (number, required): Latitude. - `longitude` (number, required): Longitude. - `total_area` (integer, required): Total area. - `living_area` (integer, required): Living area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bathrooms` (integer, required): Number of bathrooms. - `bedrooms` (integer, required): Number of bedrooms. - `rooms` (integer, required): Number of rooms. - `number_of_parkings` (integer, optional, nullable): Number of parking spaces. - `floor_number` (integer, required): Exact floor number. Negative values indicate underground floors (e.g. basements). - `rent_currency` (string, required): Rent price currency code. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `fortnight`, `month`, `year`, `none`. - `rent_price` (integer, required): Current rent price, in the currency of the listings (specified by the `rent_currency` field). - `rent_status` (string, required): Current rent status of the property. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price` (integer, required): Current sale price, in the currency of the listings (specified by the `sale_currency` field). - `sale_status` (string, required): Current sale status of the property. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `is_private_property` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `features` (object, required): Property features, as returned by the GET /api/v1/references/features endpoint. - `floor` (string, required): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, required): Property view orientation. Values: `exterior`, `interior`. - `view` (string, required): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], required): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, required): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], required): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], required): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `condition` (string, required): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `sale_time_on_market` (object, required): Information about the property last activity on the sales market. - `date_start` (string (date), required): Start date of activity on the market. - `date_end` (string (date), required): End date of activity on the market. - `days_on_market` (integer, required): Number of days property was / is on the market. - `has_untracked_period` (boolean, required): Whether the property was already on the market when it started being tracked. - `rent_time_on_market` (object, required): Information about the property last activity on the rental market. - `date_start` (string (date), required): Start date of activity on the market. - `date_end` (string (date), required): End date of activity on the market. - `days_on_market` (integer, required): Number of days property was / is on the market. - `has_untracked_period` (boolean, required): Whether the property was already on the market when it started being tracked. - `listings` (object[], required): The list of listings related to the property. - `listing_id` (integer, required): ID of the listing (ad). - `total_area` (integer, required): Total area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `bathrooms` (integer, required): Number of bathrooms. - `rooms` (integer, required): Number of rooms. - `sale_status` (string, required): Current sale status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price` (integer, required): Current sale price, in the currency of the listing (specified by the `sale_currency` field). - `sale_price_base` (integer, required): Current sale price, in Euros. - `rent_status` (string, required): Current rent status of the listing. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `rent_currency` (string, required): Rent price currency code. - `rent_price` (integer, required): Current rent price, in the currency of the listing (specified by the `rent_currency` field). - `rent_price_base` (integer, required): Current rent price, in Euros. - `agency_legal_id` (string, required): Agency legal identifier specified on the source. Only for France and its overseas territories(DROM and COM). - `agency` (string, required): The company that manages the listing. - `listing_url` (string, optional, nullable): URL of the listing. Available only for currently active listings. - `listing_old_url` (string, optional, nullable): Old URL of the listing. Available only for currently inactive listings. - `description` (string, required): Property description. - `listing_uid` (string, required): Unique ID of the listing on the source site. - `construction_year` (integer, required): Construction year. - `source_name` (string, required): The name of the source where the listing is displayed. - `contacts_info` (object, required): Information about listing contacts. - `name` (string, required): The owner name. Only for FSBO listings. - `email` (string (email), required): The email contact. - `phone` (string, required): The phone contact. - `energy_certificate` (string, required): Energy certificate classification that attests to the energy efficiency of a property. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** - `energy_rating` (string, required): Energy rating that attests to the energy efficiency of a property. - `heating_type` (string, required): Type of heating. - `ceiling_label` (string, required): Ceiling height in meters. Available only for Germany. - `commission` (number, required): Commission percentage. Available only for Germany. - `min_rent_area` (integer, required): Minimum rental area in square meters (mainly applicable to commercial properties). Available only for Germany. - `companies` (object[], required): Companies to which the listing belongs. - `name` (string, required): Company name. - `casafari_connect_on` (boolean, required): Whether the company is connected to Casafari Connect. - `created_at` (string (date), required): The datetime when the listing was added. - `floor_number` (integer, required): Exact floor number. Negative values indicate underground floors (e.g. basements). - `is_private` (boolean, required): Whether the listing is listed by a private individual, as opposed to an agent or a professional. - `casafari_connect` (boolean, required): Whether the company is connected to Casafari Connect. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `pictures` (string[], optional): List of the original picture image URLs. - `ref_numbers` (string[], optional): List of reference numbers. - `is_private_property` (boolean, required): Whether the listing is listed by a private individual, as opposed to an agent or a professional. - `is_auction_property` (boolean, required): Whether the listing is an auction property. - `is_bank_property` (boolean, required): Whether the listing is a bank property. - `history` (object[], optional): List of sale and rent price history data. **This field is deprecated and will be removed in the next major update.** **Please, use `sale_price_history and rent_price_history` field instead.** default []. - `sale_price` (integer, required): Sale price, in the currency of the listings (specified by the `sale_currency` field). - `sale_currency` (string, required): Sale price currency code. - `rent_price` (integer, required): Rent price, in the currency of the listings (specified by the `rent_currency` field). - `rent_currency` (string, required): Rent price currency code. - `changed_at` (string (date), required): Date when the estate was last updated. - `sale_price_history` (object[], optional): List of sale price history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `sale_price_old` (integer, required): Old sale price, in the currency of the listings. - `sale_price_new` (integer, required): New sale price, in the currency of the listings. - `rent_price_history` (object[], optional): List of rent price history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `rent_price_old` (integer, required): Old rent price, in the currency of the listings. - `rent_price_new` (integer, required): New rent price, in the currency of the listings. - `sale_status_history` (object[], optional): List of sale status history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `sale_status_old` (string, required): Old sale status, in the currency of the listings. - `sale_status_new` (string, required): New sale status, in the currency of the listings. - `rent_status_history` (object[], optional): List of rent status history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `rent_status_old` (string, required): Old rent status, in the currency of the listings. - `rent_status_new` (string, required): New rent status, in the currency of the listings. - `property_url` (string, optional, nullable): URL of the property in the CASAFARI website. - `address` (string, required): Property address. - `zip_code` (string, required): The location zip code. - `distance` (number, optional, nullable): Distance in kilometers from target point to the property.Available only when the `custom_location_boundary.circle` field is defined in the request. - `description` (string, required): Property description. - `construction_year` (integer, required): Construction year. - `rent_price_base` (integer, required): Current rent price, in Euros. - `rent_price_per_sqm` (number, required): Current rent price per square meter, in the currency of the listings (specified by the `rent_currency` field). - `rent_price_per_sqm_base` (number, required): Current rent price per square meter, in Euros. - `sale_price_base` (integer, required): Current sale price, in Euros. - `sale_price_per_sqm` (number, required): Current sale price per square meter, in the currency of the listings (specified by the `sale_currency` field). - `sale_price_per_sqm_base` (number, required): Current sale price per square meter, in Euros. - `is_auction_property` (boolean, required): Whether the property is an auction property. - `is_bank_property` (boolean, required): Whether the property is a bank property. - `changed_at` (string (date), required): The date and time when the property was last updated. - `sale_price_last_change` (object, required): Information about the last change of sale price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `rent_price_last_change` (object, required): Information about the last change of rent price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `pictures` (string[], optional): List of the original picture image URLs. - `gross_yield` (number, required): Gross yield in percentage. - `title` (string, required): Property title. - `energy_certificate` (string, required): Energy certificate classification that attests to the energy efficiency of a property. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** - `energy_rating` (string, required): Energy rating that attests to the energy efficiency of a property. - `ceiling_label` (string, required): Ceiling height in meters. Available only for Germany. - `min_rent_area` (integer, required): Minimum rental area in square meters (mainly applicable to commercial properties). Available only for Germany. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `casafari_connect` (boolean, required): Whether the company is connected to Casafari Connect. - `source_floor_numbers` (integer[], optional): List of property floor numbers based on listings data. Negative values indicate underground floors (e.g. basements). default []. - `retail_data` (object, optional, nullable): Retail-related attributes of the property. Null for non-commercial properties or if the retail data is not available. - `facade_measurements` (object, required): Facade measurements of the commercial property (height, length, surface in meters). - `height` (number, required): Facade height in meters. - `length` (number, required): Facade length in meters. - `surface` (number, required): Facade surface area in square meters. - `transfer_price_range` (object, required): Price range if the property is available for transfer. - `gte` (integer, required): Lower bound of the transfer price range. - `lte` (integer, required): Upper bound of the transfer price range. - `is_street_level` (boolean, required): Whether the commercial entrance is situated at the street level, without having to go upstairs/downstairs to reach it. - `number_of_floors` (integer, required): The number of commercial property floors. - `number_of_premises` (integer, required): The number of property usable rooms/premises. - `possible_business_types` (string[], required): What kind of business can/did run in this commercial property (e.g. cafe, restaurant, grocery store, dental clinic). ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 404 Not Found Type: `object`. - `errors` (object, optional): Description of the errors encountered. ## Questions about this - [Can I search properties over Casafari MCP?](/docs/faq/properties-over-mcp) - [How do I look up one property and its price history?](/docs/faq/example-property-lookup) - [Does Casafari keep price and status history?](/docs/faq/price-and-status-history) --- # Create a smart link (BETA) (v1) `POST https://api.casafari.com/api/v1/properties/smart-links` [Properties](/docs/properties) · [REST API](/docs/rest/properties). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#properties). ## Description Generates a smart link that provides detailed property information with customizable components, branding, and user/company information overrides. ## Request body Content type `application/json`. Optional. Type: `object`. - `primary_listing_ids` (integer[], required): List of primary listing ids to include in the smart link. 1–10 items. - `settings` (object, required) - `is_indexing_by_search_engine` (boolean, optional): Determines whether a share page should be indexed by search engines. default false. - `is_hide_source` (boolean, optional): Removes the "Sourced by Casafari" label from the Smartlink page. default false. - `language` (string, required): Language of the share page. Values: `en`, `fr`, `it`, `pt`, `es`, `de`. - `brand_color` (string, optional): Main color of graphical elements in the report. at most 9 characters. - `components_to_include` (string[], optional): List of components to include in the smart link. Values: `price`, `days_on_market`, `price_change`, `sources`, `history`, `location_intelligence`, `comparables`, `valuation`, `market_analytics`. default ["price"]. - `user` (object, required) - `first_name` (string, required) - `last_name` (string, required) - `email` (string (email), required) - `phone` (string, required) - `photo_url` (string (uri), optional) pattern `^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*)?@)?(?:(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)(?:\.(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)){3}|\[[0-9a-f:.]+\]|([a-z¡-￿0-9](?:[a-z¡-￿0-9-]{0,61}[a-z¡-￿0-9])?(?:\.(?!-)[a-z¡-￿0-9-]{1,63}(? # Search properties (v2) `POST https://api.casafari.com/api/v2/properties/search` [Properties](/docs/properties) · [REST API](/docs/rest/properties). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#properties). ## Description Search properties. ## Query parameters - `limit` (integer, optional): Number of results to return per page. ≤ 100; default 20. - `order` (string, optional): The order of search results. Values: `asc`, `desc`. default "asc". - `order_by` (string, optional): The field by which to sort the results. Values: `price`, `price_per_sqm`, `total_area`, `plot_area`, `bedrooms`, `construction_year`, `last_update`, `time_on_market`. ## Request body Content type `application/json`. Optional. Type: `object`. - `search_operations` (string[], required): Search business types for which the property is available. Values: `sale`, `sold`, `sale_hold`, `rent`, `rented`, `rent_hold`. - `location_ids` (integer[], optional): List of location IDs, as returned by the POST /api/v1/references/locations endpoint. at most 100 items; 1–2147483647. - `custom_location_boundary` (object, optional): Custom location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided. - `polygon` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. **This field is deprecated and will be removed in the next major update.** **Please, use `polygons` field instead.** at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to the properties. 0.05–50; default 5. - `target_point` (object, required): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. - `coordinates` (object, optional): Target point coordinates to search around. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `address` (string, optional): Address of the property to define the point to search around. - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `province` (string, optional): Name of the estate's province. - `municipality` (string, optional): Name of the estate's municipality. - `polygons` (object[][], optional): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. at most 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `conditions` (string[], optional): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `property_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for property of interest. - `property_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for property of interest. - `created_date_from` (string (date-time), optional): Created date from (in the format `YYYY-MM-DDTHH:mm:ss`). - `created_date_to` (string (date-time), optional): Created date to (in the format `YYYY-MM-DDTHH:mm:ss`). - `updated_date_from` (string (date-time), optional): Updated date from (in the format `YYYY-MM-DDTHH:mm:ss`). - `updated_date_to` (string (date-time), optional): Updated date to (in the format `YYYY-MM-DDTHH:mm:ss`). - `price_from` (integer, optional): Minimum price value. 1–2147483647. - `price_to` (integer, optional): Maximum price value. 1–2147483647. - `price_per_sqm_from` (integer, optional): Minimum value for price per square meter. 1–2147483647. - `price_per_sqm_to` (integer, optional): Maximum value for price per square meter. 1–2147483647. - `bedrooms_from` (integer, optional): Minimum number of bedrooms. 0–15000. - `bedrooms_to` (integer, optional): Maximum number of bedrooms. 0–15000. - `bathrooms_from` (integer, optional): Minimum number of bathrooms. 1–15000. - `bathrooms_to` (integer, optional): Maximum number of bathrooms. 1–15000. - `total_area_from` (integer, optional): Minimum total area. 1–10000000. - `total_area_to` (integer, optional): Maximum total area. 1–10000000. - `plot_area_from` (integer, optional): Minimum plot area. 1–10000000. - `plot_area_to` (integer, optional): Maximum plot area. 1–10000000. - `construction_year_from` (integer, optional): Minimum construction year. 1–3000. - `construction_year_to` (integer, optional): Maximum construction year. 1–3000. - `floor` (string, optional): Floor type. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (object, optional): Property characteristics. **The field was changed from Array of strings to object.** **Backwards compatibility is still supported.** - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `types` (string[], optional): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, apartment, dachgeschosswohnung, erdgeschosswohnung, duplex, etagenwohnung, studio **house:** einfamilienhaus, family_house (DEPRECATED), reihenmittelhaus, house, villa, country_house, zweifamilienhaus, landwirtschaftliche_betriebe, palace, bungalow, townhouse, reihenhaus, chalet, country_estate, reihenendhaus **room:** room **building:** mix_use_building, office_building, apartment_building **investment:** other_commercial, warehouse, office, retail, hotel, werkstatt, industrial, restaurant **plot:** urban_plot, plot (DEPRECATED), rural_plot **other:** garage, other, parking Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `property_types` (string[], optional): Property types, as returned by the GET /api/v1/references/types endpoint. **This field is deprecated and will be removed in the next major update.** **Please, use `types` field instead.** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `private` (boolean, optional): Whether to return properties listed by a private individual, as opposed to an agent or a professional. - `auction` (boolean, optional): Whether to return auction properties. (If the `bank` filter is also set, the result will contain both `auction` and `bank` properties) - `bank` (boolean, optional): Whether to return bank properties. (If the `auction` filter is also set, the result will contain both `bank` and `auction` properties) - `casafari_connect` (boolean, optional): Whether to return properties that have at least one listing with a company connected to Casafari Connect. - `listing_agents` (string[], optional): Return properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint. - `with_agencies` (string[], optional): Return properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclusive` (boolean, optional): Whether to return properties that are available on market exclusively from a single agency or private individual. Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `energy_certificate` (string, optional): Energy certificate. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_certificates` (string[], optional): List of energy certificates. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_ratings` (string[], optional): List of energy ratings. Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `days_on_market_from` (integer, optional): Minimum days on market value. 1–10000. - `days_on_market_to` (integer, optional): Maximum days on market value. 1–10000. - `gross_yield_from` (number, optional): Minimum gross yield value. 1–20. - `gross_yield_to` (number, optional): Maximum gross yield value. 1–20. - `rooms_from` (integer, optional): Minimum number of rooms. 1–15000. - `rooms_to` (integer, optional): Maximum number of rooms. 1–15000. - `number_of_parkings_from` (integer, optional): Minimum number of parking spaces. 1–15000. - `number_of_parkings_to` (integer, optional): Maximum number of parking spaces. 1–15000. - `living_area_from` (integer, optional): Minimum living area. 1–10000000. - `living_area_to` (integer, optional): Maximum living area. 1–10000000. - `floor_numbers` (integer[], optional): Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250. -250–250. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v2/properties/search" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "search_operations": [ "rented", "rent" ], "conditions": [ "used" ], "location_ids": [ 499 ], "custom_location_boundary": { "circle": { "distance": 30, "target_point": { "coordinates": { "latitude": 38.71, "longitude": -9.17 } } } }, "price_from": 800, "price_to": 10000, "price_per_sqm_from": 5, "price_per_sqm_to": 50, "bedrooms_from": 1, "bedrooms_to": 3, "bathrooms_from": 1, "bathrooms_to": 2, "rooms_from": 1, "rooms_to": 4, "total_area_from": 30, "total_area_to": 1000, "living_area_from": 20, "living_area_to": 800, "floor_numbers": [ 1, 2, 3 ], "views": [ "city" ], "directions": [ "west", "south" ], "floors": [ "middle", "top" ], "energy_ratings": [ "A", "B", "C" ], "casafari_connect": true }' ``` ## Responses ### 200 OK Type: `object[]`. - `property_id` (integer, required): ID of the property. - `primary_listing_id` (integer, required): Primary listing (ad) ID of the property which is defined after the matching into property. - `type` (string, required): Property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Property type group, as returned by the GET /api/v1/references/types endpoint. - `operations` (string[], required): Operation types for which property is available. Values: `sale`, `rent`. - `location` (object, required): Information about property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required): Information about all the parent locations (including property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `coordinates` (object, required): Property coordinates. - `latitude` (number, required): Latitude. - `longitude` (number, required): Longitude. - `total_area` (integer, required): Total area. - `living_area` (integer, required): Living area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bathrooms` (integer, required): Number of bathrooms. - `bedrooms` (integer, required): Number of bedrooms. - `rooms` (integer, required): Number of rooms. - `number_of_parkings` (integer, optional, nullable): Number of parking spaces. - `floor_number` (integer, required): Exact floor number. Negative values indicate underground floors (e.g. basements). - `rent_currency` (string, required): Rent price currency code. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `fortnight`, `month`, `year`, `none`. - `rent_price` (integer, required): Current rent price, in the currency of the listings (specified by the `rent_currency` field). - `rent_status` (string, required): Current rent status of the property. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price` (integer, required): Current sale price, in the currency of the listings (specified by the `sale_currency` field). - `sale_status` (string, required): Current sale status of the property. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `is_private_property` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `features` (object, required): Property features, as returned by the GET /api/v1/references/features endpoint. - `floor` (string, required): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, required): Property view orientation. Values: `exterior`, `interior`. - `view` (string, required): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], required): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, required): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], required): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], required): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `condition` (string, required): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `sale_time_on_market` (object, required): Information about the property last activity on the sales market. - `date_start` (string (date), required): Start date of activity on the market. - `date_end` (string (date), required): End date of activity on the market. - `days_on_market` (integer, required): Number of days property was / is on the market. - `has_untracked_period` (boolean, required): Whether the property was already on the market when it started being tracked. - `rent_time_on_market` (object, required): Information about the property last activity on the rental market. - `date_start` (string (date), required): Start date of activity on the market. - `date_end` (string (date), required): End date of activity on the market. - `days_on_market` (integer, required): Number of days property was / is on the market. - `has_untracked_period` (boolean, required): Whether the property was already on the market when it started being tracked. - `listings` (object[], required): The list of listings related to the property. - `listing_id` (integer, required): ID of the listing (ad). - `total_area` (integer, required): Total area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `bathrooms` (integer, required): Number of bathrooms. - `rooms` (integer, required): Number of rooms. - `sale_status` (string, required): Current sale status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price` (integer, required): Current sale price, in the currency of the listing (specified by the `sale_currency` field). - `sale_price_base` (integer, required): Current sale price, in Euros. - `rent_status` (string, required): Current rent status of the listing. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `rent_currency` (string, required): Rent price currency code. - `rent_price` (integer, required): Current rent price, in the currency of the listing (specified by the `rent_currency` field). - `rent_price_base` (integer, required): Current rent price, in Euros. - `agency_legal_id` (string, required): Agency legal identifier specified on the source. Only for France and its overseas territories(DROM and COM). - `agency` (string, required): The company that manages the listing. - `listing_url` (string, optional, nullable): URL of the listing. Available only for currently active listings. - `listing_old_url` (string, optional, nullable): Old URL of the listing. Available only for currently inactive listings. - `description` (string, required): Property description. - `listing_uid` (string, required): Unique ID of the listing on the source site. - `construction_year` (integer, required): Construction year. - `source_name` (string, required): The name of the source where the listing is displayed. - `contacts_info` (object, required): Information about listing contacts. - `name` (string, required): The owner name. Only for FSBO listings. - `email` (string (email), required): The email contact. - `phone` (string, required): The phone contact. - `energy_certificate` (string, required): Energy certificate classification that attests to the energy efficiency of a property. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** - `energy_rating` (string, required): Energy rating that attests to the energy efficiency of a property. - `heating_type` (string, required): Type of heating. - `ceiling_label` (string, required): Ceiling height in meters. Available only for Germany. - `commission` (number, required): Commission percentage. Available only for Germany. - `min_rent_area` (integer, required): Minimum rental area in square meters (mainly applicable to commercial properties). Available only for Germany. - `companies` (object[], required): Companies to which the listing belongs. - `name` (string, required): Company name. - `casafari_connect_on` (boolean, required): Whether the company is connected to Casafari Connect. - `created_at` (string (date), required): The datetime when the listing was added. - `floor_number` (integer, required): Exact floor number. Negative values indicate underground floors (e.g. basements). - `is_private` (boolean, required): Whether the listing is listed by a private individual, as opposed to an agent or a professional. - `casafari_connect` (boolean, required): Whether the company is connected to Casafari Connect. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `history` (object[], optional): List of sale and rent price history data. **This field is deprecated and will be removed in the next major update.** **Please, use `sale_price_history and rent_price_history` field instead.** default []. - `sale_price` (integer, required): Sale price, in the currency of the listings (specified by the `sale_currency` field). - `sale_currency` (string, required): Sale price currency code. - `rent_price` (integer, required): Rent price, in the currency of the listings (specified by the `rent_currency` field). - `rent_currency` (string, required): Rent price currency code. - `changed_at` (string (date), required): Date when the estate was last updated. - `sale_price_history` (object[], optional): List of sale price history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `sale_price_old` (integer, required): Old sale price, in the currency of the listings. - `sale_price_new` (integer, required): New sale price, in the currency of the listings. - `rent_price_history` (object[], optional): List of rent price history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `rent_price_old` (integer, required): Old rent price, in the currency of the listings. - `rent_price_new` (integer, required): New rent price, in the currency of the listings. - `sale_status_history` (object[], optional): List of sale status history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `sale_status_old` (string, required): Old sale status, in the currency of the listings. - `sale_status_new` (string, required): New sale status, in the currency of the listings. - `rent_status_history` (object[], optional): List of rent status history data. default []. - `date_start` (string (date), required): Start date when the change was applied. - `date_end` (string (date), required): End date when the change was applied. - `rent_status_old` (string, required): Old rent status, in the currency of the listings. - `rent_status_new` (string, required): New rent status, in the currency of the listings. - `property_url` (string, optional, nullable): URL of the property in the CASAFARI website. - `address` (string, required): Property address. - `zip_code` (string, required): The location zip code. - `distance` (number, optional, nullable): Distance in kilometers from target point to the property.Available only when the `custom_location_boundary.circle` field is defined in the request. - `description` (string, required): Property description. - `construction_year` (integer, required): Construction year. - `rent_price_base` (integer, required): Current rent price, in Euros. - `rent_price_per_sqm` (number, required): Current rent price per square meter, in the currency of the listings (specified by the `rent_currency` field). - `rent_price_per_sqm_base` (number, required): Current rent price per square meter, in Euros. - `sale_price_base` (integer, required): Current sale price, in Euros. - `sale_price_per_sqm` (number, required): Current sale price per square meter, in the currency of the listings (specified by the `sale_currency` field). - `sale_price_per_sqm_base` (number, required): Current sale price per square meter, in Euros. - `is_auction_property` (boolean, required): Whether the property is an auction property. - `is_bank_property` (boolean, required): Whether the property is a bank property. - `changed_at` (string (date), required): The date and time when the property was last updated. - `sale_price_last_change` (object, required): Information about the last change of sale price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `rent_price_last_change` (object, required): Information about the last change of rent price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `pictures` (string[], optional): List of the original picture image URLs. - `gross_yield` (number, required): Gross yield in percentage. - `title` (string, required): Property title. - `energy_certificate` (string, required): Energy certificate classification that attests to the energy efficiency of a property. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** - `energy_rating` (string, required): Energy rating that attests to the energy efficiency of a property. - `ceiling_label` (string, required): Ceiling height in meters. Available only for Germany. - `min_rent_area` (integer, required): Minimum rental area in square meters (mainly applicable to commercial properties). Available only for Germany. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `casafari_connect` (boolean, required): Whether the company is connected to Casafari Connect. - `source_floor_numbers` (integer[], optional): List of property floor numbers based on listings data. Negative values indicate underground floors (e.g. basements). default []. - `retail_data` (object, optional, nullable): Retail-related attributes of the property. Null for non-commercial properties or if the retail data is not available. - `facade_measurements` (object, required): Facade measurements of the commercial property (height, length, surface in meters). - `height` (number, required): Facade height in meters. - `length` (number, required): Facade length in meters. - `surface` (number, required): Facade surface area in square meters. - `transfer_price_range` (object, required): Price range if the property is available for transfer. - `gte` (integer, required): Lower bound of the transfer price range. - `lte` (integer, required): Upper bound of the transfer price range. - `is_street_level` (boolean, required): Whether the commercial entrance is situated at the street level, without having to go upstairs/downstairs to reach it. - `number_of_floors` (integer, required): The number of commercial property floors. - `number_of_premises` (integer, required): The number of property usable rooms/premises. - `possible_business_types` (string[], required): What kind of business can/did run in this commercial property (e.g. cafe, restaurant, grocery store, dental clinic). ### 400 Bad Request Type: `object`. - `errors` (object, optional): Description of the errors encountered. ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [Can I search properties over Casafari MCP?](/docs/faq/properties-over-mcp) - [How do I look up one property and its price history?](/docs/faq/example-property-lookup) --- # Comparables & Valuation Comparable properties and estimated prices for a home: properties on the market, past sales and rentals, and official registry records, matched around a point, an address or a cadastral reference. 1 MCP tool · 4 REST operations. ## MCP tools | Tool | Title | What it does | |---|---|---| | [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) | Get Comparables | Retrieves comparable real estate properties and AI-powered market valuations using the Casafari Comparables Engine. | ## REST API 4 operations in the public OpenAPI description, all under `https://api.casafari.com` with a bearer token ([how to get one](/docs/rest#get-a-token)). The same list with more detail: [Comparables & Valuation REST API](/docs/rest/comparables-valuation). ### Comparables Paths under `/api`. - [`POST /api/v1/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v1): Search comparables (v1). Returns comparable properties by the given parameters. - [`POST /api/v2/comparables/ai-builder`](/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2): Initialize an AI Builder session (v2). Initializes an AI Builder session from a saved CMA (valuation) and returns the generated report ID along with the URL of the AI Builder session. - [`POST /api/v2/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v2): Search comparables (v2). Returns comparable properties by the given parameters. ### Valuation - [`POST /api/v1/valuation/comparables-prices`](/docs/rest/comparables-valuation/search-estimated-prices-v1): Search estimated prices (v1). Returns estimated prices by the given parameters. ## MCP and REST compared Over MCP: 1 tool. Over REST: 4 operations. Available over both. - Equivalent: [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) and [`POST /api/v2/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v2). - Related: [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) and [`POST /api/v1/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v1). - Related: [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) and [`POST /api/v1/valuation/comparables-prices`](/docs/rest/comparables-valuation/search-estimated-prices-v1). Only over REST: [`POST /api/v2/comparables/ai-builder`](/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2). Details: [MCP and REST compared](/docs/parity#comparables-valuation). ## Ask your assistant > What is a 3-bedroom flat near Avenida da Liberdade, Lisbon worth? Use comparables within 1 km. ## Questions about this - [What is Casafari MCP?](/docs/faq/what-is-casafari-mcp) - [Which countries does Casafari cover?](/docs/faq/which-countries) - [Does Casafari cover Spain and Portugal?](/docs/faq/coverage-spain-portugal) - [Which products does Casafari MCP offer, and how many tools are there?](/docs/faq/which-products) - [What does Comparables & Valuation do?](/docs/faq/what-is-comparables-valuation) --- # `comps_get-comparables` Get Comparables. Product: [Comparables & Valuation](/docs/comparables-valuation). Annotations: Read-only. Call it as `comps_get-comparables` on `https://mcp.casafari.com/` (the backend's own name is `get-comparables`). Over REST: [`POST /api/v2/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v2) (equivalent), [`POST /api/v1/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v1) (related), [`POST /api/v1/valuation/comparables-prices`](/docs/rest/comparables-valuation/search-estimated-prices-v1) (related). [MCP and REST compared](/docs/parity#comparables-valuation). ## Description Retrieves **comparable real estate properties** and **AI-powered market valuations** using the Casafari Comparables Engine. The tool analyzes: - **Active listings** – current market offerings - **Historical transactions** – past sales and rentals - **Verified DVF data** – official property transfer records Returns: - **Matched comparable properties** ranked by relevance - **Aggregated market statistics** (median prices, DOM, listing velocity) - **Estimated price ranges**: fair market value, quick-sale price, premium pricing #### Primary Use Cases | Use Case | Description | |----------|-------------| | **Property Valuation** | Price a listing based on real market data | | **Comp Analysis** | Find similar properties for BPO/CMA reports | | **Market Research** | Analyze local trends, absorption rates, pricing dynamics | | **Investment Modeling** | Assess fair value vs. asking price spreads | | **Historical Trends** | Track price evolution using sold_or_rented_after filter | #### Key Capabilities ##### Advanced Filtering - **Property attributes**: type, bedrooms, bathrooms, size, condition - **Structural features**: floor level, orientation, views, parking, storage - **Quality markers**: construction year, energy rating, renovation status - **Characteristic logic**: must-have / nice-to-have / exclude lists - **Temporal filters**: sold/rented after specific date ##### Spatial Precision Uses a **circle boundary** (target point + radius in kilometers) or a **closed polygon** of geo-points to ensure all comparables reflect the same micro-market conditions. The target point accepts coordinates, an address, or a Spanish cadastral reference. ##### Output Intelligence - **Property-level data**: individual comp details with photos, descriptions, pricing history - **Registry data**: DVF records (dvf_results) and notarial transactions (transactional_data) - **Market-level stats**: aggregated insights (median $/sqm, average DOM, inventory levels) - **Valuation estimates**: algorithmic price recommendations based on comp set #### Pro Tips - Use tight radius (0.5-1 km) for urban areas, wider (2-5 km) for rural - Combine sold_or_rented_after with recent date for "hot market" analysis - Leverage characteristic filters to match unique property features (e.g., sea views, penthouse, ground floor) - Check both active listings AND sold comps for complete market picture --- **Powered by Casafari's proprietary matching algorithm** – trained on millions of European property transactions. ## Parameters - `comparables_count` (integer, required): Maximum number of comparable properties in results. 1–50. - `location_boundary` (object, required): Location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided. - `polygon` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to the properties. Default value: 5. 0.05–50. - `target_point` (object, required): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. - `coordinates` (object, optional): Target point coordinates to search around. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `address` (string, optional): Address of the property to define the point to search around. - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `province` (string, optional): Name of the estate's province. - `municipality` (string, optional): Name of the estate's municipality. - `sold_or_rented_after` (string, optional, nullable): Properties sold/rented since this date (in the format `YYYY-MM-DD`) will be considered as possible comparables. Default value: 9 months ago, counting from today. If `null` is passed, only active properties will be considered. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `comparables_types` (string[], required): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: apartment: erdgeschosswohnung, etagenwohnung, dachgeschosswohnung, duplex, studio, penthouse, apartment house: villa, reihenhaus, palace, country_estate, family_house (DEPRECATED), zweifamilienhaus, reihenmittelhaus, reihenendhaus, landwirtschaftliche_betriebe, country_house, townhouse, chalet, bungalow, einfamilienhaus, house room: room building: mix_use_building, office_building, apartment_building investment: restaurant, other_commercial, warehouse, office, industrial, werkstatt, hotel, retail plot: plot (DEPRECATED), rural_plot, urban_plot other: garage, other, parking Note that you can select multiple types only from one property type group. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `min_price` (integer, optional): The minimum price filter for comparables result. Default value: 0. 0–2147483647. - `max_price` (integer, optional): The maximum price filter for comparables result. 1–2147483647. - `condition` (string, optional): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `bedrooms` (integer, optional): Number of bedrooms (cannot be used together with `rooms`). 0–15000. - `rooms` (integer, optional): Number of rooms (cannot be used together with `bedrooms`). 0–15000. - `bathrooms` (integer, optional): Number of bathrooms. 1–15000. - `construction_year` (integer, optional): Desired construction year. 1–3000. - `total_area` (integer, optional): Desired total area, square meters. This field is required for `hotel`, `industrial`, `office`, `other_commercial`, `restaurant`, `retail`, `warehouse`, `werkstatt` property types if `target_point.cadastral_reference` is not provided. 5–10000000. - `plot_area` (integer, optional): Desired plot area, square meters. This field is required for `rural_plot` and `urban_plot` property types if `target_point.cadastral_reference` is not provided. 20–10000000. - `floors` (string[], optional): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`. - `floor_number` (integer[], optional): Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250. -250–250. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `views` (string[], optional): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `directions` (string[], optional): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (object, optional): Property characteristics. - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `nice_to_have` (string[], optional): Include properties that have any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `energy_ratings` (string[], optional): List of energy ratings. Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `days_on_market_from` (integer, optional): Minimum days on market value. 1–10000. - `days_on_market_to` (integer, optional): Maximum days on market value. 1–10000. - `with_agencies` (string[], optional): Return properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. Default value: true. ## Response - `results` (object[], required): Array of found comparable properties. - `property_id` (integer, required): ID of the property. - `property_url` (string, optional, nullable): URL of the property in the CASAFARI website. - `primary_listing_id` (integer, required): Primary listing (ad) ID of the property which is defined after the matching into property. - `type` (string, required): Property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Property type group, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `house`, `investment`, `plot`, `other`. - `coordinates` (object, required): Property coordinates. - `latitude` (number, required): Latitude. - `longitude` (number, required): Longitude. - `location` (object, required): Information about property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional, nullable): The location zip codes. - `locations_structure` (object[], required): Information about all the parent locations (including property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional, nullable): The location zip codes. - `address` (string, required): Property address. - `zip_code` (string, required): The location zip code. - `distance` (number, optional, nullable): Distance in kilometers from target point to the property. Not calculated for search by polygon. - `construction_year` (integer, required): Construction year. - `total_area` (integer, required): Total area. - `living_area` (integer, required): Living area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `rooms` (integer, required): Number of rooms. - `bathrooms` (integer, required): Number of bathrooms. - `floor_number` (integer, required): Exact floor number. Negative values indicate underground floors (e.g. basements). - `condition` (string, required): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `features` (object, required): Property features, as returned by the GET /api/v1/references/features endpoint. - `floor` (string, required): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, required): Property view orientation. Values: `exterior`, `interior`. - `view` (string, required): View from the property. This field is deprecated and will be removed in the next major update. Please, use `views` field instead. Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], required): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, required): Cardinal direction the property faces. This field is deprecated and will be removed in the next major update. Please, use `directions` field instead. Values: `north`, `south`, `east`, `west`. - `directions` (string[], required): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], required): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `operations` (string[], required): Operation types for which property is available. Values: `sale`, `rent`. - `sale_status` (string, required): Sale status. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price` (integer, required): Sale price, in the currency of the listings (specified by the `sale_currency` field). - `sale_price_base` (integer, required): Sale price, in Euros. - `sale_price_per_sqm` (number, required): Sale price per square meter, in the currency of the listings (specified by the `sale_currency` field). - `sale_price_per_sqm_base` (number, required): Sale price per square meter, in Euros. - `rent_status` (string, required): Rent status. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `rent_currency` (string, required): Rent price currency code. - `rent_price` (integer, required): Rent price, in the currency of the listings (specified by the `rent_currency` field). - `rent_price_base` (integer, required): Rent price, in Euros. - `rent_price_per_sqm` (number, required): Rent price per square meter, in the currency of the listings (specified by the `rent_currency` field). - `rent_price_per_sqm_base` (number, required): Rent price per square meter, in Euros. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `fortnight`, `month`, `year`, `none`. - `title` (string, required): Property title. - `description` (string, required): Property description. - `thumbnails` (string[], optional, nullable): List of the thumbnail image URLs. - `pictures` (string[], optional, nullable): List of the original picture image URLs. - `gross_yield` (number, required): Gross yield in percentage. - `sold_at` (string, required): Date when the property was sold. - `rented_at` (string, required): Date when the property was rented. - `total_sale_price_change` (number, required): Total sale price change in percents. - `total_rent_price_change` (number, required): Total rent price change in percents. - `last_sale_price_reduction` (number, required): Last sale price reduction in percents. - `last_rent_price_reduction` (number, required): Last rent price reduction in percents. - `sale_price_last_change` (object, required): Information about the last change of sale price. - `change_date` (string, required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `rent_price_last_change` (object, required): Information about the last change of rent price. - `change_date` (string, required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `sale_time_on_market` (map of any, optional, nullable): Information about the property last activity on the sales market. - `rent_time_on_market` (map of any, optional, nullable): Information about the property last activity on the rental market. - `sale_active_listings_count` (integer, optional, nullable): Number of active listings for this property on the sales market. - `rent_active_listings_count` (integer, optional, nullable): Number of active listings for this property on the rental market. - `similarity_score` (number, optional, nullable): Similarity score of the property. Value between 0 and 1. Indicates how property parameters are close to the requested ones. - `listing_urls` (string[], required): Listing urls of the comparable. - `is_outlier` (boolean, optional, nullable): Whether the property is considered an outlier based on its price. Default value: false. - `is_private_property` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `energy_certificate` (string, optional, nullable): Energy certificate classification that attests to the energy efficiency of a property. This field is deprecated and will be removed in the next major update. Please, use `energy_rating` field instead. - `energy_rating` (string, optional, nullable): Energy rating that attests to the energy efficiency of a property. - `ref_numbers` (string[], required): List of reference numbers from listings. - `dvf_results` (object[], optional): Array of found DVF data (Request for geolocated property values). - `dvf_reference` (integer, required): Reference ID of the DVF property. - `coordinates` (object, required): DVF property coordinates. - `lat` (number, required): Latitude. - `lon` (number, required): Longitude. - `distance` (number, optional, nullable): Distance in kilometers from target point to DVF the property. Not calculated for search by polygon. - `type` (string, required): Property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Property type group, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `house`, `investment`, `plot`, `other`. - `sale_price` (integer, required): Sale price, in the original currency. - `sale_price_base` (integer, required): Sale price, in Euros. - `sale_price_psqm` (number, optional, nullable): Sale price per square meter, in the original currency. Default value: 0. - `sale_price_psqm_base` (number, optional, nullable): Sale price per square meter, in Euros. Default value: 0. - `sold_at` (string, optional, nullable): Date when the property was sold. - `total_area` (integer, required): Total area. - `plot_area` (integer, required): Plot area. - `rooms` (integer, required): Number of rooms. - `bedrooms` (integer, required): Number of bedrooms. - `address` (string, required): Property address. - `location` (object, required): Information about DVF property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional, nullable): The location zip codes. - `locations_structure` (object[], required): Information about all the parent locations (including DVF property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional, nullable): The location zip codes. - `sale_status` (string, optional, nullable): Sale status. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `thumbnails` (string[], optional, nullable): List of the thumbnail image URLs. - `transactional_data` (object[], optional, nullable) - `id` (integer, required) - `reference` (string, required) - `cadastral_reference` (string, required) - `rooms` (integer, required) - `bedrooms` (integer, required) - `bathrooms` (integer, required) - `coordinates` (object, required) - `lat` (number, required): Latitude. - `lon` (number, required): Longitude. - `total_area` (number, required) - `plot_area` (number, required) - `address` (string, required) - `source_typology` (string, required) - `source_annexes` (string, required): Additional raw source data (if present), describing annexes (such as parking, storage, etc) included in the transaction price. - `type` (string, required) Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required) - `sold_at` (string, required) - `currency` (string, required): Price currency code. - `price` (number, required) - `price_per_sqm` (number, required) - `with_mortgage` (boolean, required): Flag indicating whether the transaction was financed with a mortgage. - `distance` (number, optional, nullable): Distance in kilometers from target point to the property. Not calculated for search by polygon. - `location_id` (integer, required) - `construction_year` (integer, required) - `location` (object, required) - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional, nullable): The location zip codes. - `locations_structure` (object[], required) - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional, nullable): The location zip codes. - `image_url` (string, required) - `country_code` (string, required) Values: `FR`, `IT`, `PT`, `ES`. - `statistics` (object, required): Statistics information for the found comparables (for `operation` defined in the request). - `average_price` (integer, required): Average price. - `average_price_per_sqm` (number, required): Average price per square meter. - `average_time_on_the_market` (integer, required): Average number of days on the market. - `average_listings_per_property` (number, required): Average number of listings per property. - `sold_or_rented_in_last_six_months` (integer, required): Number of properties that were sold or rented during the last 6 months in the requested location. - `estimated_prices` (object, required): Estimated prices calculated based on the found comparables (for `operation` defined in the request). - `fast_sell_price` (integer, required): Fast sell price. - `fair_market_price` (integer, required): Fair market price. - `out_of_market_price` (integer, required): Out of market price. - `fast_sell_price_per_sqm` (number, required): Fast sell price per square meter. - `fair_market_price_per_sqm` (number, required): Fair market price per square meter. - `out_of_market_price_per_sqm` (number, required): Out of market price per square meter. - `casafari_link` (string, required): Link to Comparative Market Analysis page. - `valuation_id` (integer, optional, nullable): Persistent valuation ID used to generate Smart Link or a PDF. Expires in a year. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "comps_get-comparables", "arguments": { "comparables_count": 1, "location_boundary": { "polygon": [ { "latitude": -90, "longitude": -180 } ] }, "operation": "sale", "comparables_types": [ "apartment" ] } } } ``` ## Questions about this - [Does Casafari cover Spain and Portugal?](/docs/faq/coverage-spain-portugal) - [Does every tool cover all 16 countries?](/docs/faq/per-tool-coverage) - [What does Comparables & Valuation do?](/docs/faq/what-is-comparables-valuation) - [How do I value a home or find comparables with Casafari MCP?](/docs/faq/example-valuation) - [Can I build a market report with Casafari MCP?](/docs/faq/example-market-report) --- # Comparables & Valuation REST API Comparable properties and estimated prices for a home: properties on the market, past sales and rentals, and official registry records, matched around a point, an address or a cadastral reference. 4 operations, from the public OpenAPI description. Base URL `https://api.casafari.com`; every operation but sign-in needs a bearer token (see [the REST API overview](/docs/rest#get-a-token)). Over MCP, Comparables & Valuation has 1 tool: see [Comparables & Valuation](/docs/comparables-valuation) and [MCP and REST compared](/docs/parity#comparables-valuation). ## Comparables Paths under `/api`. - [`POST /api/v1/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v1): Search comparables (v1). Returns comparable properties by the given parameters. - [`POST /api/v2/comparables/ai-builder`](/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2): Initialize an AI Builder session (v2). Initializes an AI Builder session from a saved CMA (valuation) and returns the generated report ID along with the URL of the AI Builder session. - [`POST /api/v2/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v2): Search comparables (v2). Returns comparable properties by the given parameters. ## Valuation - [`POST /api/v1/valuation/comparables-prices`](/docs/rest/comparables-valuation/search-estimated-prices-v1): Search estimated prices (v1). Returns estimated prices by the given parameters. ## Questions about this - [What does Comparables & Valuation do?](/docs/faq/what-is-comparables-valuation) --- # Search comparables (v1) `POST https://api.casafari.com/api/v1/comparables/search` [Comparables & Valuation](/docs/comparables-valuation) · [REST API](/docs/rest/comparables-valuation). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) (related). See [MCP and REST compared](/docs/parity#comparables-valuation). ## Description Returns comparable properties by the given parameters. ## Request body Content type `application/json`. Optional. Type: `object`. - `comparables_count` (integer, required): Maximum number of comparable properties in results. 1–50. - `coordinates` (object, optional): Target point coordinates to search around. **This field is deprecated and will be removed in the next major update.** **Please, use `target_point.coordinates` field instead.** - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `target_point` (object, optional): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. **This field is deprecated and will be removed in the next major update.** **Please, use `location_boundary.circle` field instead.** - `coordinates` (object, optional): Target point coordinates to search around. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `address` (string, optional): Address of the property to define the point to search around. - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `province` (string, optional): Name of the estate's province. - `municipality` (string, optional): Name of the estate's municipality. - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to comparable properties. **This field is deprecated and will be removed in the next major update.** **Please, use `location_boundary.circle` field instead.** 0.05–50; default 5. - `location_boundary` (object, required): Location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided. - `polygon` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to the properties. 0.05–50; default 5. - `target_point` (object, required): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. - `coordinates` (object, optional): Target point coordinates to search around. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `address` (string, optional): Address of the property to define the point to search around. - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `province` (string, optional): Name of the estate's province. - `municipality` (string, optional): Name of the estate's municipality. - `sold_or_rented_after` (string (date), optional, nullable): Properties sold/rented since this date (in the format `YYYY-MM-DD`) will be considered as possible comparables. Default value: 9 months ago, counting from today. If `null` is passed, only active properties will be considered. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `business_type` (string, optional): Operation type. **This field is deprecated and will be removed in the next major update.** **Please, use `operation` field instead.** Values: `sale`, `rent`. - `comparables_type` (string, optional): Comparables property type, as returned by the GET /api/v1/references/types endpoint. **This field is deprecated and will be removed in the next major update.** **Please, use `comparables_types` field instead.** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `comparables_types` (string[], required): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking *Note that you can select multiple types only from one property type group.* Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `property_type` (string, optional): Comparables property type, as returned by the GET /api/v1/references/types endpoint. **This field is deprecated and will be removed in the next major update.** **Please, use `comparables_types` field instead.** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `min_price` (integer, optional): The minimum price filter for comparables result. 0–2147483647; default 0. - `max_price` (integer, optional): The maximum price filter for comparables result. 1–2147483647. - `condition` (string, optional): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `bedrooms` (integer, optional): Number of bedrooms (cannot be used together with `rooms`). 0–15000. - `rooms` (integer, optional): Number of rooms (cannot be used together with `bedrooms`). 0–15000. - `bathrooms` (integer, optional): Number of bathrooms. 1–15000. - `construction_year` (integer, optional): Desired construction year. 1–3000. - `total_area` (integer, optional): Desired total area, square meters. This field is required for `hotel`, `industrial`, `office`, `other_commercial`, `restaurant`, `retail`, `warehouse`, `werkstatt` property types if `target_point.cadastral_reference` is not provided. 5–10000000. - `plot_area` (integer, optional): Desired plot area, square meters. This field is required for `rural_plot` and `urban_plot` property types if `target_point.cadastral_reference` is not provided. 20–10000000. - `floor` (string, optional): Floor type. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`. - `floor_number` (integer[], optional): Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250. -250–250. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (object, optional): Property characteristics. - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `nice_to_have` (string[], optional): Include properties that have any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `energy_certificate` (string, optional): Energy certificate. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_certificates` (string[], optional): List of energy certificates. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_ratings` (string[], optional): List of energy ratings. Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `days_on_market_from` (integer, optional): Minimum days on market value. 1–10000. - `days_on_market_to` (integer, optional): Maximum days on market value. 1–10000. - `with_agencies` (string[], optional): Return properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/comparables/search" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "comparables_count": 20, "location_boundary": { "circle": { "distance": 3.5, "target_point": { "coordinates": { "latitude": 38.74, "longitude": -9.17 } } } }, "sold_or_rented_after": "2020-06-01", "days_on_market_from": 10, "days_on_market_to": 1000, "operation": "sale", "comparables_types": [ "apartment" ], "bedrooms": 2, "construction_year": 2010, "total_area": 125, "condition": "used", "floors": [ "middle", "top" ], "floor_number": [ 3, 5 ], "views": [ "city", "landscape" ], "directions": [ "west", "north" ], "characteristics": { "must_have": [ "balcony", "elevator" ], "nice_to_have": [ "garage", "parking", "storage" ] }, "energy_ratings": [ "A", "B", "C" ] }' ``` ## Responses ### 200 OK Type: `object`. - `results` (object[], required): Array of found comparable properties. - `property_id` (integer, required): ID of the property. - `property_url` (string, optional, nullable): URL of the property in the CASAFARI website. - `primary_listing_id` (integer, required): Primary listing (ad) ID of the property which is defined after the matching into property. - `type` (string, required): Property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Property type group, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `house`, `investment`, `plot`, `other`. - `coordinates` (object, required): Property coordinates. - `latitude` (number, required): Latitude. - `longitude` (number, required): Longitude. - `location` (object, required): Information about property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required): Information about all the parent locations (including property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `address` (string, required): Property address. - `zip_code` (string, required): The location zip code. - `distance` (number, optional, nullable): Distance in kilometers from target point to the property. Not calculated for search by polygon. - `construction_year` (integer, required): Construction year. - `total_area` (integer, required): Total area. - `living_area` (integer, required): Living area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `rooms` (integer, required): Number of rooms. - `bathrooms` (integer, required): Number of bathrooms. - `floor_number` (integer, required): Exact floor number. Negative values indicate underground floors (e.g. basements). - `condition` (string, required): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `features` (object, required): Property features, as returned by the GET /api/v1/references/features endpoint. - `floor` (string, required): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, required): Property view orientation. Values: `exterior`, `interior`. - `view` (string, required): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], required): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, required): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], required): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], required): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `operations` (string[], required): Operation types for which property is available. Values: `sale`, `rent`. - `sale_status` (string, required): Sale status. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price` (integer, required): Sale price, in the currency of the listings (specified by the `sale_currency` field). - `sale_price_base` (integer, required): Sale price, in Euros. - `sale_price_per_sqm` (number, required): Sale price per square meter, in the currency of the listings (specified by the `sale_currency` field). - `sale_price_per_sqm_base` (number, required): Sale price per square meter, in Euros. - `rent_status` (string, required): Rent status. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `rent_currency` (string, required): Rent price currency code. - `rent_price` (integer, required): Rent price, in the currency of the listings (specified by the `rent_currency` field). - `rent_price_base` (integer, required): Rent price, in Euros. - `rent_price_per_sqm` (number, required): Rent price per square meter, in the currency of the listings (specified by the `rent_currency` field). - `rent_price_per_sqm_base` (number, required): Rent price per square meter, in Euros. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `fortnight`, `month`, `year`, `none`. - `title` (string, required): Property title. - `description` (string, required): Property description. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `pictures` (string[], optional): List of the original picture image URLs. - `gross_yield` (number, required): Gross yield in percentage. - `sold_at` (string (date), required): Date when the property was sold. - `rented_at` (string (date), required): Date when the property was rented. - `total_sale_price_change` (number, required): Total sale price change in percents. - `total_rent_price_change` (number, required): Total rent price change in percents. - `last_sale_price_reduction` (number, required): Last sale price reduction in percents. - `last_rent_price_reduction` (number, required): Last rent price reduction in percents. - `sale_price_last_change` (object, required): Information about the last change of sale price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `rent_price_last_change` (object, required): Information about the last change of rent price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `sale_time_on_market` (object, optional, nullable): Information about the property last activity on the sales market. - `rent_time_on_market` (object, optional, nullable): Information about the property last activity on the rental market. - `sale_active_listings_count` (integer, optional): Number of active listings for this property on the sales market. - `rent_active_listings_count` (integer, optional): Number of active listings for this property on the rental market. - `similarity_score` (number, optional): Similarity score of the property. Value between 0 and 1. Indicates how property parameters are close to the requested ones. - `listing_urls` (string (uri)[], required): Listing urls of the comparable. - `is_dvf` (boolean, optional): Whether the property taken from DVF. default false. - `is_outlier` (boolean, optional): Whether the property is considered an outlier based on its price. default false. - `is_private_property` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `energy_certificate` (string, optional): Energy certificate classification that attests to the energy efficiency of a property. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** default "". - `energy_rating` (string, optional): Energy rating that attests to the energy efficiency of a property. default "". - `statistics` (object, required): Statistics information for the found comparables (for `operation` defined in the request). - `average_price` (integer, required): Average price. - `average_price_per_sqm` (number, required): Average price per square meter. - `average_time_on_the_market` (integer, required): Average number of days on the market. - `average_listings_per_property` (number, required): Average number of listings per property. - `sold_or_rented_in_last_six_months` (integer, required): Number of properties that were sold or rented during the last 6 months in the requested location. - `estimated_prices` (object, required): Estimated prices calculated based on the found comparables (for `operation` defined in the request). - `fast_sell_price` (integer, required): Fast sell price. - `fair_market_price` (integer, required): Fair market price. - `out_of_market_price` (integer, required): Out of market price. - `fast_sell_price_per_sqm` (number, required): Fast sell price per square meter. - `fair_market_price_per_sqm` (number, required): Fair market price per square meter. - `out_of_market_price_per_sqm` (number, required): Out of market price per square meter. - `casafari_link` (string (uri), required): Link to Comparative Market Analysis page. pattern `^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*)?@)?(?:(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)(?:\.(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)){3}|\[[0-9a-f:.]+\]|([a-z¡-￿0-9](?:[a-z¡-￿0-9-]{0,61}[a-z¡-￿0-9])?(?:\.(?!-)[a-z¡-￿0-9-]{1,63}(? # Initialize an AI Builder session (v2) `POST https://api.casafari.com/api/v2/comparables/ai-builder` [Comparables & Valuation](/docs/comparables-valuation) · [REST API](/docs/rest/comparables-valuation). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#comparables-valuation). ## Description Initializes an AI Builder session from a saved CMA (valuation) and returns the generated report ID along with the URL of the AI Builder session. ## Request body Content type `application/json`. Optional. Type: `object`. - `valuation_id` (integer, required): ID of the saved CMA to build the session from. - `agent` (object, optional, nullable): Agent data to display in the Builder. - `first_name` (string, required): First name of the agent displayed in the Builder. - `last_name` (string, optional, nullable): Last name of the agent displayed in the Builder. - `shop_name` (string, optional, nullable): Name of the agency or brokerage displayed alongside the agent information. - `photo_url` (string (uri), optional, nullable): URL to the profile picture of the agent. pattern `^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*)?@)?(?:(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)(?:\.(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)){3}|\[[0-9a-f:.]+\]|([a-z¡-￿0-9](?:[a-z¡-￿0-9-]{0,61}[a-z¡-￿0-9])?(?:\.(?!-)[a-z¡-￿0-9-]{1,63}(? # Search comparables (v2) `POST https://api.casafari.com/api/v2/comparables/search` [Comparables & Valuation](/docs/comparables-valuation) · [REST API](/docs/rest/comparables-valuation). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) (equivalent). See [MCP and REST compared](/docs/parity#comparables-valuation). ## Description Returns comparable properties by the given parameters. ## Request body Content type `application/json`. Optional. Type: `object`. - `comparables_count` (integer, required): Maximum number of comparable properties in results. 1–50. - `coordinates` (object, optional): Target point coordinates to search around. **This field is deprecated and will be removed in the next major update.** **Please, use `target_point.coordinates` field instead.** - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `target_point` (object, optional): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. **This field is deprecated and will be removed in the next major update.** **Please, use `location_boundary.circle` field instead.** - `coordinates` (object, optional): Target point coordinates to search around. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `address` (string, optional): Address of the property to define the point to search around. - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `province` (string, optional): Name of the estate's province. - `municipality` (string, optional): Name of the estate's municipality. - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to comparable properties. **This field is deprecated and will be removed in the next major update.** **Please, use `location_boundary.circle` field instead.** 0.05–50; default 5. - `location_boundary` (object, required): Location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided. - `polygon` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to the properties. 0.05–50; default 5. - `target_point` (object, required): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. - `coordinates` (object, optional): Target point coordinates to search around. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `address` (string, optional): Address of the property to define the point to search around. - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `province` (string, optional): Name of the estate's province. - `municipality` (string, optional): Name of the estate's municipality. - `sold_or_rented_after` (string (date), optional, nullable): Properties sold/rented since this date (in the format `YYYY-MM-DD`) will be considered as possible comparables. Default value: 9 months ago, counting from today. If `null` is passed, only active properties will be considered. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `business_type` (string, optional): Operation type. **This field is deprecated and will be removed in the next major update.** **Please, use `operation` field instead.** Values: `sale`, `rent`. - `comparables_type` (string, optional): Comparables property type, as returned by the GET /api/v1/references/types endpoint. **This field is deprecated and will be removed in the next major update.** **Please, use `comparables_types` field instead.** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `comparables_types` (string[], required): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, apartment, dachgeschosswohnung, erdgeschosswohnung, duplex, etagenwohnung, studio **house:** einfamilienhaus, family_house (DEPRECATED), reihenmittelhaus, house, villa, country_house, zweifamilienhaus, landwirtschaftliche_betriebe, palace, bungalow, townhouse, reihenhaus, chalet, country_estate, reihenendhaus **room:** room **building:** mix_use_building, office_building, apartment_building **investment:** other_commercial, warehouse, office, retail, hotel, werkstatt, industrial, restaurant **plot:** urban_plot, plot (DEPRECATED), rural_plot **other:** garage, other, parking *Note that you can select multiple types only from one property type group.* Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `property_type` (string, optional): Comparables property type, as returned by the GET /api/v1/references/types endpoint. **This field is deprecated and will be removed in the next major update.** **Please, use `comparables_types` field instead.** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `min_price` (integer, optional): The minimum price filter for comparables result. 0–2147483647; default 0. - `max_price` (integer, optional): The maximum price filter for comparables result. 1–2147483647. - `condition` (string, optional): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `bedrooms` (integer, optional): Number of bedrooms (cannot be used together with `rooms`). 0–15000. - `rooms` (integer, optional): Number of rooms (cannot be used together with `bedrooms`). 0–15000. - `bathrooms` (integer, optional): Number of bathrooms. 1–15000. - `construction_year` (integer, optional): Desired construction year. 1–3000. - `total_area` (integer, optional): Desired total area, square meters. This field is required for `hotel`, `industrial`, `office`, `other_commercial`, `restaurant`, `retail`, `warehouse`, `werkstatt` property types if `target_point.cadastral_reference` is not provided. 5–10000000. - `plot_area` (integer, optional): Desired plot area, square meters. This field is required for `rural_plot` and `urban_plot` property types if `target_point.cadastral_reference` is not provided. 20–10000000. - `floor` (string, optional): Floor type. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`. - `floor_number` (integer[], optional): Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250. -250–250. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (object, optional): Property characteristics. - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `nice_to_have` (string[], optional): Include properties that have any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `energy_certificate` (string, optional): Energy certificate. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_certificates` (string[], optional): List of energy certificates. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_ratings` (string[], optional): List of energy ratings. Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `days_on_market_from` (integer, optional): Minimum days on market value. 1–10000. - `days_on_market_to` (integer, optional): Maximum days on market value. 1–10000. - `with_agencies` (string[], optional): Return properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v2/comparables/search" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "comparables_count": 20, "location_boundary": { "circle": { "distance": 10, "target_point": { "coordinates": { "latitude": 48.8727989, "longitude": 2.3025047 } } } }, "sold_or_rented_after": "2020-08-01", "days_on_market_from": 10, "days_on_market_to": 1000, "operation": "sale", "comparables_types": [ "apartment" ], "bedrooms": 2, "construction_year": 2010, "total_area": 125, "condition": "used", "floors": [ "top" ], "views": [ "city" ], "directions": [ "west" ], "characteristics": { "must_have": [ "balcony", "garage", "parking" ], "nice_to_have": [ "storage", "terrace", "furniture" ], "exclude": [ "swimming_pool" ] }, "energy_ratings": [ "A", "B", "C" ] }' ``` ## Responses ### 200 OK Type: `object`. - `results` (object[], required): Array of found comparable properties. - `property_id` (integer, required): ID of the property. - `property_url` (string, optional, nullable): URL of the property in the CASAFARI website. - `primary_listing_id` (integer, required): Primary listing (ad) ID of the property which is defined after the matching into property. - `type` (string, required): Property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Property type group, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `house`, `investment`, `plot`, `other`. - `coordinates` (object, required): Property coordinates. - `latitude` (number, required): Latitude. - `longitude` (number, required): Longitude. - `location` (object, required): Information about property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required): Information about all the parent locations (including property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `address` (string, required): Property address. - `zip_code` (string, required): The location zip code. - `distance` (number, optional, nullable): Distance in kilometers from target point to the property. Not calculated for search by polygon. - `construction_year` (integer, required): Construction year. - `total_area` (integer, required): Total area. - `living_area` (integer, required): Living area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `rooms` (integer, required): Number of rooms. - `bathrooms` (integer, required): Number of bathrooms. - `floor_number` (integer, required): Exact floor number. Negative values indicate underground floors (e.g. basements). - `condition` (string, required): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `features` (object, required): Property features, as returned by the GET /api/v1/references/features endpoint. - `floor` (string, required): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, required): Property view orientation. Values: `exterior`, `interior`. - `view` (string, required): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], required): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, required): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], required): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], required): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `operations` (string[], required): Operation types for which property is available. Values: `sale`, `rent`. - `sale_status` (string, required): Sale status. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price` (integer, required): Sale price, in the currency of the listings (specified by the `sale_currency` field). - `sale_price_base` (integer, required): Sale price, in Euros. - `sale_price_per_sqm` (number, required): Sale price per square meter, in the currency of the listings (specified by the `sale_currency` field). - `sale_price_per_sqm_base` (number, required): Sale price per square meter, in Euros. - `rent_status` (string, required): Rent status. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `rent_currency` (string, required): Rent price currency code. - `rent_price` (integer, required): Rent price, in the currency of the listings (specified by the `rent_currency` field). - `rent_price_base` (integer, required): Rent price, in Euros. - `rent_price_per_sqm` (number, required): Rent price per square meter, in the currency of the listings (specified by the `rent_currency` field). - `rent_price_per_sqm_base` (number, required): Rent price per square meter, in Euros. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `fortnight`, `month`, `year`, `none`. - `title` (string, required): Property title. - `description` (string, required): Property description. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `pictures` (string[], optional): List of the original picture image URLs. - `gross_yield` (number, required): Gross yield in percentage. - `sold_at` (string (date), required): Date when the property was sold. - `rented_at` (string (date), required): Date when the property was rented. - `total_sale_price_change` (number, required): Total sale price change in percents. - `total_rent_price_change` (number, required): Total rent price change in percents. - `last_sale_price_reduction` (number, required): Last sale price reduction in percents. - `last_rent_price_reduction` (number, required): Last rent price reduction in percents. - `sale_price_last_change` (object, required): Information about the last change of sale price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `rent_price_last_change` (object, required): Information about the last change of rent price. - `change_date` (string (date), required): Date of the change. - `old_value` (integer, required): Value before change. - `new_value` (integer, required): Value after change. - `sale_time_on_market` (object, optional, nullable): Information about the property last activity on the sales market. - `rent_time_on_market` (object, optional, nullable): Information about the property last activity on the rental market. - `sale_active_listings_count` (integer, optional): Number of active listings for this property on the sales market. - `rent_active_listings_count` (integer, optional): Number of active listings for this property on the rental market. - `similarity_score` (number, optional): Similarity score of the property. Value between 0 and 1. Indicates how property parameters are close to the requested ones. - `listing_urls` (string (uri)[], required): Listing urls of the comparable. - `is_outlier` (boolean, optional): Whether the property is considered an outlier based on its price. default false. - `is_private_property` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `energy_certificate` (string, optional): Energy certificate classification that attests to the energy efficiency of a property. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** default "". - `energy_rating` (string, optional): Energy rating that attests to the energy efficiency of a property. default "". - `ref_numbers` (string[], required): List of reference numbers from listings. - `dvf_results` (object[], optional): Array of found DVF data (Request for geolocated property values). - `dvf_reference` (integer, required): Reference ID of the DVF property. - `coordinates` (object, required): DVF property coordinates. - `lat` (number, required): Latitude. - `lon` (number, required): Longitude. - `distance` (number, optional): Distance in kilometers from target point to DVF the property. Not calculated for search by polygon. - `type` (string, required): Property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Property type group, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `house`, `investment`, `plot`, `other`. - `sale_price` (integer, required): Sale price, in the original currency. - `sale_price_base` (integer, required): Sale price, in Euros. - `sale_price_psqm` (number, optional): Sale price per square meter, in the original currency. default 0. - `sale_price_psqm_base` (number, optional): Sale price per square meter, in Euros. default 0. - `sold_at` (string, optional, nullable): Date when the property was sold. - `total_area` (integer, required): Total area. - `plot_area` (integer, required): Plot area. - `rooms` (integer, required): Number of rooms. - `bedrooms` (integer, required): Number of bedrooms. - `address` (string, required): Property address. - `location` (object, required): Information about DVF property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required): Information about all the parent locations (including DVF property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `sale_status` (string, optional): Sale status. Values: `active`, `reserved`, `hold`, `sold`, `none`. default "sold". - `thumbnails` (string[], optional): List of the thumbnail image URLs. default []. - `transactional_data` (object[], optional, nullable) - `id` (integer, required) - `reference` (string, required) - `cadastral_reference` (string, required) - `rooms` (integer, required) - `bedrooms` (integer, required) - `bathrooms` (integer, required) - `coordinates` (object, required) - `lat` (number, required): Latitude. - `lon` (number, required): Longitude. - `total_area` (number, required) - `plot_area` (number, required) - `address` (string, required) - `source_typology` (string, required) - `source_annexes` (string, required): Additional raw source data (if present), describing annexes (such as parking, storage, etc) included in the transaction price. - `type` (string, required) Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required) - `sold_at` (string (date), required) - `currency` (string, required): Price currency code. - `price` (number, required) - `price_per_sqm` (number, required) - `with_mortgage` (boolean, required): Flag indicating whether the transaction was financed with a mortgage. - `distance` (number, optional, nullable): Distance in kilometers from target point to the property. Not calculated for search by polygon. - `location_id` (integer, required) - `construction_year` (integer, required) - `location` (object, required) - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required) - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `image_url` (string (uri), required) pattern `^(?:[a-z0-9.+-]*)://(?:[^\s:@/]+(?::[^\s:@/]*)?@)?(?:(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)(?:\.(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)){3}|\[[0-9a-f:.]+\]|([a-z¡-￿0-9](?:[a-z¡-￿0-9-]{0,61}[a-z¡-￿0-9])?(?:\.(?!-)[a-z¡-￿0-9-]{1,63}(? # Search estimated prices (v1) `POST https://api.casafari.com/api/v1/valuation/comparables-prices` [Comparables & Valuation](/docs/comparables-valuation) · [REST API](/docs/rest/comparables-valuation). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) (related). See [MCP and REST compared](/docs/parity#comparables-valuation). ## Description Returns estimated prices by the given parameters. ## Request body Content type `application/json`. Optional. Type: `object`. - `comparables_count` (integer, required): Maximum number of comparable properties in results. 1–50. - `target_point` (object, optional): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. **This field is deprecated and will be removed in the next major update.** **Please, use `location_boundary.circle` field instead.** - `coordinates` (object, optional): Target point coordinates to search around. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `address` (string, optional): Address of the property to define the point to search around. - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `province` (string, optional): Name of the estate's province. - `municipality` (string, optional): Name of the estate's municipality. - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to comparable properties. **This field is deprecated and will be removed in the next major update.** **Please, use `location_boundary.circle` field instead.** 0.05–50; default 5. - `location_boundary` (object, required): Location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided. - `polygon` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to the properties. 0.05–50; default 5. - `target_point` (object, required): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. - `coordinates` (object, optional): Target point coordinates to search around. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `address` (string, optional): Address of the property to define the point to search around. - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `province` (string, optional): Name of the estate's province. - `municipality` (string, optional): Name of the estate's municipality. - `sold_or_rented_after` (string (date), optional, nullable): Properties sold/rented since this date (in the format `YYYY-MM-DD`) will be considered as possible comparables. Default value: 9 months ago, counting from today. If `null` is passed, only active properties will be considered. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `comparables_type` (string, optional): Comparables property type, as returned by the GET /api/v1/references/types endpoint. **This field is deprecated and will be removed in the next major update.** **Please, use `comparables_types` field instead.** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `comparables_types` (string[], required): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking *Note that you can select multiple types only from one property type group.* Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `min_price` (integer, optional): The minimum price filter for comparables result. 0–2147483647; default 0. - `max_price` (integer, optional): The maximum price filter for comparables result. 1–2147483647. - `condition` (string, optional): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `bedrooms` (integer, optional): Number of bedrooms (cannot be used together with `rooms`). 0–15000. - `rooms` (integer, optional): Number of rooms (cannot be used together with `bedrooms`). 0–15000. - `bathrooms` (integer, optional): Number of bathrooms. 1–15000. - `construction_year` (integer, optional): Desired construction year. 1–3000. - `total_area` (integer, optional): Desired total area, square meters. This field is required for `hotel`, `industrial`, `office`, `other_commercial`, `restaurant`, `retail`, `warehouse`, `werkstatt` property types if `target_point.cadastral_reference` is not provided. 5–10000000. - `plot_area` (integer, optional): Desired plot area, square meters. This field is required for `rural_plot` and `urban_plot` property types if `target_point.cadastral_reference` is not provided. 20–10000000. - `floors` (string[], optional): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`. - `floor_number` (integer[], optional): Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250. -250–250. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `views` (string[], optional): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `directions` (string[], optional): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (object, optional): Property characteristics. - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `nice_to_have` (string[], optional): Include properties that have any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `energy_certificate` (string, optional): Energy certificate. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_certificates` (string[], optional): List of energy certificates. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `energy_ratings` (string[], optional): List of energy ratings. Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. - `days_on_market_from` (integer, optional): Minimum days on market value. 1–10000. - `days_on_market_to` (integer, optional): Maximum days on market value. 1–10000. - `with_agencies` (string[], optional): Return properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/valuation/comparables-prices" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "comparables_count": 20, "location_boundary": { "circle": { "distance": 3.5, "target_point": { "coordinates": { "latitude": 38.74, "longitude": -9.17 } } } }, "sold_or_rented_after": "2020-06-01", "days_on_market_from": 10, "days_on_market_to": 1000, "operation": "sale", "comparables_types": [ "apartment" ], "bedrooms": 2, "construction_year": 2010, "total_area": 125, "condition": "used", "floors": [ "middle", "top" ], "floor_number": [ 3, 5 ], "views": [ "city", "landscape" ], "directions": [ "west", "north" ], "characteristics": { "must_have": [ "balcony", "elevator" ], "nice_to_have": [ "garage", "parking", "storage" ] }, "energy_ratings": [ "A", "B", "C" ] }' ``` ## Responses ### 200 OK Type: `object`. - `statistics` (object, required): Statistics information for the found comparables (for `operation` defined in the request). - `average_price` (integer, required): Average price. - `average_price_per_sqm` (number, required): Average price per square meter. - `average_time_on_the_market` (integer, required): Average number of days on the market. - `average_listings_per_property` (number, required): Average number of listings per property. - `sold_or_rented_in_last_six_months` (integer, required): Number of properties that were sold or rented during the last 6 months in the requested location. - `estimated_prices` (object, required): Estimated prices calculated based on the found comparables (for `operation` defined in the request). - `fast_sell_price` (integer, required): Fast sell price. - `fair_market_price` (integer, required): Fair market price. - `out_of_market_price` (integer, required): Out of market price. - `fast_sell_price_per_sqm` (number, required): Fast sell price per square meter. - `fair_market_price_per_sqm` (number, required): Fair market price per square meter. - `out_of_market_price_per_sqm` (number, required): Out of market price per square meter. Example from the API description: ```json { "statistics": { "average_price": 767950, "average_price_per_sqm": 6376, "average_time_on_the_market": 169, "average_listings_per_property": 6.2, "sold_or_rented_in_last_six_months": 453 }, "estimated_prices": { "fast_sell_price": 741210, "fair_market_price": 797000, "out_of_market_price": 852790, "fast_sell_price_per_sqm": 5929.68, "fair_market_price_per_sqm": 6376, "out_of_market_price_per_sqm": 6822.32 } } ``` ### 400 Bad Request Type: `object`. - `errors` (object, optional): Description of the errors encountered. ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [What does Comparables & Valuation do?](/docs/faq/what-is-comparables-valuation) - [How do I value a home or find comparables with Casafari MCP?](/docs/faq/example-valuation) --- # Area Insights Insights for an area: price, supply and activity over time, distributions by price, bedrooms and time on market, and market analysis. Over MCP also growth and volatility measures and heatmaps by district. 8 MCP tools · 6 REST operations. ## How the MCP server describes itself What `list_servers` returns for this product (the server's own `initialize` instructions): > Server provides functionality to analyze real estate market. ## MCP tools | Tool | Title | What it does | |---|---|---| | [`ma_get_current_datetime`](/docs/area-insights/get_current_datetime) | Get Current Datetime | Returns the current system date and time. | | [`ma_get_time_series_data`](/docs/area-insights/get_time_series_data) | Get Time Series Data | Retrieve time series data for the real estate market. | | [`ma_get_time_series_operations`](/docs/area-insights/get_time_series_operations) | Get Time Series Operations | Performs analytical time-series operations (e.g., mean, delta_pct, CAGR, cv, std, etc.) for a single geographic or analytical segment using real-estate… | | [`ma_get_price_distribution`](/docs/area-insights/get_price_distribution) | Get Price Distribution | Returns a distribution of property prices based on the provided filters. | | [`ma_get_bedrooms_distribution`](/docs/area-insights/get_bedrooms_distribution) | Get Bedrooms Distribution | Returns a distribution of properties grouped by the number of bedrooms. | | [`ma_get_time_on_market_distribution`](/docs/area-insights/get_time_on_market_distribution) | Get Time on Market Distribution | Returns a distribution of properties by their time on the market, grouped by price intervals. | | [`ma_get_heatmap`](/docs/area-insights/get_heatmap) | Get Heatmap | Generate an area insights heatmap showing property distribution and price dynamics across geographic areas. | | [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead) | Get Location Typeahead | Retrieve typeahead suggestions for a given location name. | ## REST API 6 operations in the public OpenAPI description, all under `https://api.casafari.com` with a bearer token ([how to get one](/docs/rest#get-a-token)). The same list with more detail: [Area Insights REST API](/docs/rest/area-insights). ### Time Series - [`POST /market-analytics-api/time-series`](/docs/rest/area-insights/time-series): Time Series. Returns time series data for the real estate market. ### Distributions Paths under `/market-analytics-api/distributions`. - [`POST /market-analytics-api/distributions/bedrooms`](/docs/rest/area-insights/bedrooms-distribution): Bedrooms Distribution. Returns property distribution based on the number of bedrooms. - [`POST /market-analytics-api/distributions/prices`](/docs/rest/area-insights/price-distribution): Price Distribution. Returns the number of properties distributed across price ranges. - [`POST /market-analytics-api/distributions/properties`](/docs/rest/area-insights/properties-distribution): Properties Distribution. Returns the properties lightweight data sample and distribution quartiles. - [`POST /market-analytics-api/distributions/time-on-market`](/docs/rest/area-insights/time-on-market-distribution): Time On Market Distribution. Returns time on market (days and months) distribution by price ranges. ### Analysis - [`POST /market-analytics-api/analysis`](/docs/rest/area-insights/analysis): Analysis. Market analysis based on the requested property parameters. ## MCP and REST compared Over MCP: 8 tools. Over REST: 6 operations. Available over both. - Equivalent: [`ma_get_time_series_data`](/docs/area-insights/get_time_series_data) and [`POST /market-analytics-api/time-series`](/docs/rest/area-insights/time-series). - Equivalent: [`ma_get_price_distribution`](/docs/area-insights/get_price_distribution) and [`POST /market-analytics-api/distributions/prices`](/docs/rest/area-insights/price-distribution). - Equivalent: [`ma_get_bedrooms_distribution`](/docs/area-insights/get_bedrooms_distribution) and [`POST /market-analytics-api/distributions/bedrooms`](/docs/rest/area-insights/bedrooms-distribution). - Equivalent: [`ma_get_time_on_market_distribution`](/docs/area-insights/get_time_on_market_distribution) and [`POST /market-analytics-api/distributions/time-on-market`](/docs/rest/area-insights/time-on-market-distribution). - Related: [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead) and [`POST /api/v1/references/locations/typeahead`](/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1). Only over MCP: [`ma_get_current_datetime`](/docs/area-insights/get_current_datetime), [`ma_get_time_series_operations`](/docs/area-insights/get_time_series_operations), [`ma_get_heatmap`](/docs/area-insights/get_heatmap). Only over REST: [`POST /market-analytics-api/distributions/properties`](/docs/rest/area-insights/properties-distribution), [`POST /market-analytics-api/analysis`](/docs/rest/area-insights/analysis). Details: [MCP and REST compared](/docs/parity#area-insights). ## Ask your assistant > How has the asking price per m² of flats in Valencia moved over the last three years? ## Questions about this - [What is Casafari MCP?](/docs/faq/what-is-casafari-mcp) - [Does Casafari cover Spain and Portugal?](/docs/faq/coverage-spain-portugal) - [Which products does Casafari MCP offer, and how many tools are there?](/docs/faq/which-products) - [What is Area Insights?](/docs/faq/what-is-area-insights) - [How do I analyse how prices in an area have moved over time?](/docs/faq/example-price-trend) --- # `ma_get_current_datetime` Get Current Datetime. Product: [Area Insights](/docs/area-insights). Annotations: Read-only. Call it as `ma_get_current_datetime` on `https://mcp.casafari.com/` (the backend's own name is `get_current_datetime`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#area-insights). ## Description Returns the current system date and time. #### Returns ```json { "current_datetime": "2025-10-06T12:45:00.000000" } ``` | Key | Type | Description | |------|------|-------------| | `current_datetime` | `str` | Local system date and time in ISO format. | #### Example Usage ```python result = await call_tool("get_current_datetime") print(result["current_datetime"]) ``` ## Parameters No parameters. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ma_get_current_datetime", "arguments": {} } } ``` ## Questions about this - [Which tools exist only over MCP, and which operations only over REST?](/docs/faq/mcp-only-and-rest-only) - [Can I build a market report with Casafari MCP?](/docs/faq/example-market-report) --- # `ma_get_time_series_data` Get Time Series Data. Product: [Area Insights](/docs/area-insights). Annotations: Read-only. Call it as `ma_get_time_series_data` on `https://mcp.casafari.com/` (the backend's own name is `get_time_series_data`). Over REST: [`POST /market-analytics-api/time-series`](/docs/rest/area-insights/time-series) (equivalent). [MCP and REST compared](/docs/parity#area-insights). ## Description Retrieve **time series data** for the real estate market. Each data point in the series represents an aggregated metric (`data_point`) for a specific period, defined by the chosen `date_interval` and property filters. This tool provides consistent, interval-based historical data for various real estate indicators. #### Use Cases Retrieve historical market information, such as: - Average property prices. - Average price per square meter. - Number of properties sold or rented over time. - Number of newly listed properties. - Number of properties available on the market. - Number of price increases or decreases for listings. #### Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPTimeSeriesRequestSchema` | Yes | Defines filters, time interval, and data metric (`data_point`) for aggregation. | ##### Filter highlights - `data_point`: defines **which metric** to retrieve (e.g. price, listings, sold count, etc.). - `date_interval`: defines **the frequency** of data points in the response (`WEEK`, `MONTH`, `QUARTER`, `YEAR`). - `custom_location_boundary`: spatial boundary (circle or list of location IDs). - `type_group`: group of property types to analyze. - `business_type`: `"sale"` or `"rent"`. - `exclude_outliers`: optionally exclude statistical outliers from the results. - optional property filters: price range, area, bedrooms, bathrooms, etc. #### Important Notes - If you need to compare different property types, send **separate requests** for each type group. - For broader analyses, prefer using `AVERAGE_PRICE_PER_SQM` over total price. - You can reuse the same filters with different `data_point` values to analyze multiple aspects of the market (e.g. compare new listings vs. sold properties). - Use the `exclude_outliers` flag to remove extreme values and improve analytical accuracy. #### Returns ```json [ { "date_start": "2024-01-01", "value": 4350.5 } ] ## Parameters - `request_data` (object, required): One analytical segment defining a specific filter or location boundary. Alias (name) is generated automatically on the server based on the location definition. - `type_group` (string, required): Estate type group. Values: `apartment`, `house`. - `business_type` (string, required): Operation type for which the property is available. Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true. - `alias` (string, required): Alias (name) of the segment that was analyzed. - `custom_location_boundary` (object, required): Geographic boundary definition (circle, or location ID list). - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `data_point` (string, required): Specifies the type of real estate data to retrieve for a given period. Values: `avg_price`, `avg_price_psqm`, `available_on_market`, `new`, `sold_or_rented`, `price_up`, `price_down`. - `date_interval` (string, required): Defines the time interval for aggregating data points. Determines the frequency at which data is reported in the response. Values: `week`, `month`, `quarter`, `year`. - `date_range` (object, required) - `min` (string (date), required): Start date in the format `YYYY-MM-DD`. If the specified date is not Monday - the closest previous Monday will be selected. - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`. If the specified date is not Sunday - the closest previous Sunday will be selected. ## Response The result is returned as `result`: - `date_start` (string (date), required): The starting date of the period associated with the passed `date_interval` field value. The format follows `YYYY-MM-DD`. - `value` (number, required): The numerical value corresponding to the passed `data_point` field value for the given `date_start`. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ma_get_time_series_data", "arguments": { "request_data": { "type_group": "apartment", "business_type": "sale", "alias": "…", "custom_location_boundary": { "location_ids": [ 1 ] }, "data_point": "avg_price", "date_interval": "week", "date_range": { "min": "2025-01-01" } } } } } ``` ## Questions about this - [What is Area Insights?](/docs/faq/what-is-area-insights) - [How do I analyse how prices in an area have moved over time?](/docs/faq/example-price-trend) --- # `ma_get_time_series_operations` Get Time Series Operations. Product: [Area Insights](/docs/area-insights). Annotations: Read-only. Call it as `ma_get_time_series_operations` on `https://mcp.casafari.com/` (the backend's own name is `get_time_series_operations`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#area-insights). ## Description Performs analytical **time-series operations** (e.g., `mean`, `delta_pct`, `CAGR`, `cv`, `std`, etc.) for a **single geographic or analytical segment** using real-estate historical data. This tool enables focused analysis of **real estate market dynamics** over time — such as prices, listings, or sales — within one defined location or subset. #### Purpose Designed for analytical scenarios such as: - Tracking how property prices evolve in a specific area. - Measuring growth trends (e.g., CAGR, percentage deltas). - Evaluating volatility using standard deviation or coefficient of variation. - Studying local market activity over a given period. #### Input (`request_data`) Expects an instance of `MCPTimeSeriesOperationsRequestSchema`, which includes: - **`segment`** → a single `MCPTimeSeriesRequestSchema` object defining the geographic or analytical subset. - **`operations`** → list of time-series operations (`TimeSeriesOperationEnum`) to compute. `MCPTimeSeriesRequestSchema` includes: - `custom_location_boundary`: spatial boundary (circle or list of location IDs). - `data_point`: metric to analyze (e.g. `AVERAGE_PRICE_PER_SQM`, `SOLD_COUNT`, `NEW_LISTED_COUNT`). - `date_interval`: aggregation interval (`WEEK`, `MONTH`, `QUARTER`, or `YEAR`). - `date_range`: start and end of the analysis period. - Optional property filters (price, area, rooms, construction year, etc.). - `exclude_outliers`: whether to exclude statistical outliers. > **Analytical consistency rule:** The analytical context (data_point, date_interval, business_type, etc.) must remain consistent within the request. The `segment` may only redefine `custom_location_boundary` and `alias` relative to the base filter. #### Operations Supported operations from `TimeSeriesOperationEnum` include: - `mean` — average value across the time range. - `delta_pct` — percentage change between the first and last data points. - `cagr` — compound annual growth rate. - `std` — standard deviation. - `cv` — coefficient of variation. - (plus others defined in the enum). #### LLM Behavior - On success → returns a **single analytical result** (`MCPTimeSeriesUnitResponseSchema`) containing computed metrics for the requested segment. - On error → raises a `ToolError` with an error message. #### Example Success Response ```json { "alias": "Madrid Center", "date_start": "2020-01-01", "date_end": "2024-01-01", "date_interval": "MONTH", "total_of_data_points": 48, "results": [ {"operation": "mean", "value": 3200.5}, {"operation": "delta_pct", "value": 12.4}, {"operation": "cagr", "value": 0.032} ] } ``` #### Example Error Response ``` ToolError: No data found for the specified segment. ``` #### Example Use Cases - Analyze **average price per m²** in a specific city or district. - Measure **sales growth** over several years. - Evaluate **rental market volatility**. - Assess **seasonal dynamics** of listings or sales activity. #### Summary `get_time_series_operations` retrieves **aggregated real-estate time-series data** for a defined location or segment and computes selected analytical operations. It provides a structured, quantitative summary of market trends and changes for a single region or subset. ## Parameters - `request_data` (object, required): Schema for MCP time-series analytical requests. ### Concept This schema defines *what* to analyze (via `filter`), *where* to analyze (via `segment`), and *which operations* to compute (via `operations`). - The `filter` contains **shared analytical parameters** defining the general query context. - The `segment` represents a **specific analytical subset** (e.g., a district, city, or region), which inherits all values from `filter` but can override a few (e.g., location boundary). This logic ensures a consistent analytical context while allowing a single location-specific override — suitable for focused analytical requests where only one boundary or subset is being analyzed. - `segment` (object, required): Analytical segment representing a boundary or subset of data. Inherits all fields from `filter` but may redefine location-specific ones (such as `custom_location_boundary` or `alias`). - `type_group` (string, required): Estate type group. Values: `apartment`, `house`. - `business_type` (string, required): Operation type for which the property is available. Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true. - `alias` (string, required): Alias (name) of the segment that was analyzed. - `custom_location_boundary` (object, required): Geographic boundary definition (circle, or location ID list). - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `data_point` (string, required): Specifies the type of real estate data to retrieve for a given period. Values: `avg_price`, `avg_price_psqm`, `available_on_market`, `new`, `sold_or_rented`, `price_up`, `price_down`. - `date_interval` (string, required): Defines the time interval for aggregating data points. Determines the frequency at which data is reported in the response. Values: `week`, `month`, `quarter`, `year`. - `date_range` (object, required) - `min` (string (date), required): Start date in the format `YYYY-MM-DD`. If the specified date is not Monday - the closest previous Monday will be selected. - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`. If the specified date is not Sunday - the closest previous Sunday will be selected. - `operations` (string[], optional): List of analytical operations to compute (e.g. `mean`, `cagr`, `delta_pct`). If omitted, a default minimal set is applied. Values: `mean`, `median`, `std`, `var`, `min`, `max`, `sum`, `count`, `delta_abs`, `delta_pct`, `cagr`, `mom_last`, `yoy_last`, `slope_per_period`, `trend_strength`, `cv`, `inc_steps`, `dec_steps`, `flat_steps`, `p10`, `q1`, `p90`, `p95`, `iqr`, `outlier_ratio`, `zscore_max`, `movavg_last_3`, `movavg_last_6`, `movavg_last_12`. ## Response - `alias` (string, required): Alias (name) of the segment that was analyzed. - `date_start` (string (date), required): Start date of the analyzed period. - `date_end` (string (date), required): End date of the analyzed period. - `date_interval` (string, required): Frequency of the analyzed period. Values: `week`, `month`, `quarter`, `year`. - `total_of_data_points` (integer, required): Number of data points included in the analyzed period. - `results` (object[], required): List of computed results for each analytical operation. - `operation` (string, required): Operation type applied to the time series (e.g., mean, cagr, delta_pct, cv). Values: `mean`, `median`, `std`, `var`, `min`, `max`, `sum`, `count`, `delta_abs`, `delta_pct`, `cagr`, `mom_last`, `yoy_last`, `slope_per_period`, `trend_strength`, `cv`, `inc_steps`, `dec_steps`, `flat_steps`, `p10`, `q1`, `p90`, `p95`, `iqr`, `outlier_ratio`, `zscore_max`, `movavg_last_3`, `movavg_last_6`, `movavg_last_12`. - `value` (number, required): Computed numeric value. None if insufficient data for the operation. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ma_get_time_series_operations", "arguments": { "request_data": { "segment": { "type_group": "apartment", "business_type": "sale", "alias": "…", "custom_location_boundary": { "location_ids": [ 1 ] }, "data_point": "avg_price", "date_interval": "week", "date_range": { "min": "2025-01-01" } } } } } } ``` ## Questions about this - [What is Area Insights?](/docs/faq/what-is-area-insights) - [Which tools exist only over MCP, and which operations only over REST?](/docs/faq/mcp-only-and-rest-only) - [How do I analyse how prices in an area have moved over time?](/docs/faq/example-price-trend) --- # `ma_get_price_distribution` Get Price Distribution. Product: [Area Insights](/docs/area-insights). Annotations: Read-only. Call it as `ma_get_price_distribution` on `https://mcp.casafari.com/` (the backend's own name is `get_price_distribution`). Over REST: [`POST /market-analytics-api/distributions/prices`](/docs/rest/area-insights/price-distribution) (equivalent). [MCP and REST compared](/docs/parity#area-insights). ## Description Returns a **distribution of property prices** based on the provided filters. Each record represents a price interval and the number of properties within that interval. #### Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPPriceDistributionRequestSchema` | Yes | Configuration for price distribution filtering. | ##### Filter highlights - `type_group`: group of estate types (e.g., apartment, house) - `business_type`: `"sale"` or `"rent"` - `price_range`: numeric price range filter - `exclude_outliers`: optional flag to exclude statistical outliers #### Returns ```json [ { "lower_bound": 100000, "upper_bound": 150000, "properties_count": 42, "is_mean": false } ] ``` | Field | Type | Description | |--------|------|-------------| | `lower_bound` | `int` | Lower price boundary | | `upper_bound` | `int` | Upper price boundary | | `properties_count` | `int` | Number of properties in the range | | `is_mean` | `bool` | Indicates whether the range includes the mean price | #### Example Request ```json { "custom_location_boundary": { "circle": { "target_point": {"latitude": 48.8566, "longitude": 2.3522}, "distance": 10000 } }, "type_group": "apartment", "business_type": "sale", "price_range": {"min": 100000, "max": 500000}, "exclude_outliers": true } ``` ## Parameters - `request_data` (object, required) - `type_group` (string, required): Estate type group. Values: `apartment`, `house`. - `business_type` (string, required): Operation type for which the property is available. Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true. - `custom_location_boundary` (object, required) - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. ## Response The result is returned as `result`: - `lower_bound` (integer, required): The lower price bound of the distribution unit. - `upper_bound` (integer, required): The upper price bound of the distribution unit. - `properties_count` (integer, required): The number of properties that participated in the distribution. - `is_mean` (boolean, required): Indicates whether the mean value is within this distribution unit. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ma_get_price_distribution", "arguments": { "request_data": { "type_group": "apartment", "business_type": "sale", "custom_location_boundary": { "location_ids": [ 1 ] } } } } } ``` ## Questions about this - [What is Area Insights?](/docs/faq/what-is-area-insights) - [How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap) --- # `ma_get_bedrooms_distribution` Get Bedrooms Distribution. Product: [Area Insights](/docs/area-insights). Annotations: Read-only. Call it as `ma_get_bedrooms_distribution` on `https://mcp.casafari.com/` (the backend's own name is `get_bedrooms_distribution`). Over REST: [`POST /market-analytics-api/distributions/bedrooms`](/docs/rest/area-insights/bedrooms-distribution) (equivalent). [MCP and REST compared](/docs/parity#area-insights). ## Description Returns a **distribution of properties grouped by the number of bedrooms**. Each record includes total listings count, average price, and average price per square meter. #### Business Context Useful for analyzing pricing differences and market concentration based on bedroom count — ideal for residential market segmentation. #### Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPBedroomsDistributionRequestSchema` | Yes | Filter configuration for bedroom-based distribution. | ##### Filter highlights - `type_group`: property type group (e.g., apartment, house) - `business_type`: `"sale"` or `"rent"` - `custom_location_boundary`: geographical boundary filter - `bedrooms_range`: range of bedroom counts - `exclude_outliers`: optional flag to remove statistical outliers #### Returns ```json [ { "bedrooms": "2", "properties_count": 324, "average_price": 245000.0, "average_price_per_sqm": 5200.0 } ] ``` | Field | Type | Description | |--------|------|-------------| | `bedrooms` | `str` | Bedroom count label | | `properties_count` | `int` | Number of properties | | `average_price` | `float` | Average property price | | `average_price_per_sqm` | `float` | Average price per square meter | #### Example Request ```json { "custom_location_boundary": { "circle": { "target_point": {"latitude": 48.8566, "longitude": 2.3522}, "distance": 10000 } }, "type_group": "apartment", "business_type": "sale", "bedrooms_range": {"min": 1, "max": 4}, "exclude_outliers": true } ``` ## Parameters - `request_data` (object, required) - `type_group` (string, required): Estate type group. Values: `apartment`, `house`. - `business_type` (string, required): Operation type for which the property is available. Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–10. - `max` (integer, optional, nullable) 0–10. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true. - `custom_location_boundary` (object, required) - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. ## Response The result is returned as `result`: - `bedrooms` (string, required): The number of bedrooms in the properties that participated in the distribution. - `properties_count` (integer, required): The number of properties that participated in the distribution. - `average_price` (number, required): Average price of properties with a specific number of bedrooms. - `average_price_per_sqm` (number, required): Average price per square meter of properties with a specific number of bedrooms. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ma_get_bedrooms_distribution", "arguments": { "request_data": { "type_group": "apartment", "business_type": "sale", "custom_location_boundary": { "location_ids": [ 1 ] } } } } } ``` ## Questions about this - [What is Area Insights?](/docs/faq/what-is-area-insights) - [How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap) --- # `ma_get_time_on_market_distribution` Get Time on Market Distribution. Product: [Area Insights](/docs/area-insights). Annotations: Read-only. Call it as `ma_get_time_on_market_distribution` on `https://mcp.casafari.com/` (the backend's own name is `get_time_on_market_distribution`). Over REST: [`POST /market-analytics-api/distributions/time-on-market`](/docs/rest/area-insights/time-on-market-distribution) (equivalent). [MCP and REST compared](/docs/parity#area-insights). ## Description Returns a **distribution of properties by their time on the market**, grouped by price intervals. Each record contains average listing duration and property count. #### Business Context Useful for evaluating **market liquidity** and **demand efficiency**, identifying price segments where listings sell faster or remain longer. #### Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPTimeOnMarketDistributionRequestSchema` | Yes | Defines filters for listing duration analysis. | ##### Filter highlights - `type_group`: property type group - `business_type`: `"sale"` or `"rent"` - `price_range`: price interval boundaries - `date_range`: date range for the active listing period - `exclude_outliers`: optional flag to exclude statistical outliers #### Returns ```json [ { "lower_bound": 100000, "upper_bound": 199999, "days_on_market": 45, "months_on_market": 1.5, "properties_count": 120 } ] ``` | Field | Type | Description | |---------------|-------|------------| | `lower_bound` | `int` | Lower price limit | | `upper_bound` | `int` | Upper price limit | | `days_on_market` | `int` | Average number of active days | | `months_on_market` | `float` | Average duration in months | | `properties_count` | `int` | Number of listings in the group | #### Example Request ```json { "custom_location_boundary": { "circle": { "target_point": {"latitude": 41.3851, "longitude": 2.1734}, "distance": 20000 } }, "type_group": "apartment", "business_type": "sale", "price_range": {"min": 100000, "max": 1000000}, "date_range": {"min": "2024-01-01", "max": "2024-12-31"}, "exclude_outliers": true } ``` ## Parameters - `request_data` (object, required) - `type_group` (string, required): Estate type group. Values: `apartment`, `house`. - `business_type` (string, required): Operation type for which the property is available. Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true. - `custom_location_boundary` (object, required) - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `date_range` (object, optional): Filter properties based on the start date of their last active period on the market. - `min` (string (date), required): Start date in the format `YYYY-MM-DD`. - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`. ## Response The result is returned as `result`: - `lower_bound` (integer, required): The lower price bound of the distribution unit. - `upper_bound` (integer, required): The upper price bound of the distribution unit. - `days_on_market` (integer, required): The average days on the market. - `months_on_market` (number, required): The average months on the market. - `properties_count` (integer, required): The number of properties that participated in the distribution. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ma_get_time_on_market_distribution", "arguments": { "request_data": { "type_group": "apartment", "business_type": "sale", "custom_location_boundary": { "location_ids": [ 1 ] } } } } } ``` ## Questions about this - [What is Area Insights?](/docs/faq/what-is-area-insights) - [How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap) --- # `ma_get_heatmap` Get Heatmap. Product: [Area Insights](/docs/area-insights). Annotations: Read-only. Call it as `ma_get_heatmap` on `https://mcp.casafari.com/` (the backend's own name is `get_heatmap`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#area-insights). ## Description Generate an **area insights heatmap** showing property distribution and price dynamics across geographic areas. This tool aggregates **active real estate listings** for the child locations of the given `location_id` (e.g., districts of a city), returning the selected `data_point` metric for each of them. It supports a wide range of property filters, including estate type, price range, construction year, and location hierarchy. #### Use Cases Retrieve geographic insights for real estate analytics: - Visualize market activity intensity across a city or region. - Identify hotspots of high property density or high average price. - Compare neighborhoods based on average price per sqm. - Analyze supply distribution and property trends over time. - Combine with time-series data to understand historical evolution by area. #### Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPHeatMapRequestSchema` | Yes | Defines filters, metrics, and date range for heatmap generation. | #### Important Notes - Only **ACTIVE** listings are included. - The tool automatically resolves **child locations** (e.g., neighborhoods within a city). - If no matching data is found, a `ToolError` will be raised. - Use returned data for **map visualization** or **spatial analytics dashboards**. #### Returns ```json [ { "location_id": 12345, "location_name": "Lisbon", "value": 5200.5 } ] ``` Each item represents one geographic unit with aggregated metric value. ## Parameters - `request_data` (object, required) - `type_group` (string, required): Estate type group. Values: `apartment`, `house`. - `business_type` (string, required): Operation type for which the property is available. Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true. - `location_id` (integer, required) 1–2147483647. - `data_point` (string, required): Specifies the type of real estate data to retrieve for a given period. Values: `avg_price`, `avg_price_psqm`, `available_on_market`, `new`, `sold_or_rented`, `price_up`, `price_down`. - `date_range` (object, required) - `min` (string (date), required): Start date in the format `YYYY-MM-DD`. If the specified date is not Monday - the closest previous Monday will be selected - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`. If the specified date is not Sunday - the closest previous Sunday will be selected ## Response The result is returned as `result`: - `location_id` (integer, required) - `location_name` (string, required) - `value` (number, required) ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ma_get_heatmap", "arguments": { "request_data": { "type_group": "apartment", "business_type": "sale", "location_id": 1, "data_point": "avg_price", "date_range": { "min": "2025-01-01" } } } } } ``` ## Questions about this - [What is Area Insights?](/docs/faq/what-is-area-insights) - [Which tools exist only over MCP, and which operations only over REST?](/docs/faq/mcp-only-and-rest-only) - [How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap) - [Can I build a market report with Casafari MCP?](/docs/faq/example-market-report) --- # `ma_get_location_typeahead` Get Location Typeahead. Product: [Area Insights](/docs/area-insights). Annotations: Read-only. Call it as `ma_get_location_typeahead` on `https://mcp.casafari.com/` (the backend's own name is `get_location_typeahead`). Over REST: [`POST /api/v1/references/locations/typeahead`](/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1) (related). [MCP and REST compared](/docs/parity#area-insights). ## Description Retrieve typeahead suggestions for a given location name. Use case: Retrieve typeahead suggestions to get location_id for different requests. Important notes: - If there is more than one location with the same name, and it's not clear which one is correct - specify more information / symbols in the request. - The `location_name` should be a valid location name in English. ## Parameters - `location_name` (string, required) ## Response The result is returned as `result`: - `location_id` (integer, required) - `name` (string, required) - `matched_name` (string, required) - `administrative_level` (string, required) - `breadcrumbs` (object[], required) - `location_id` (integer, required) - `name` (string, required) ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ma_get_location_typeahead", "arguments": { "location_name": "…" } } } ``` ## Questions about this - [What is Area Insights?](/docs/faq/what-is-area-insights) - [How do I value a home or find comparables with Casafari MCP?](/docs/faq/example-valuation) - [How do I analyse how prices in an area have moved over time?](/docs/faq/example-price-trend) - [How do I turn a place name into a location id?](/docs/faq/location-ids) --- # Area Insights REST API Insights for an area: price, supply and activity over time, distributions by price, bedrooms and time on market, and market analysis. Over MCP also growth and volatility measures and heatmaps by district. 6 operations, from the public OpenAPI description. Base URL `https://api.casafari.com`; every operation but sign-in needs a bearer token (see [the REST API overview](/docs/rest#get-a-token)). Over MCP, Area Insights has 8 tools: see [Area Insights](/docs/area-insights) and [MCP and REST compared](/docs/parity#area-insights). ## Time Series - [`POST /market-analytics-api/time-series`](/docs/rest/area-insights/time-series): Time Series. Returns time series data for the real estate market. ## Distributions Paths under `/market-analytics-api/distributions`. - [`POST /market-analytics-api/distributions/bedrooms`](/docs/rest/area-insights/bedrooms-distribution): Bedrooms Distribution. Returns property distribution based on the number of bedrooms. - [`POST /market-analytics-api/distributions/prices`](/docs/rest/area-insights/price-distribution): Price Distribution. Returns the number of properties distributed across price ranges. - [`POST /market-analytics-api/distributions/properties`](/docs/rest/area-insights/properties-distribution): Properties Distribution. Returns the properties lightweight data sample and distribution quartiles. - [`POST /market-analytics-api/distributions/time-on-market`](/docs/rest/area-insights/time-on-market-distribution): Time On Market Distribution. Returns time on market (days and months) distribution by price ranges. ## Analysis - [`POST /market-analytics-api/analysis`](/docs/rest/area-insights/analysis): Analysis. Market analysis based on the requested property parameters. --- # Time Series `POST https://api.casafari.com/market-analytics-api/time-series` [Area Insights](/docs/area-insights) · [REST API](/docs/rest/area-insights). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: [`ma_get_time_series_data`](/docs/area-insights/get_time_series_data) (equivalent). See [MCP and REST compared](/docs/parity#area-insights). ## Description Returns time series data for the real estate market. Each time series unit includes the interval start date based on the provided `date_interval` and a value corresponding to the selected `data_point`. ## Request body Content type `application/json`. Required. Type: `object`. - `types` (string[], required): The list of property types by type groups: **apartment:** ["apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung"] **house:** ["country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe"] **room:** ["room"] **building:** ["apartment_building", "office_building", "mix_use_building"] **investment:** ["retail", "office", "industrial", "warehouse", "hotel", "building", "other_commercial", "restaurant", "werkstatt"] **development:** ["apartment_development", "house_development"] **plot:** ["urban_plot", "rural_plot"] **other:** ["parking", "garage", "other"] *Note that you can select multiple types only from one property type group.* The list of property types specific to certain countries: **apartment:** ○ dachgeschosswohnung: **Germany** ○ etagenwohnung: **Germany** ○ erdgeschosswohnung: **Germany** **house:** ○ family_house: **Germany** ○ reihenhaus: **Germany** ○ reihenendhaus: **Germany** ○ reihenmittelhaus: **Germany** ○ einfamilienhaus: **Germany** ○ zweifamilienhaus: **Germany** ○ landwirtschaftliche_betriebe: **Germany** **investment:** ○ restaurant: **Germany** ○ werkstatt: **Germany** **plot:** ○ urban_plot: **Italy, Germany, Portugal, Spain, France** ○ rural_plot: **Italy, Germany, Portugal, Spain, France** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `building`, `other_commercial`, `restaurant`, `werkstatt`, `urban_plot`, `rural_plot`, `room`, `parking`, `garage`, `other`, `apartment_building`, `office_building`, `mix_use_building`, `apartment_development`, `house_development`. at least 1 item. - `business_type` (string, required) Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default false. - `custom_location_boundary` (object, required) - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `polygon` (object[], optional): List of geo-points to search within. Polygon must contain at least 4 points. First and last points must match. at least 4 items. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `data_point` (string, required): Specifies the type of real estate data to retrieve for a given period. Values: `avg_price`, `avg_price_psqm`, `available_on_market`, `new`, `sold_or_rented`, `price_up`, `price_down`. - `date_interval` (string, required): Defines the time interval for aggregating data points. Determines the frequency at which data is reported in the response. Values: `week`, `month`, `quarter`, `year`. - `date_range` (object, required) - `min` (string (date), required): Start date in the format `YYYY-MM-DD`. If the specified date is not Monday - the closest previous Monday will be selected. - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`. If the specified date is not Sunday - the closest previous Sunday will be selected. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/market-analytics-api/time-series" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "types": [ "apartment" ], "business_type": "sale", "custom_location_boundary": { "location_ids": [ 1 ] }, "data_point": "avg_price", "date_interval": "week", "date_range": { "min": "2025-01-01" } }' ``` ## Responses ### 200 Successful Response Type: `object[]`. - `date_start` (string (date), required): The starting date of the period associated with the passed `date_interval` field value. The format follows `YYYY-MM-DD`. - `value` (number, required): The numerical value corresponding to the passed `data_point` field value for the given `date_start`. ### 204 No Content No body. ### 400 Bad Request Type: `object`. - `message` (string, required) - `errors` (string[], optional, nullable) - `details` (string, optional, nullable) ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [How do I analyse how prices in an area have moved over time?](/docs/faq/example-price-trend) --- # Bedrooms Distribution `POST https://api.casafari.com/market-analytics-api/distributions/bedrooms` [Area Insights](/docs/area-insights) · [REST API](/docs/rest/area-insights). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: [`ma_get_bedrooms_distribution`](/docs/area-insights/get_bedrooms_distribution) (equivalent). See [MCP and REST compared](/docs/parity#area-insights). ## Description Returns property distribution based on the number of bedrooms. Each distribution unit includes the bedroom count, number of matching properties, and related analysis. ## Request body Content type `application/json`. Required. Type: `object`. - `types` (string[], required): The list of property types by type groups: **apartment:** ["apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung"] **house:** ["country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe"] **development:** ["apartment_development", "house_development"] *Note that you can select multiple types only from one property type group.* The list of property types specific to certain countries: **apartment:** ○ dachgeschosswohnung: **Germany** ○ etagenwohnung: **Germany** ○ erdgeschosswohnung: **Germany** **house:** ○ family_house: **Germany** ○ reihenhaus: **Germany** ○ reihenendhaus: **Germany** ○ reihenmittelhaus: **Germany** ○ einfamilienhaus: **Germany** ○ zweifamilienhaus: **Germany** ○ landwirtschaftliche_betriebe: **Germany** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `apartment_development`, `house_development`. at least 1 item. - `business_type` (string, required) Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–10. - `max` (integer, optional, nullable) 0–10. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default false. - `custom_location_boundary` (object, required) - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `polygon` (object[], optional): List of geo-points to search within. Polygon must contain at least 4 points. First and last points must match. at least 4 items. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/market-analytics-api/distributions/bedrooms" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "types": [ "apartment" ], "business_type": "sale", "custom_location_boundary": { "location_ids": [ 1 ] } }' ``` ## Responses ### 200 Successful Response Type: `object[]`. - `bedrooms` (string, required): The number of bedrooms in the properties that participated in the distribution. - `properties_count` (integer, required): The number of properties that participated in the distribution. - `average_price` (number, required): Average price of properties with a specific number of bedrooms. - `average_price_per_sqm` (number, required): Average price per square meter of properties with a specific number of bedrooms. ### 204 No Content No body. ### 400 Bad Request Type: `object`. - `message` (string, required) - `errors` (string[], optional, nullable) - `details` (string, optional, nullable) ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap) --- # Price Distribution `POST https://api.casafari.com/market-analytics-api/distributions/prices` [Area Insights](/docs/area-insights) · [REST API](/docs/rest/area-insights). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: [`ma_get_price_distribution`](/docs/area-insights/get_price_distribution) (equivalent). See [MCP and REST compared](/docs/parity#area-insights). ## Description Returns the number of properties distributed across price ranges. Each range is defined by price boundaries and shows the number of properties with prices falling within those boundaries. ## Request body Content type `application/json`. Required. Type: `object`. - `types` (string[], required): The list of property types by type groups: **apartment:** ["apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung"] **house:** ["country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe"] **room:** ["room"] **building:** ["apartment_building", "office_building", "mix_use_building"] **investment:** ["retail", "office", "industrial", "warehouse", "hotel", "building", "other_commercial", "restaurant", "werkstatt"] **development:** ["apartment_development", "house_development"] **plot:** ["urban_plot", "rural_plot"] **other:** ["parking", "garage", "other"] *Note that you can select multiple types only from one property type group.* The list of property types specific to certain countries: **apartment:** ○ dachgeschosswohnung: **Germany** ○ etagenwohnung: **Germany** ○ erdgeschosswohnung: **Germany** **house:** ○ family_house: **Germany** ○ reihenhaus: **Germany** ○ reihenendhaus: **Germany** ○ reihenmittelhaus: **Germany** ○ einfamilienhaus: **Germany** ○ zweifamilienhaus: **Germany** ○ landwirtschaftliche_betriebe: **Germany** **investment:** ○ restaurant: **Germany** ○ werkstatt: **Germany** **plot:** ○ urban_plot: **Italy, Germany, Portugal, Spain, France** ○ rural_plot: **Italy, Germany, Portugal, Spain, France** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `building`, `other_commercial`, `restaurant`, `werkstatt`, `urban_plot`, `rural_plot`, `room`, `parking`, `garage`, `other`, `apartment_building`, `office_building`, `mix_use_building`, `apartment_development`, `house_development`. at least 1 item. - `business_type` (string, required) Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default false. - `custom_location_boundary` (object, required) - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `polygon` (object[], optional): List of geo-points to search within. Polygon must contain at least 4 points. First and last points must match. at least 4 items. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/market-analytics-api/distributions/prices" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "types": [ "apartment" ], "business_type": "sale", "custom_location_boundary": { "location_ids": [ 1 ] } }' ``` ## Responses ### 200 Successful Response Type: `object[]`. - `lower_bound` (integer, required): The lower price bound of the distribution unit. - `upper_bound` (integer, required): The upper price bound of the distribution unit. - `properties_count` (integer, required): The number of properties that participated in the distribution. - `is_mean` (boolean, required): Indicates whether the mean value is within this distribution unit. ### 204 No Content No body. ### 400 Bad Request Type: `object`. - `message` (string, required) - `errors` (string[], optional, nullable) - `details` (string, optional, nullable) ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap) --- # Properties Distribution `POST https://api.casafari.com/market-analytics-api/distributions/properties` [Area Insights](/docs/area-insights) · [REST API](/docs/rest/area-insights). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#area-insights). ## Description Returns the properties lightweight data sample and distribution quartiles. Lightweight data includes only price and location data. ## Request body Content type `application/json`. Required. Type: `object`. - `types` (string[], required): The list of property types by type groups: **apartment:** ["apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung"] **house:** ["country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe"] **room:** ["room"] **building:** ["apartment_building", "office_building", "mix_use_building"] **investment:** ["retail", "office", "industrial", "warehouse", "hotel", "building", "other_commercial", "restaurant", "werkstatt"] **development:** ["apartment_development", "house_development"] **plot:** ["urban_plot", "rural_plot"] **other:** ["parking", "garage", "other"] *Note that you can select multiple types only from one property type group.* The list of property types specific to certain countries: **apartment:** ○ dachgeschosswohnung: **Germany** ○ etagenwohnung: **Germany** ○ erdgeschosswohnung: **Germany** **house:** ○ family_house: **Germany** ○ reihenhaus: **Germany** ○ reihenendhaus: **Germany** ○ reihenmittelhaus: **Germany** ○ einfamilienhaus: **Germany** ○ zweifamilienhaus: **Germany** ○ landwirtschaftliche_betriebe: **Germany** **investment:** ○ restaurant: **Germany** ○ werkstatt: **Germany** **plot:** ○ urban_plot: **Italy, Germany, Portugal, Spain, France** ○ rural_plot: **Italy, Germany, Portugal, Spain, France** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `building`, `other_commercial`, `restaurant`, `werkstatt`, `urban_plot`, `rural_plot`, `room`, `parking`, `garage`, `other`, `apartment_building`, `office_building`, `mix_use_building`, `apartment_development`, `house_development`. at least 1 item. - `business_type` (string, required) Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default false. - `custom_location_boundary` (object, required) - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `polygon` (object[], optional): List of geo-points to search within. Polygon must contain at least 4 points. First and last points must match. at least 4 items. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/market-analytics-api/distributions/properties" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "types": [ "apartment" ], "business_type": "sale", "custom_location_boundary": { "location_ids": [ 1 ] } }' ``` ## Responses ### 200 Successful Response Type: `object`. - `properties` (object[], required): List of properties that participated in the distribution. - `property_id` (integer, required): ID of the property. - `property_unit_id` (integer, required): Property sub-identifier. Along with the property_id, it ensures the uniqueness of the property. - `price` (integer, required) - `price_per_sqm` (number, required) - `location_id` (integer, required) - `coordinates` (object, required) - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `quartiles` (object, required): The quantiles that divide the properties distribution into four parts. - `lower` (number, required): 25th percentile. The lowest 25% of distribution data is below this point. - `mean` (number, required): 50th percentile or median. The lowest 50% of distribution data is below this point. - `upper` (number, required): 75th percentile. The lowest 75% of distribution data is below this point. ### 204 No Content No body. ### 400 Bad Request Type: `object`. - `message` (string, required) - `errors` (string[], optional, nullable) - `details` (string, optional, nullable) ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [Which tools exist only over MCP, and which operations only over REST?](/docs/faq/mcp-only-and-rest-only) --- # Time On Market Distribution `POST https://api.casafari.com/market-analytics-api/distributions/time-on-market` [Area Insights](/docs/area-insights) · [REST API](/docs/rest/area-insights). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: [`ma_get_time_on_market_distribution`](/docs/area-insights/get_time_on_market_distribution) (equivalent). See [MCP and REST compared](/docs/parity#area-insights). ## Description Returns time on market (days and months) distribution by price ranges. Each distribution unit is defined by price boundaries and includes the time on market for properties within those boundaries. ## Request body Content type `application/json`. Required. Type: `object`. - `types` (string[], required): The list of property types by type groups: **apartment:** ["apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung"] **house:** ["country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe"] **room:** ["room"] **building:** ["apartment_building", "office_building", "mix_use_building"] **investment:** ["retail", "office", "industrial", "warehouse", "hotel", "building", "other_commercial", "restaurant", "werkstatt"] **development:** ["apartment_development", "house_development"] **plot:** ["urban_plot", "rural_plot"] **other:** ["parking", "garage", "other"] *Note that you can select multiple types only from one property type group.* The list of property types specific to certain countries: **apartment:** ○ dachgeschosswohnung: **Germany** ○ etagenwohnung: **Germany** ○ erdgeschosswohnung: **Germany** **house:** ○ family_house: **Germany** ○ reihenhaus: **Germany** ○ reihenendhaus: **Germany** ○ reihenmittelhaus: **Germany** ○ einfamilienhaus: **Germany** ○ zweifamilienhaus: **Germany** ○ landwirtschaftliche_betriebe: **Germany** **investment:** ○ restaurant: **Germany** ○ werkstatt: **Germany** **plot:** ○ urban_plot: **Italy, Germany, Portugal, Spain, France** ○ rural_plot: **Italy, Germany, Portugal, Spain, France** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `building`, `other_commercial`, `restaurant`, `werkstatt`, `urban_plot`, `rural_plot`, `room`, `parking`, `garage`, `other`, `apartment_building`, `office_building`, `mix_use_building`, `apartment_development`, `house_development`. at least 1 item. - `business_type` (string, required) Values: `sale`, `rent`. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_per_sqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `bank` (boolean, optional): Whether the property is owned by the bank. - `auction` (boolean, optional): Whether the property is the subject of an auction. default false. - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default false. - `custom_location_boundary` (object, required) - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `polygon` (object[], optional): List of geo-points to search within. Polygon must contain at least 4 points. First and last points must match. at least 4 items. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `date_range` (object, optional): Filter properties based on the start date of their last active period on the market. - `min` (string (date), required): Start date in the format `YYYY-MM-DD`. - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/market-analytics-api/distributions/time-on-market" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "types": [ "apartment" ], "business_type": "sale", "custom_location_boundary": { "location_ids": [ 1 ] } }' ``` ## Responses ### 200 Successful Response Type: `object[]`. - `lower_bound` (integer, required): The lower price bound of the distribution unit. - `upper_bound` (integer, required): The upper price bound of the distribution unit. - `days_on_market` (integer, required): The average days on the market. - `months_on_market` (number, required): The average months on the market. - `properties_count` (integer, required): The number of properties that participated in the distribution. ### 204 No Content No body. ### 400 Bad Request Type: `object`. - `message` (string, required) - `errors` (string[], optional, nullable) - `details` (string, optional, nullable) ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap) --- # Analysis `POST https://api.casafari.com/market-analytics-api/analysis` [Area Insights](/docs/area-insights) · [REST API](/docs/rest/area-insights). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#area-insights). ## Description Market analysis based on the requested property parameters. ## Request body Content type `application/json`. Required. Type: `object`. - `custom_location_boundary` (object, required) - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647. - `polygon` (object[], optional): List of geo-points to search within. Polygon must contain at least 4 points. First and last points must match. at least 4 items. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `circle` (object, optional): Circle boundary to search within. - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000. - `target_point` (object, required): Target point coordinates to search around. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `business_type` (string, required): Operation type for which the property is available. Values: `sale`, `rent`. - `types` (string[], required): The list of property types by type groups: **apartment:** ["apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung"] **house:** ["country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe"] **room:** ["room"] **building:** ["apartment_building", "office_building", "mix_use_building"] **investment:** ["retail", "office", "industrial", "warehouse", "hotel", "building", "other_commercial", "restaurant", "werkstatt"] **development:** ["apartment_development", "house_development"] **plot:** ["urban_plot", "rural_plot"] **other:** ["parking", "garage", "other"] *Note that you can select multiple types only from one property type group.* The list of property types specific to certain countries: **apartment:** ○ dachgeschosswohnung: **Germany** ○ etagenwohnung: **Germany** ○ erdgeschosswohnung: **Germany** **house:** ○ family_house: **Germany** ○ reihenhaus: **Germany** ○ reihenendhaus: **Germany** ○ reihenmittelhaus: **Germany** ○ einfamilienhaus: **Germany** ○ zweifamilienhaus: **Germany** ○ landwirtschaftliche_betriebe: **Germany** **investment:** ○ restaurant: **Germany** ○ werkstatt: **Germany** **plot:** ○ urban_plot: **Italy, Germany, Portugal, Spain, France** ○ rural_plot: **Italy, Germany, Portugal, Spain, France** Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `building`, `other_commercial`, `restaurant`, `werkstatt`, `urban_plot`, `rural_plot`, `room`, `parking`, `garage`, `other`, `apartment_building`, `office_building`, `mix_use_building`, `apartment_development`, `house_development`. at least 1 item. - `conditions` (string[], optional, nullable): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item. - `energy_ratings` (string[], optional, nullable): List of energy ratings that attests to the energy efficiency of the property. Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`. at least 1 item. - `orientations` (string[], optional, nullable): Property view orientation. Values: `exterior`, `interior`. at least 1 item. - `views` (string[], optional, nullable): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. at least 1 item. - `directions` (string[], optional, nullable): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. at least 1 item. - `floors` (string[], optional, nullable): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`. at least 1 item. - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `rooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `characteristics` (object, optional, nullable) - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/market-analytics-api/analysis" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "custom_location_boundary": { "location_ids": [ 1 ] }, "business_type": "sale", "types": [ "apartment" ] }' ``` ## Responses ### 200 Successful Response Type: `object`. - `price_statistics` (object, required): Statistics including the average price and average price per square meter for properties matching the requested filters. - `average_price` (integer, required) - `average_price_per_sqm` (integer, required) - `price_estimation` (object, required): Provides estimated prices, including a quick sale price `fast_market_price` and an inflated price `out_of_market_price`. - `fast_market_price` (integer, required) - `out_of_market_price` (integer, required) - `price_evolution` (object, required): Represents time series data showing how average prices and prices per square meter have changed over time for inactive properties. - `avg_price` (object, required) - `for_the_last_1_month` (integer, required) - `for_the_last_3_month` (integer, required) - `for_the_last_6_month` (integer, required) - `for_the_last_9_month` (integer, required) - `for_the_last_12_month` (integer, required) - `avg_price_per_sqm` (object, required) - `for_the_last_1_month` (integer, required) - `for_the_last_3_month` (integer, required) - `for_the_last_6_month` (integer, required) - `for_the_last_9_month` (integer, required) - `for_the_last_12_month` (integer, required) - `summary_price_evolution` (object, required): Represents time series data showing how average prices and prices per square meter have changed over time for both active and inactive properties. - `avg_price` (object, required) - `for_the_last_1_month` (integer, required) - `for_the_last_3_month` (integer, required) - `for_the_last_6_month` (integer, required) - `for_the_last_9_month` (integer, required) - `for_the_last_12_month` (integer, required) - `avg_price_per_sqm` (object, required) - `for_the_last_1_month` (integer, required) - `for_the_last_3_month` (integer, required) - `for_the_last_6_month` (integer, required) - `for_the_last_9_month` (integer, required) - `for_the_last_12_month` (integer, required) - `average_days_on_the_market` (integer, required): Indicates the average number of days properties remain listed on the market before being sold or removed. ### 400 Bad Request Type: `object`. - `message` (string, required) - `errors` (string[], optional, nullable) - `details` (string, optional, nullable) ### 404 Not Found Type: `object`. - `message` (string, required) - `errors` (string[], optional, nullable) - `details` (string, optional, nullable) ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [Which tools exist only over MCP, and which operations only over REST?](/docs/faq/mcp-only-and-rest-only) --- # Alerts Alert feeds that follow the property graph for a set of filters: new properties, price rises and cuts, reservations, delistings and sales. Create a feed, read its alerts, or have them delivered to your webhook. 12 REST operations. ## REST API 12 operations in the public OpenAPI description, all under `https://api.casafari.com` with a bearer token ([how to get one](/docs/rest#get-a-token)). The same list with more detail: [Alerts REST API](/docs/rest/alerts). ### Alerts Paths under `/api/v1/listing-alerts`. - [`GET /api/v1/listing-alerts/feeds`](/docs/rest/alerts/get-feeds-list-v1): Get feeds list (v1). Returns all alerts feeds for currently authenticated user. - [`POST /api/v1/listing-alerts/feeds`](/docs/rest/alerts/create-feed-v1): Create feed (v1). Create alerts feed for currently authenticated user. - [`GET /api/v1/listing-alerts/feeds/{id}`](/docs/rest/alerts/get-alerts-by-feed-v1): Get alerts by feed (v1). Returns paginated list of alerts (by feed ID) for currently authenticated user. - [`DELETE /api/v1/listing-alerts/feeds/{id}`](/docs/rest/alerts/delete-feed-v1): Delete feed (v1). Delete alerts feed (by feed ID) for currently authenticated user. - [`PUT /api/v1/listing-alerts/feeds/{id}/update`](/docs/rest/alerts/update-feed-v1): Update feed (v1). Update alerts feed by id. - [`POST /api/v1/listing-alerts/search`](/docs/rest/alerts/search-alerts-v1): Search alerts (v1). Returns paginated list of alerts (by requested parameters) for currently authenticated user. ### Feeds Paths under `/alerts-api/feeds`. - [`GET /alerts-api/feeds`](/docs/rest/alerts/list-feeds): List feeds. Returns a paginated list of feeds, sorted newest first. - [`POST /alerts-api/feeds`](/docs/rest/alerts/create-feed): Create feed. Create a new alert feed that delivers matching real estate events to your webhook URL. - [`GET /alerts-api/feeds/{feed_id}`](/docs/rest/alerts/get-feed): Get feed. Returns the feed configuration in the same format as it was originally created. - [`DELETE /alerts-api/feeds/{feed_id}`](/docs/rest/alerts/delete-feed): Delete feed. Permanently removes the feed. ### Webhooks Paths under `/alerts-api/webhooks`. - [`PUT /alerts-api/webhooks`](/docs/rest/alerts/set-webhook-url): Set webhook URL. Sets (or replaces) the delivery URL for all your alert feeds. - [`POST /alerts-api/webhooks/rotate-secret`](/docs/rest/alerts/rotate-signing-secret): Rotate signing secret. Issues a new current signing secret. ## MCP and REST compared Over MCP: 0 tools. Over REST: 12 operations. Available over REST only: MCP has no tool for it. Details: [MCP and REST compared](/docs/parity#alerts). ## Questions about this - [Which products does Casafari MCP offer, and how many tools are there?](/docs/faq/which-products) - [Can I get alerts (new properties, price cuts, sales) over Casafari MCP?](/docs/faq/alerts-over-mcp) - [How do I get alerts delivered to a webhook?](/docs/faq/alerts-webhook) - [Does Casafari keep price and status history?](/docs/faq/price-and-status-history) --- # Alerts REST API Alert feeds that follow the property graph for a set of filters: new properties, price rises and cuts, reservations, delistings and sales. Create a feed, read its alerts, or have them delivered to your webhook. 12 operations, from the public OpenAPI description. Base URL `https://api.casafari.com`; every operation but sign-in needs a bearer token (see [the REST API overview](/docs/rest#get-a-token)). Over MCP, Alerts has no tools: see [MCP and REST compared](/docs/parity#alerts). ## Alerts Paths under `/api/v1/listing-alerts`. - [`GET /api/v1/listing-alerts/feeds`](/docs/rest/alerts/get-feeds-list-v1): Get feeds list (v1). Returns all alerts feeds for currently authenticated user. - [`POST /api/v1/listing-alerts/feeds`](/docs/rest/alerts/create-feed-v1): Create feed (v1). Create alerts feed for currently authenticated user. - [`GET /api/v1/listing-alerts/feeds/{id}`](/docs/rest/alerts/get-alerts-by-feed-v1): Get alerts by feed (v1). Returns paginated list of alerts (by feed ID) for currently authenticated user. - [`DELETE /api/v1/listing-alerts/feeds/{id}`](/docs/rest/alerts/delete-feed-v1): Delete feed (v1). Delete alerts feed (by feed ID) for currently authenticated user. - [`PUT /api/v1/listing-alerts/feeds/{id}/update`](/docs/rest/alerts/update-feed-v1): Update feed (v1). Update alerts feed by id. - [`POST /api/v1/listing-alerts/search`](/docs/rest/alerts/search-alerts-v1): Search alerts (v1). Returns paginated list of alerts (by requested parameters) for currently authenticated user. ## Feeds Paths under `/alerts-api/feeds`. - [`GET /alerts-api/feeds`](/docs/rest/alerts/list-feeds): List feeds. Returns a paginated list of feeds, sorted newest first. - [`POST /alerts-api/feeds`](/docs/rest/alerts/create-feed): Create feed. Create a new alert feed that delivers matching real estate events to your webhook URL. - [`GET /alerts-api/feeds/{feed_id}`](/docs/rest/alerts/get-feed): Get feed. Returns the feed configuration in the same format as it was originally created. - [`DELETE /alerts-api/feeds/{feed_id}`](/docs/rest/alerts/delete-feed): Delete feed. Permanently removes the feed. ## Webhooks Paths under `/alerts-api/webhooks`. - [`PUT /alerts-api/webhooks`](/docs/rest/alerts/set-webhook-url): Set webhook URL. Sets (or replaces) the delivery URL for all your alert feeds. - [`POST /alerts-api/webhooks/rotate-secret`](/docs/rest/alerts/rotate-signing-secret): Rotate signing secret. Issues a new current signing secret. ## Questions about this - [Can I get alerts (new properties, price cuts, sales) over Casafari MCP?](/docs/faq/alerts-over-mcp) - [How do I get alerts delivered to a webhook?](/docs/faq/alerts-webhook) --- # Get feeds list (v1) `GET https://api.casafari.com/api/v1/listing-alerts/feeds` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Returns all alerts feeds for currently authenticated user. ## Query parameters - `filter` (boolean, optional): Whether to include information about feed filters in the response. - `only_self` (boolean, optional): Indicates if manager user wants to see only own feeds. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/listing-alerts/feeds" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object[]`. - `id` (integer, optional) - `name` (string, required): Name of the feed. at most 200 characters. - `filter` (object, required): Set of clauses to filter alerts. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `location_ids` (integer[], optional): List of location IDs, as returned by the POST /api/v1/references/locations endpoint. at most 100 items; 1–2147483647. - `custom_location` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. **This field is deprecated and will be removed in the next major update.** **Please, use `custom_locations` field instead.** at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `custom_locations` (object[][], optional): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. at most 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `types` (string[], optional): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `alert_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `alert_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `created_at_from` (string (date-time), optional): Start date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_to` (string (date-time), optional): End date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_with_photos_from` (string (date-time), optional): Start date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `created_at_with_photos_to` (string (date-time), optional): End date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `statuses` (string[], optional): Current status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `rented`. - `price_from` (integer, optional): Minimum price value. 1–2147483647. - `price_to` (integer, optional): Maximum price value. 1–2147483647. - `price_per_sqm_from` (integer, optional): Minimum value for price per square meter. 1–2147483647. - `price_per_sqm_to` (integer, optional): Maximum value for price per square meter. 1–2147483647. - `bedrooms_from` (integer, optional): Minimum number of bedrooms. 0–15000. - `bedrooms_to` (integer, optional): Maximum number of bedrooms. 0–15000. - `bathrooms_from` (integer, optional): Minimum number of bathrooms. 1–15000. - `bathrooms_to` (integer, optional): Maximum number of bathrooms. 1–15000. - `total_area_from` (integer, optional): Minimum total area. 1–10000000. - `total_area_to` (integer, optional): Maximum total area. 1–10000000. - `plot_area_from` (integer, optional): Minimum plot area. 1–10000000. - `plot_area_to` (integer, optional): Maximum plot area. 1–10000000. - `construction_year_from` (integer, optional): Minimum construction year. 1–3000. - `construction_year_to` (integer, optional): Maximum construction year. 1–3000. - `floor` (string, optional): Floor type of the property. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional) Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional) Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional) Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], optional): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `alert_subtypes` (string[], optional): Alert subtypes. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `private` (boolean, optional): Whether to return alerts only from properties listed by a private individual, as opposed to an agent or a professional. - `auction` (boolean, optional): Whether to return alerts from auction property listings. - `bank` (boolean, optional): Whether to return alerts from bank property listings. - `new_development` (boolean, optional): Whether to return alerts from new development property listings. - `listing_agents` (string[], optional): Return alerts only for properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint. - `with_agencies` (string[], optional): Return alerts only for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude alerts for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclusive` (boolean, optional): Whether to return alerts exclusively from specific listings rather than from all related to the property listings. Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `has_phone` (boolean, optional): Whether to return alerts only from listings with or without `phone` number. - `has_email` (boolean, optional): Whether to return alerts only from listings with or without email. - `has_agency_name` (boolean, optional): Whether to return alerts only from listings with or without agency name. - `property_ids` (integer[], optional): List of property IDs. at most 100 items; ≥ 1. - `listing_ids` (integer[], optional): List of listing IDs. at most 100 items; ≥ 1. - `user` (string (email), optional) Example from the API description: ```json [ { "id": 887, "user": "user@email.com", "name": "Apartments for sale" }, { "id": 888, "user": "user@email.com", "name": "Houses for sale" } ] ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. --- # Create feed (v1) `POST https://api.casafari.com/api/v1/listing-alerts/feeds` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Create alerts feed for currently authenticated user. Feed is a predefined set of conditions to filter alerts by. The `id` of created feed then should be used as URL parameter for get alerts by feed endpoint to get alerts filtered by feed filter conditions. ## Request body Content type `application/json`. Optional. Type: `object`. - `name` (string, required): Name of the feed. at most 200 characters. - `filter` (object, required): Set of clauses to filter alerts. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `location_ids` (integer[], optional): List of location IDs, as returned by the POST /api/v1/references/locations endpoint. at most 100 items; 1–2147483647. - `custom_location` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. **This field is deprecated and will be removed in the next major update.** **Please, use `custom_locations` field instead.** at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `custom_locations` (object[][], optional): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. at most 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `types` (string[], optional): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `alert_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `alert_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `created_at_from` (string (date-time), optional): Start date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_to` (string (date-time), optional): End date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_with_photos_from` (string (date-time), optional): Start date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `created_at_with_photos_to` (string (date-time), optional): End date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `statuses` (string[], optional): Current status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `rented`. - `price_from` (integer, optional): Minimum price value. 1–2147483647. - `price_to` (integer, optional): Maximum price value. 1–2147483647. - `price_per_sqm_from` (integer, optional): Minimum value for price per square meter. 1–2147483647. - `price_per_sqm_to` (integer, optional): Maximum value for price per square meter. 1–2147483647. - `bedrooms_from` (integer, optional): Minimum number of bedrooms. 0–15000. - `bedrooms_to` (integer, optional): Maximum number of bedrooms. 0–15000. - `bathrooms_from` (integer, optional): Minimum number of bathrooms. 1–15000. - `bathrooms_to` (integer, optional): Maximum number of bathrooms. 1–15000. - `total_area_from` (integer, optional): Minimum total area. 1–10000000. - `total_area_to` (integer, optional): Maximum total area. 1–10000000. - `plot_area_from` (integer, optional): Minimum plot area. 1–10000000. - `plot_area_to` (integer, optional): Maximum plot area. 1–10000000. - `construction_year_from` (integer, optional): Minimum construction year. 1–3000. - `construction_year_to` (integer, optional): Maximum construction year. 1–3000. - `floor` (string, optional): Floor type of the property. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional) Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional) Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional) Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], optional): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `alert_subtypes` (string[], optional): Alert subtypes. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `private` (boolean, optional): Whether to return alerts only from properties listed by a private individual, as opposed to an agent or a professional. - `auction` (boolean, optional): Whether to return alerts from auction property listings. - `bank` (boolean, optional): Whether to return alerts from bank property listings. - `new_development` (boolean, optional): Whether to return alerts from new development property listings. - `listing_agents` (string[], optional): Return alerts only for properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint. - `with_agencies` (string[], optional): Return alerts only for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude alerts for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclusive` (boolean, optional): Whether to return alerts exclusively from specific listings rather than from all related to the property listings. Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `has_phone` (boolean, optional): Whether to return alerts only from listings with or without `phone` number. - `has_email` (boolean, optional): Whether to return alerts only from listings with or without email. - `has_agency_name` (boolean, optional): Whether to return alerts only from listings with or without agency name. - `property_ids` (integer[], optional): List of property IDs. at most 100 items; ≥ 1. - `listing_ids` (integer[], optional): List of listing IDs. at most 100 items; ≥ 1. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/listing-alerts/feeds" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Apartments for sale in Cascais, Oeiras, Lisbon", "filter": { "operation": "sale", "types": [ "apartment", "studio", "duplex", "penthouse" ], "location_ids": [ 2942, 1861, 1600 ], "conditions": [ "used", "very-good", "new" ], "statuses": [ "active", "reserved" ], "price_from": 150000, "price_to": 800000, "price_per_sqm_from": 2000, "price_per_sqm_to": 8000, "bedrooms_from": 1, "bedrooms_to": 3, "total_area_from": 30, "total_area_to": 130, "construction_year_from": 1950, "floors": [ "middle", "top" ], "views": [ "city" ], "directions": [ "west", "south" ], "characteristics": [ "balcony", "elevator", "parking" ], "private": false, "new_development": false, "has_agency_name": true, "has_email": false, "without_agencies": [ "Airbnb", "Casa.Sapo" ] } }' ``` ## Responses ### 201 Created Type: `object`. - `id` (integer, optional) - `name` (string, required): Name of the feed. at most 200 characters. - `filter` (object, required): Set of clauses to filter alerts. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `location_ids` (integer[], optional): List of location IDs, as returned by the POST /api/v1/references/locations endpoint. at most 100 items; 1–2147483647. - `custom_location` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. **This field is deprecated and will be removed in the next major update.** **Please, use `custom_locations` field instead.** at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `custom_locations` (object[][], optional): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. at most 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `types` (string[], optional): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `alert_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `alert_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `created_at_from` (string (date-time), optional): Start date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_to` (string (date-time), optional): End date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_with_photos_from` (string (date-time), optional): Start date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `created_at_with_photos_to` (string (date-time), optional): End date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `statuses` (string[], optional): Current status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `rented`. - `price_from` (integer, optional): Minimum price value. 1–2147483647. - `price_to` (integer, optional): Maximum price value. 1–2147483647. - `price_per_sqm_from` (integer, optional): Minimum value for price per square meter. 1–2147483647. - `price_per_sqm_to` (integer, optional): Maximum value for price per square meter. 1–2147483647. - `bedrooms_from` (integer, optional): Minimum number of bedrooms. 0–15000. - `bedrooms_to` (integer, optional): Maximum number of bedrooms. 0–15000. - `bathrooms_from` (integer, optional): Minimum number of bathrooms. 1–15000. - `bathrooms_to` (integer, optional): Maximum number of bathrooms. 1–15000. - `total_area_from` (integer, optional): Minimum total area. 1–10000000. - `total_area_to` (integer, optional): Maximum total area. 1–10000000. - `plot_area_from` (integer, optional): Minimum plot area. 1–10000000. - `plot_area_to` (integer, optional): Maximum plot area. 1–10000000. - `construction_year_from` (integer, optional): Minimum construction year. 1–3000. - `construction_year_to` (integer, optional): Maximum construction year. 1–3000. - `floor` (string, optional): Floor type of the property. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional) Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional) Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional) Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], optional): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `alert_subtypes` (string[], optional): Alert subtypes. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `private` (boolean, optional): Whether to return alerts only from properties listed by a private individual, as opposed to an agent or a professional. - `auction` (boolean, optional): Whether to return alerts from auction property listings. - `bank` (boolean, optional): Whether to return alerts from bank property listings. - `new_development` (boolean, optional): Whether to return alerts from new development property listings. - `listing_agents` (string[], optional): Return alerts only for properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint. - `with_agencies` (string[], optional): Return alerts only for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude alerts for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclusive` (boolean, optional): Whether to return alerts exclusively from specific listings rather than from all related to the property listings. Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `has_phone` (boolean, optional): Whether to return alerts only from listings with or without `phone` number. - `has_email` (boolean, optional): Whether to return alerts only from listings with or without email. - `has_agency_name` (boolean, optional): Whether to return alerts only from listings with or without agency name. - `property_ids` (integer[], optional): List of property IDs. at most 100 items; ≥ 1. - `listing_ids` (integer[], optional): List of listing IDs. at most 100 items; ≥ 1. - `user` (string (email), optional) Example from the API description (long arrays shortened): ```json { "id": 887, "user": "user@email.com", "name": "Apartments for sale in Cascais, Oeiras, Lisbon", "filter": { "operation": "sale", "types": [ "apartment", "studio" ], "location_ids": [ 2942, 1861 ], "conditions": [ "used", "very-good" ], "statuses": [ "active", "reserved" ], "price_from": 150000, "price_to": 800000, "price_per_sqm_from": 2000, "price_per_sqm_to": 8000, "bedrooms_from": 1, "bedrooms_to": 3, "total_area_from": 30, "total_area_to": 130, "construction_year_from": 1950, "floors": [ "middle", "top" ], "views": [ "city" ], "directions": [ "west", "south" ], "characteristics": [ "balcony", "elevator" ], "private": false, "new_development": false, "has_agency_name": true, "has_email": false, "without_agencies": [ "Airbnb", "Casa.Sapo" ] } } ``` ### 400 Bad Request Type: `object`. - `errors` (object, optional): Description of the errors encountered. ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. --- # Get alerts by feed (v1) `GET https://api.casafari.com/api/v1/listing-alerts/feeds/{id}` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Returns paginated list of alerts (by feed ID) for currently authenticated user. ## Path parameters - `id` (string, required): A unique integer value identifying this alerts feed. ## Query parameters - `limit` (integer, optional): Number of results to return per page. - `offset` (integer, optional): Offset from which to start the search. Maximum value is 50000. - `order_by` (string, optional): The field by which to sort the results. Values: `alert_date`, `-alert_date`, `alert_id`, `-alert_id`, `created_at`, `-created_at`, `updated_at`, `-updated_at`. default "-alert_date". - `alert_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for alerts of interest. Overrides `alert_date_from` value if it was specified in the feed filter. Invalid values are ignored. - `alert_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for alerts of interest. Overrides `alert_date_to` value if it was specified in the feed filter. Invalid values are ignored. - `created_at_from` (string (date-time), optional): Start date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. Overrides `created_at_from` value if it was specified in the feed filter. Invalid values are ignored. - `created_at_to` (string (date-time), optional): End date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. Overrides `created_at_to` value if it was specified in the feed filter. Invalid values are ignored. - `created_at_with_photos_from` (string (date-time), optional): Start date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. Overrides `created_at_with_photos_from` value if it was specified in the feed filter. Invalid values are ignored. - `created_at_with_photos_to` (string (date-time), optional): End date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. Overrides `created_at_with_photos_to` value if it was specified in the feed filter. Invalid values are ignored. - `alert_subtype` (string, optional): Get only alerts of the specific subtype (for the requested feed). Invalid values are ignored. **This field is deprecated and will be removed in the next major update.** **Please, use `alert_subtypes` field in the feed.filter instead.** Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/listing-alerts/feeds/" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object[]`. - `count` (integer, optional) - `next` (string (uri), optional, nullable) - `previous` (string (uri), optional, nullable) - `results` (object, optional) - `alert_id` (integer, required): ID of the alert. - `listing_id` (integer, required): ID of the listing (ad). - `ref` (string, required): The reference ID of the listing. - `alert_type` (string, required): The type of the alert. Values: `sale_price`, `sale_status`, `rent_price`, `rent_status`, `new`. - `alert_subtype` (string, required): The subtype of the alert. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `old_value` (string, required): Value before change. - `new_value` (string, required): Value after change. - `alert_date` (string (date), required): Date when the alert occurred. - `alert_date_and_time` (string, optional, nullable): Date and time when the alert occurred. - `property_url` (string, optional, nullable): URL of the property in the CASAFARI website. - `listing_url` (string, optional, nullable): URL of the listing. Available only for currently active listings. - `listing_old_url` (string, optional, nullable): Old URL of the listing. Available only for currently inactive listings. - `listing_uid` (string, required): Unique ID of the listing on the source site. - `property_id` (integer, required): ID of the property to which the listing belongs. - `title` (string, required): Listing title. - `type` (string, required): Listing property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Listing property type group, as returned by the GET /api/v1/references/types endpoint. - `location` (object, required): Information about property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required): Information about all the parent locations (including property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `address` (string, required): Property address. - `zip_code` (string, required): The location zip code. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `coordinates` (object, required): Property coordinates. - `latitude` (number, required): Latitude. - `longitude` (number, required): Longitude. - `condition` (string, required): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `contacts_info` (object, required): Information about listing contacts. - `name` (string, required): The owner name. Only for FSBO listings. - `email` (string (email), required): The email contact. - `phone` (string, required): The phone contact. - `total_area` (integer, required): Total area. - `living_area` (integer, required): Living area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `rooms` (integer, required): Number of rooms. - `bathrooms` (integer, required): Number of bathrooms. - `features` (object, required): Property features, as returned by the GET /api/v1/references/features endpoint. - `floor` (string, required): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, required): Property view orientation. Values: `exterior`, `interior`. - `view` (string, required): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], required): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, required): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], required): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], required): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `construction_year` (integer, required): Construction year. - `operations` (string[], required): Operation types for which listing property is available. Values: `sale`, `rent`. - `is_bank_property` (boolean, required): Whether the listing property is a bank property. - `is_auction_property` (boolean, required): Whether the listing property is an auction property. - `is_new_development_property` (boolean, required): Whether the listing property is a new development property. - `is_private_property` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `sale_status` (string, required): Current sale status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price_base` (integer, required): Current sale price, in Euros. - `sale_price` (integer, required): Current sale price, in the currency of the listing (specified by the `sale_currency` field). - `sale_price_per_sqm` (number, required): Current sale price per square meter, in the currency of the listing (specified by the `sale_currency` field). - `sale_price_per_sqm_base` (number, required): Current sale price per square meter, in Euros. - `rent_status` (string, required): Current rent status of the listing. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `rent_currency` (string, required): Rent price currency code. - `rent_price_base` (integer, required): Current rent price, in Euros. - `rent_price` (integer, required): Current rent price, in the currency of the listing (specified by the `rent_currency` field). - `rent_price_per_sqm` (number, required): Current rent price per square meter, in the currency of the listing (specified by the `rent_currency` field). - `rent_price_per_sqm_base` (number, required): Current rent price per square meter, in Euros. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `fortnight`, `month`, `year`, `none`. - `agency_legal_id` (string, required): Agency legal identifier specified on the source. Only for France and its overseas territories(DROM and COM). - `agency` (string, required): The company that manages the listing. - `agent` (string, required): The agent that manages the listing. - `source_name` (string, required): The name of the source. - `description` (string, required): Listing description. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `pictures` (string[], optional): List of the original picture image URLs. - `created_at` (string (date-time), required): Date and time when the alert was created (UTC). - `created_at_with_photos` (string (date-time), required): Date and time (UTC) when the alert was created and its photos were processed. Can be `null` if photo processing has not finished yet. If the listing has no photos but the system has finished the processing, this field will contain its date and time. - `updated_at` (string (date-time), required): Date and time when the alert data was updated (UTC). - `energy_certificate` (string, required): Energy certificate classification that attests to the energy efficiency of a listing. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** - `energy_rating` (string, required): Energy rating that attests to the energy efficiency of a listing. - `heating_type` (string, required): Type of heating. - `available_from` (string (date), required): The date the listing property becomes available for occupancy. The start of the availability window. - `available_to` (string (date), required): The date the listing property stops being available. The end of the availability window. Example from the API description (long arrays shortened): ```json { "count": 79, "next": "http://api.casafari.com/v1/listing-alerts/feeds/887?alert_date_from=2021-09-01&limit=50&offset=50", "results": [ { "alert_id": 412269711, "listing_id": 110358519, "title": "Apartamento T2 em Santa Engracia", "ref": "ID-124021076-47", "alert_type": "sale_price", "alert_subtype": "price_down", "old_value": "549000", "new_value": "545000", "alert_date": "2021-10-24", "alert_date_and_time": "2021-10-24T05:37:09", "created_at": "2021-10-24T05:38:53.273581", "created_at_with_photos": "2021-10-24T05:43:27.622175", "updated_at": "2021-04-05T17:47:19.191211", "property_url": "https://www.casafari.com/home-sale/property-51277418", "listing_url": "https://www.idealista.pt/imovel/31407575/", "listing_uid": "1054046", "property_id": 51277418, "type": "apartment", "type_group": "apartment", "location": { "location_id": 28649, "name": "Santa Engrácia", "administrative_level": "Localidade", "zip_codes": [] }, "locations_structure": [ { "location_id": 499, "name": "Portugal", "administrative_level": "País", "zip_codes": [ "1200-224" ] } ], "address": "", "zip_code": "80804", "cadastral_reference": "2181605VK4728A0001TA", "coordinates": { "latitude": 38.7194, "longitude": -9.12209 }, "condition": "used", "contacts_info": { "phone": "215551538" }, "total_area": 130, "living_area": 128, "plot_area": 0, "terrace_area": 15, "bedrooms": 3, "rooms": 0, "bathrooms": 2, "features": { "floor": "middle", "views": [ "city" ], "directions": [ "west" ], "characteristics": [ "balcony" ] }, "construction_year": 2015, "operations": [ "sale" ], "is_bank_property": false, "is_auction_property": false, "is_new_development_property": false, "is_private_property": false, "sale_status": "active", "sale_currency": "EUR", "sale_price": 545000, "sale_price_base": 545000, "sale_price_per_sqm": 4192, "sale_price_per_sqm_base": 4192, "rent_status": "none", "rent_currency": "EUR", "rent_price": 0, "rent_price_base": 0, "rent_price_per_sqm": 0, "rent_price_per_sqm_base": 0, "rent_period": "none", "agency_legal_id": "402016653", "agency": "Helena Almeida Pires", "agent": "", "source_name": "Idealista", "description": "O apartamento é composto de sala de estar e jantar ampla, com janelas de vidro duplo que dão enorme luminosidade, ao ambiente.", "thumbnails": [ "https://st2.retelligence.co/c/2875/4/7f/5a0fc6ebf8e4e41d062342a29b50647f350.jpg" ], "pictures": [ "https://media.casasapo.pt/Z1140x855/Wnone/S5/C2729/P20091734/Tphoto/ID56933201-0000-0500-0000-00000d1ffcdc.jpg" ], "energy_certificate": "B", "energy_rating": "B", "heating_type": "Central heating", "available_from": "2026-07-01", "available_to": "2027-06-30" } ] } ``` ### 400 Bad Request Type: `object`. - `errors` (object, optional): Description of the errors encountered. ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 404 Not Found Type: `object`. - `errors` (object, optional): Description of the errors encountered. --- # Delete feed (v1) `DELETE https://api.casafari.com/api/v1/listing-alerts/feeds/{id}` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Delete alerts feed (by feed ID) for currently authenticated user. ## Path parameters - `id` (string, required): A unique integer value identifying this alerts feed. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X DELETE "https://api.casafari.com/api/v1/listing-alerts/feeds/" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object`. - `success` (boolean, optional): Boolean indicating whether the delete action was successful. ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 404 Not Found Type: `object`. - `errors` (object, optional): Description of the errors encountered. --- # Update feed (v1) `PUT https://api.casafari.com/api/v1/listing-alerts/feeds/{id}/update` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Update alerts feed by id. ## Path parameters - `id` (string, required): A unique integer value identifying this alerts feed. ## Request body Content type `application/json`. Optional. Type: `object`. - `name` (string, required): Name of the feed. at most 200 characters. - `filter` (object, required): Set of clauses to filter alerts. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `location_ids` (integer[], optional): List of location IDs, as returned by the POST /api/v1/references/locations endpoint. at most 100 items; 1–2147483647. - `custom_location` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. **This field is deprecated and will be removed in the next major update.** **Please, use `custom_locations` field instead.** at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `custom_locations` (object[][], optional): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. at most 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `types` (string[], optional): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `alert_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `alert_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `created_at_from` (string (date-time), optional): Start date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_to` (string (date-time), optional): End date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_with_photos_from` (string (date-time), optional): Start date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `created_at_with_photos_to` (string (date-time), optional): End date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `statuses` (string[], optional): Current status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `rented`. - `price_from` (integer, optional): Minimum price value. 1–2147483647. - `price_to` (integer, optional): Maximum price value. 1–2147483647. - `price_per_sqm_from` (integer, optional): Minimum value for price per square meter. 1–2147483647. - `price_per_sqm_to` (integer, optional): Maximum value for price per square meter. 1–2147483647. - `bedrooms_from` (integer, optional): Minimum number of bedrooms. 0–15000. - `bedrooms_to` (integer, optional): Maximum number of bedrooms. 0–15000. - `bathrooms_from` (integer, optional): Minimum number of bathrooms. 1–15000. - `bathrooms_to` (integer, optional): Maximum number of bathrooms. 1–15000. - `total_area_from` (integer, optional): Minimum total area. 1–10000000. - `total_area_to` (integer, optional): Maximum total area. 1–10000000. - `plot_area_from` (integer, optional): Minimum plot area. 1–10000000. - `plot_area_to` (integer, optional): Maximum plot area. 1–10000000. - `construction_year_from` (integer, optional): Minimum construction year. 1–3000. - `construction_year_to` (integer, optional): Maximum construction year. 1–3000. - `floor` (string, optional): Floor type of the property. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional) Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional) Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional) Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], optional): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `alert_subtypes` (string[], optional): Alert subtypes. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `private` (boolean, optional): Whether to return alerts only from properties listed by a private individual, as opposed to an agent or a professional. - `auction` (boolean, optional): Whether to return alerts from auction property listings. - `bank` (boolean, optional): Whether to return alerts from bank property listings. - `new_development` (boolean, optional): Whether to return alerts from new development property listings. - `listing_agents` (string[], optional): Return alerts only for properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint. - `with_agencies` (string[], optional): Return alerts only for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude alerts for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclusive` (boolean, optional): Whether to return alerts exclusively from specific listings rather than from all related to the property listings. Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `has_phone` (boolean, optional): Whether to return alerts only from listings with or without `phone` number. - `has_email` (boolean, optional): Whether to return alerts only from listings with or without email. - `has_agency_name` (boolean, optional): Whether to return alerts only from listings with or without agency name. - `property_ids` (integer[], optional): List of property IDs. at most 100 items; ≥ 1. - `listing_ids` (integer[], optional): List of listing IDs. at most 100 items; ≥ 1. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X PUT "https://api.casafari.com/api/v1/listing-alerts/feeds//update" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Apartments for sale in Cascais, Oeiras, Lisbon", "filter": { "operation": "sale", "types": [ "apartment", "studio", "duplex", "penthouse" ], "location_ids": [ 2942, 1861, 1600 ], "conditions": [ "used", "very-good", "new" ], "statuses": [ "active", "reserved" ], "price_from": 150000, "price_to": 800000, "price_per_sqm_from": 2000, "price_per_sqm_to": 8000, "bedrooms_from": 1, "bedrooms_to": 3, "total_area_from": 30, "total_area_to": 130, "construction_year_from": 1950, "floors": [ "middle", "top" ], "views": [ "city" ], "directions": [ "west", "south" ], "characteristics": [ "balcony", "elevator", "parking" ], "private": false, "new_development": false, "has_agency_name": true, "has_email": false, "without_agencies": [ "Airbnb", "Casa.Sapo" ] } }' ``` ## Responses ### 200 OK Type: `object`. - `id` (integer, optional) - `name` (string, required): Name of the feed. at most 200 characters. - `filter` (object, required): Set of clauses to filter alerts. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `location_ids` (integer[], optional): List of location IDs, as returned by the POST /api/v1/references/locations endpoint. at most 100 items; 1–2147483647. - `custom_location` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. **This field is deprecated and will be removed in the next major update.** **Please, use `custom_locations` field instead.** at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `custom_locations` (object[][], optional): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. at most 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `types` (string[], optional): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `alert_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `alert_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `created_at_from` (string (date-time), optional): Start date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_to` (string (date-time), optional): End date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_with_photos_from` (string (date-time), optional): Start date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `created_at_with_photos_to` (string (date-time), optional): End date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `statuses` (string[], optional): Current status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `rented`. - `price_from` (integer, optional): Minimum price value. 1–2147483647. - `price_to` (integer, optional): Maximum price value. 1–2147483647. - `price_per_sqm_from` (integer, optional): Minimum value for price per square meter. 1–2147483647. - `price_per_sqm_to` (integer, optional): Maximum value for price per square meter. 1–2147483647. - `bedrooms_from` (integer, optional): Minimum number of bedrooms. 0–15000. - `bedrooms_to` (integer, optional): Maximum number of bedrooms. 0–15000. - `bathrooms_from` (integer, optional): Minimum number of bathrooms. 1–15000. - `bathrooms_to` (integer, optional): Maximum number of bathrooms. 1–15000. - `total_area_from` (integer, optional): Minimum total area. 1–10000000. - `total_area_to` (integer, optional): Maximum total area. 1–10000000. - `plot_area_from` (integer, optional): Minimum plot area. 1–10000000. - `plot_area_to` (integer, optional): Maximum plot area. 1–10000000. - `construction_year_from` (integer, optional): Minimum construction year. 1–3000. - `construction_year_to` (integer, optional): Maximum construction year. 1–3000. - `floor` (string, optional): Floor type of the property. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional) Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional) Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional) Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], optional): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `alert_subtypes` (string[], optional): Alert subtypes. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `private` (boolean, optional): Whether to return alerts only from properties listed by a private individual, as opposed to an agent or a professional. - `auction` (boolean, optional): Whether to return alerts from auction property listings. - `bank` (boolean, optional): Whether to return alerts from bank property listings. - `new_development` (boolean, optional): Whether to return alerts from new development property listings. - `listing_agents` (string[], optional): Return alerts only for properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint. - `with_agencies` (string[], optional): Return alerts only for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude alerts for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclusive` (boolean, optional): Whether to return alerts exclusively from specific listings rather than from all related to the property listings. Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `has_phone` (boolean, optional): Whether to return alerts only from listings with or without `phone` number. - `has_email` (boolean, optional): Whether to return alerts only from listings with or without email. - `has_agency_name` (boolean, optional): Whether to return alerts only from listings with or without agency name. - `property_ids` (integer[], optional): List of property IDs. at most 100 items; ≥ 1. - `listing_ids` (integer[], optional): List of listing IDs. at most 100 items; ≥ 1. - `user` (string (email), optional) Example from the API description (long arrays shortened): ```json { "id": 887, "name": "Apartments for sale in Cascais, Oeiras, Lisbon", "filter": { "operation": "sale", "types": [ "apartment", "studio" ], "location_ids": [ 2942, 1861 ], "conditions": [ "used", "very-good" ], "statuses": [ "active", "reserved" ], "price_from": 150000, "price_to": 800000, "price_per_sqm_from": 2000, "price_per_sqm_to": 8000, "bedrooms_from": 1, "bedrooms_to": 3, "total_area_from": 30, "total_area_to": 130, "construction_year_from": 1950, "floors": [ "middle", "top" ], "views": [ "city" ], "directions": [ "west", "south" ], "characteristics": [ "balcony", "elevator" ], "private": false, "new_development": false, "has_agency_name": true, "has_email": false, "without_agencies": [ "Airbnb", "Casa.Sapo" ] }, "user": "user@email.com" } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 404 Not Found Type: `object`. - `detail` (string, optional): Not found. --- # Search alerts (v1) `POST https://api.casafari.com/api/v1/listing-alerts/search` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Returns paginated list of alerts (by requested parameters) for currently authenticated user. ## Query parameters - `limit` (integer, optional): Number of results to return per page. ≤ 100; default 20. - `offset` (integer, optional): The initial index from which to return the results. ≤ 50000. - `order_by` (string, optional): The field by which to sort the results. Values: `alert_date`, `-alert_date`, `alert_id`, `-alert_id`, `created_at`, `-created_at`, `updated_at`, `-updated_at`. default "-alert_date". - `alert_subtype` (string, optional): Get only alerts of the specific subtype. Invalid values are ignored. **This field is deprecated and will be removed in the next major update.** **Please, use `alert_subtypes` field in the body parameters instead.** Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. ## Request body Content type `application/json`. Optional. Type: `object`. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `location_ids` (integer[], optional): List of location IDs, as returned by the POST /api/v1/references/locations endpoint. at most 100 items; 1–2147483647. - `custom_location` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. **This field is deprecated and will be removed in the next major update.** **Please, use `custom_locations` field instead.** at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `custom_locations` (object[][], optional): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. at most 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `types` (string[], optional): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `alert_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `alert_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `created_at_from` (string (date-time), optional): Start date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_to` (string (date-time), optional): End date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_with_photos_from` (string (date-time), optional): Start date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `created_at_with_photos_to` (string (date-time), optional): End date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `statuses` (string[], optional): Current status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `rented`. - `price_from` (integer, optional): Minimum price value. 1–2147483647. - `price_to` (integer, optional): Maximum price value. 1–2147483647. - `price_per_sqm_from` (integer, optional): Minimum value for price per square meter. 1–2147483647. - `price_per_sqm_to` (integer, optional): Maximum value for price per square meter. 1–2147483647. - `bedrooms_from` (integer, optional): Minimum number of bedrooms. 0–15000. - `bedrooms_to` (integer, optional): Maximum number of bedrooms. 0–15000. - `bathrooms_from` (integer, optional): Minimum number of bathrooms. 1–15000. - `bathrooms_to` (integer, optional): Maximum number of bathrooms. 1–15000. - `total_area_from` (integer, optional): Minimum total area. 1–10000000. - `total_area_to` (integer, optional): Maximum total area. 1–10000000. - `plot_area_from` (integer, optional): Minimum plot area. 1–10000000. - `plot_area_to` (integer, optional): Maximum plot area. 1–10000000. - `construction_year_from` (integer, optional): Minimum construction year. 1–3000. - `construction_year_to` (integer, optional): Maximum construction year. 1–3000. - `floor` (string, optional): Floor type. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. " **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.**" Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. " **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], optional): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `alert_subtypes` (string[], optional): Alert subtypes. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `private` (boolean, optional): Whether to return alerts only from properties listed by a private individual, as opposed to an agent or a professional. - `auction` (boolean, optional): Whether to return alerts from auction property listings. - `bank` (boolean, optional): Whether to return alerts from bank property listings. - `new_development` (boolean, optional): Whether to return alerts from new development property listings. - `listing_agents` (string[], optional): Return alerts only for properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint. - `with_agencies` (string[], optional): Return alerts only for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude alerts for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclusive` (boolean, optional): Whether to return alerts exclusively from specific listings rather than from all related to the property listings. Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `has_phone` (boolean, optional): Whether to return alerts only from listings with or without `phone` number. - `has_email` (boolean, optional): Whether to return alerts only from listings with or without email. - `has_agency_name` (boolean, optional): Whether to return alerts only from listings with or without agency name. - `property_ids` (integer[], optional): List of property IDs. at most 100 items; ≥ 1. - `listing_ids` (integer[], optional): List of listing IDs. at most 100 items; ≥ 1. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/listing-alerts/search" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "operation": "sale", "types": [ "apartment", "studio", "duplex", "penthouse" ], "location_ids": [ 2942, 1861, 1600 ], "conditions": [ "used", "very-good", "new" ], "statuses": [ "active", "reserved" ], "price_from": 150000, "price_to": 800000, "price_per_sqm_from": 2000, "price_per_sqm_to": 8000, "bedrooms_from": 1, "bedrooms_to": 3, "total_area_from": 30, "total_area_to": 130, "construction_year_from": 1950, "floors": [ "middle", "top" ], "views": [ "city" ], "directions": [ "west", "south" ], "characteristics": [ "balcony", "elevator", "parking" ], "private": false, "new_development": false, "has_agency_name": true, "has_email": false, "without_agencies": [ "Airbnb", "Casa.Sapo" ], "alert_date_from": "2021-09-01" }' ``` ## Responses ### 200 OK Type: `object[]`. - `count` (integer, optional) - `next` (string (uri), optional, nullable) - `previous` (string (uri), optional, nullable) - `results` (object, optional) - `alert_id` (integer, required): ID of the alert. - `listing_id` (integer, required): ID of the listing (ad). - `ref` (string, required): The reference ID of the listing. - `alert_type` (string, required): The type of the alert. Values: `sale_price`, `sale_status`, `rent_price`, `rent_status`, `new`. - `alert_subtype` (string, required): The subtype of the alert. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `old_value` (string, required): Value before change. - `new_value` (string, required): Value after change. - `alert_date` (string (date), required): Date when the alert occurred. - `alert_date_and_time` (string, optional, nullable): Date and time when the alert occurred. - `property_url` (string, optional, nullable): URL of the property in the CASAFARI website. - `listing_url` (string, optional, nullable): URL of the listing. Available only for currently active listings. - `listing_old_url` (string, optional, nullable): Old URL of the listing. Available only for currently inactive listings. - `listing_uid` (string, required): Unique ID of the listing on the source site. - `property_id` (integer, required): ID of the property to which the listing belongs. - `title` (string, required): Listing title. - `type` (string, required): Listing property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Listing property type group, as returned by the GET /api/v1/references/types endpoint. - `location` (object, required): Information about property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required): Information about all the parent locations (including property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `address` (string, required): Property address. - `zip_code` (string, required): The location zip code. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `coordinates` (object, required): Property coordinates. - `latitude` (number, required): Latitude. - `longitude` (number, required): Longitude. - `condition` (string, required): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `contacts_info` (object, required): Information about listing contacts. - `name` (string, required): The owner name. Only for FSBO listings. - `email` (string (email), required): The email contact. - `phone` (string, required): The phone contact. - `total_area` (integer, required): Total area. - `living_area` (integer, required): Living area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `rooms` (integer, required): Number of rooms. - `bathrooms` (integer, required): Number of bathrooms. - `features` (object, required): Property features, as returned by the GET /api/v1/references/features endpoint. - `floor` (string, required): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, required): Property view orientation. Values: `exterior`, `interior`. - `view` (string, required): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], required): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, required): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], required): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], required): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `construction_year` (integer, required): Construction year. - `operations` (string[], required): Operation types for which listing property is available. Values: `sale`, `rent`. - `is_bank_property` (boolean, required): Whether the listing property is a bank property. - `is_auction_property` (boolean, required): Whether the listing property is an auction property. - `is_new_development_property` (boolean, required): Whether the listing property is a new development property. - `is_private_property` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `sale_status` (string, required): Current sale status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price_base` (integer, required): Current sale price, in Euros. - `sale_price` (integer, required): Current sale price, in the currency of the listing (specified by the `sale_currency` field). - `sale_price_per_sqm` (number, required): Current sale price per square meter, in the currency of the listing (specified by the `sale_currency` field). - `sale_price_per_sqm_base` (number, required): Current sale price per square meter, in Euros. - `rent_status` (string, required): Current rent status of the listing. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `rent_currency` (string, required): Rent price currency code. - `rent_price_base` (integer, required): Current rent price, in Euros. - `rent_price` (integer, required): Current rent price, in the currency of the listing (specified by the `rent_currency` field). - `rent_price_per_sqm` (number, required): Current rent price per square meter, in the currency of the listing (specified by the `rent_currency` field). - `rent_price_per_sqm_base` (number, required): Current rent price per square meter, in Euros. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `fortnight`, `month`, `year`, `none`. - `agency_legal_id` (string, required): Agency legal identifier specified on the source. Only for France and its overseas territories(DROM and COM). - `agency` (string, required): The company that manages the listing. - `agent` (string, required): The agent that manages the listing. - `source_name` (string, required): The name of the source. - `description` (string, required): Listing description. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `pictures` (string[], optional): List of the original picture image URLs. - `created_at` (string (date-time), required): Date and time when the alert was created (UTC). - `created_at_with_photos` (string (date-time), required): Date and time (UTC) when the alert was created and its photos were processed. Can be `null` if photo processing has not finished yet. If the listing has no photos but the system has finished the processing, this field will contain its date and time. - `updated_at` (string (date-time), required): Date and time when the alert data was updated (UTC). - `energy_certificate` (string, required): Energy certificate classification that attests to the energy efficiency of a listing. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** - `energy_rating` (string, required): Energy rating that attests to the energy efficiency of a listing. - `heating_type` (string, required): Type of heating. - `available_from` (string (date), required): The date the listing property becomes available for occupancy. The start of the availability window. - `available_to` (string (date), required): The date the listing property stops being available. The end of the availability window. Example from the API description (long arrays shortened): ```json { "count": 79, "next": "https://api.casafari.com/v1/listing-alerts/search?limit=50&offset=50", "results": [ { "alert_id": 412269711, "listing_id": 110358519, "title": "Apartamento T2 em Santa Engracia", "ref": "ID-124021076-47", "alert_type": "sale_price", "alert_subtype": "price_down", "old_value": "549000", "new_value": "545000", "alert_date": "2021-10-24", "alert_date_and_time": "2021-10-24T05:37:09", "created_at": "2021-10-24T05:38:53.273581", "created_at_with_photos": "2021-10-24T05:43:27.622175", "updated_at": "2021-04-05T17:47:19.191211", "property_url": "https://www.casafari.com/home-sale/property-51277418", "listing_url": "https://www.idealista.pt/imovel/31407575/", "listing_uid": "1054046", "property_id": 51277418, "type": "apartment", "type_group": "apartment", "location": { "location_id": 28649, "name": "Santa Engrácia", "administrative_level": "Localidade", "zip_codes": [] }, "locations_structure": [ { "location_id": 499, "name": "Portugal", "administrative_level": "País", "zip_codes": [ "1200-224" ] } ], "address": "", "zip_code": "80804", "cadastral_reference": "2181605VK4728A0001TA", "coordinates": { "latitude": 38.7194, "longitude": -9.12209 }, "condition": "used", "contacts_info": { "phone": "215551538" }, "total_area": 130, "living_area": 128, "plot_area": 0, "terrace_area": 15, "bedrooms": 3, "rooms": 0, "bathrooms": 2, "features": { "floor": "middle", "views": [ "city" ], "directions": [ "west" ], "characteristics": [ "balcony" ] }, "construction_year": 2015, "operations": [ "sale" ], "is_bank_property": false, "is_auction_property": false, "is_new_development_property": false, "is_private_property": false, "sale_status": "active", "sale_currency": "EUR", "sale_price": 545000, "sale_price_base": 545000, "sale_price_per_sqm": 4192, "sale_price_per_sqm_base": 4192, "rent_status": "none", "rent_currency": "EUR", "rent_price": 0, "rent_price_base": 0, "rent_price_per_sqm": 0, "rent_price_per_sqm_base": 0, "rent_period": "none", "agency_legal_id": "402016653", "agency": "Helena Almeida Pires", "agent": "", "source_name": "Idealista", "description": "O apartamento é composto de sala de estar e jantar ampla, com janelas de vidro duplo que dão enorme luminosidade, ao ambiente.", "thumbnails": [ "https://st2.retelligence.co/c/2875/4/7f/5a0fc6ebf8e4e41d062342a29b50647f350.jpg" ], "pictures": [ "https://media.casasapo.pt/Z1140x855/Wnone/S5/C2729/P20091734/Tphoto/ID56933201-0000-0500-0000-00000d1ffcdc.jpg" ], "energy_certificate": "B", "energy_rating": "B", "heating_type": "Central heating", "available_from": "2026-07-01", "available_to": "2027-06-30" } ] } ``` ### 400 Bad Request Type: `object`. - `errors` (object, optional): Description of the errors encountered. ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. --- # List feeds `GET https://api.casafari.com/alerts-api/feeds` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Returns a paginated list of feeds, sorted newest first. Follow `next_url` directly to get the next page - it is an opaque URL, do not construct it manually. ## Query parameters - `cursor` (string, optional, nullable) - `limit` (integer, optional): Number of feeds to return per page. 1–100; default 20. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/alerts-api/feeds" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 Successful Response Type: `object`. - `feeds` (object[], required) - `id` (integer, required) - `feed_name` (string, required) - `created_at` (string (date-time), required) - `updated_at` (string (date-time), required) - `next_url` (string, optional, nullable) ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [Can I get alerts (new properties, price cuts, sales) over Casafari MCP?](/docs/faq/alerts-over-mcp) - [How do I get alerts delivered to a webhook?](/docs/faq/alerts-webhook) --- # Create feed `POST https://api.casafari.com/alerts-api/feeds` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Create a new alert feed that delivers matching real estate events to your webhook URL. ## Alert Delivery Format Events are delivered as a **POST** request with a single JSON object body: ```json { "alert_id": 100042, "url": "https://www.casafari.com/listing/12345", "address": "Rua do Exemplo 12, Lisbon", "location": "Lisbon", "sale_status": "active", "sale_price": 250000, "sale_price_psqm": 2500.0, "sale_currency": "EUR", "rent_status": "none", "rent_price": 0, "rent_period": "none", "rent_price_psqm": 0.0, "rent_currency": "EUR", "thumbnails": [ "https://cdn.example.com/thumb1.jpg" ], "matched_feeds": [ { "feed_id": 42, "feed_name": "My Alert Feed" } ] } ``` Your server must respond with HTTP **200**. Any other status code is treated as a failure. ## Before You Start: Configure Your Webhook Feeds deliver to your **per-user webhook URL** — one URL for all feeds, managed separately: 1. `PUT /webhooks` — set your delivery URL (it is probed with a GET and must answer 200) 2. Create feeds — this endpoint returns **409** until the webhook is configured Changing the URL via `PUT /webhooks` instantly affects all feeds, including already-queued alerts. ## Retry Policy If your server does not respond with HTTP 200 within **5 seconds**, delivery is retried — **60 seconds** after the first failure, then every **10 minutes** — until the alert expires (typically 24h). Feeds are never disabled automatically. ## Authentication of deliveries Every delivery is signed with [Standard Webhooks](https://www.standardwebhooks.com/): each POST carries `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. Verify the HMAC-SHA256 signature over the raw request body using the secret from `PUT /webhooks` (rotate it via `POST /webhooks/rotate-secret`). ## Request body Content type `application/json`. Required. Type: `object`. - `feed_name` (string, required) - `filters` (object, required) - `location_ids` (integer[], optional, nullable) 1–100 items. - `types` (string[], optional, nullable) Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `building`, `other_commercial`, `restaurant`, `werkstatt`, `urban_plot`, `rural_plot`, `room`, `parking`, `garage`, `other`, `apartment_building`, `office_building`, `mix_use_building`, `apartment_development`, `house_development`. at least 1 item. - `business_type` (string, required) Values: `sale`, `rent`. - `statuses` ((string | string)[], optional, nullable) at least 1 item. - `alert_subtypes` (string[], optional, nullable) Values: `new`, `price_increased`, `price_decreased`, `reserved`, `delisted`, `sold`. - `custom_locations` (object[][], optional, nullable): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. 1–4 items; 4–25 items. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `private` (boolean, optional, nullable) - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_psqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `new_development` (boolean, optional, nullable) - `bank` (boolean, optional, nullable) - `auction` (boolean, optional, nullable) - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `floors` (string[], optional, nullable) Values: `no_floor`, `ground`, `middle`, `top`. at least 1 item. - `conditions` (string[], optional, nullable) Values: `new`, `used`, `ruin`, `very-good`, `other`. at least 1 item. - `orientation` (string, optional, nullable) Values: `exterior`, `interior`. - `views` (string[], optional, nullable): A matching listing must have every requested view, not just one. Values: `water`, `landscape`, `city`, `golf`, `park`. at least 1 item. - `directions` (string[], optional, nullable): A matching listing must face every requested direction, not just one. Values: `north`, `south`, `east`, `west`. at least 1 item. - `characteristics` (string[], optional, nullable): A matching listing must have every requested characteristic, not just one. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. at least 1 item. - `has_phone` (boolean, optional, nullable) - `has_email` (boolean, optional, nullable) - `has_agency_name` (boolean, optional, nullable) - `ref_numbers` (string[], optional, nullable) 1–100 items. - `listing_ids` (integer[], optional, nullable) 1–100 items. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/alerts-api/feeds" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "feed_name": "", "filters": { "business_type": "sale" } }' ``` ## Responses ### 200 Successful Response Type: `object`. - `feed_id` (integer, required) - `feed_name` (string, required) - `filters` (object, required) - `location_ids` (integer[], optional, nullable) 1–100 items. - `types` (string[], optional, nullable) Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `building`, `other_commercial`, `restaurant`, `werkstatt`, `urban_plot`, `rural_plot`, `room`, `parking`, `garage`, `other`, `apartment_building`, `office_building`, `mix_use_building`, `apartment_development`, `house_development`. at least 1 item. - `business_type` (string, required) Values: `sale`, `rent`. - `statuses` ((string | string)[], optional, nullable) at least 1 item. - `alert_subtypes` (string[], optional, nullable) Values: `new`, `price_increased`, `price_decreased`, `reserved`, `delisted`, `sold`. - `custom_locations` (object[][], optional, nullable): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. 1–4 items; 4–25 items. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `private` (boolean, optional, nullable) - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_psqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `new_development` (boolean, optional, nullable) - `bank` (boolean, optional, nullable) - `auction` (boolean, optional, nullable) - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `floors` (string[], optional, nullable) Values: `no_floor`, `ground`, `middle`, `top`. at least 1 item. - `conditions` (string[], optional, nullable) Values: `new`, `used`, `ruin`, `very-good`, `other`. at least 1 item. - `orientation` (string, optional, nullable) Values: `exterior`, `interior`. - `views` (string[], optional, nullable): A matching listing must have every requested view, not just one. Values: `water`, `landscape`, `city`, `golf`, `park`. at least 1 item. - `directions` (string[], optional, nullable): A matching listing must face every requested direction, not just one. Values: `north`, `south`, `east`, `west`. at least 1 item. - `characteristics` (string[], optional, nullable): A matching listing must have every requested characteristic, not just one. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. at least 1 item. - `has_phone` (boolean, optional, nullable) - `has_email` (boolean, optional, nullable) - `has_agency_name` (boolean, optional, nullable) - `ref_numbers` (string[], optional, nullable) 1–100 items. - `listing_ids` (integer[], optional, nullable) 1–100 items. ### 409 Webhook is not configured. Type: `object`. - `detail` (string, required) Example from the API description: ```json { "detail": "No webhook configured. Set your delivery URL via PUT /webhooks first." } ``` ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [Can I get alerts (new properties, price cuts, sales) over Casafari MCP?](/docs/faq/alerts-over-mcp) - [How do I get alerts delivered to a webhook?](/docs/faq/alerts-webhook) --- # Get feed `GET https://api.casafari.com/alerts-api/feeds/{feed_id}` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Returns the feed configuration in the same format as it was originally created. Filters that were not set at creation time are omitted entirely (not returned as null); filters explicitly set to null are returned as null. ## Path parameters - `feed_id` (integer, required) ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/alerts-api/feeds/1" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 Successful Response Type: `object`. - `feed_id` (integer, required) - `feed_name` (string, required) - `filters` (object, required) - `location_ids` (integer[], optional, nullable) 1–100 items. - `types` (string[], optional, nullable) Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `building`, `other_commercial`, `restaurant`, `werkstatt`, `urban_plot`, `rural_plot`, `room`, `parking`, `garage`, `other`, `apartment_building`, `office_building`, `mix_use_building`, `apartment_development`, `house_development`. at least 1 item. - `business_type` (string, required) Values: `sale`, `rent`. - `statuses` ((string | string)[], optional, nullable) at least 1 item. - `alert_subtypes` (string[], optional, nullable) Values: `new`, `price_increased`, `price_decreased`, `reserved`, `delisted`, `sold`. - `custom_locations` (object[][], optional, nullable): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. 1–4 items; 4–25 items. - `latitude` (number, required) -90–90. - `longitude` (number, required) -180–180. - `private` (boolean, optional, nullable) - `price_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `price_psqm_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–2147483647. - `max` (integer, optional, nullable) 1–2147483647. - `bathrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–15000. - `max` (integer, optional, nullable) 1–15000. - `bedrooms_range` (object, optional, nullable) - `min` (integer, optional, nullable) 0–15000. - `max` (integer, optional, nullable) 0–15000. - `total_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `new_development` (boolean, optional, nullable) - `bank` (boolean, optional, nullable) - `auction` (boolean, optional, nullable) - `construction_year_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–3000. - `max` (integer, optional, nullable) 1–3000. - `plot_area_range` (object, optional, nullable) - `min` (integer, optional, nullable) 1–1000000. - `max` (integer, optional, nullable) 1–1000000. - `floors` (string[], optional, nullable) Values: `no_floor`, `ground`, `middle`, `top`. at least 1 item. - `conditions` (string[], optional, nullable) Values: `new`, `used`, `ruin`, `very-good`, `other`. at least 1 item. - `orientation` (string, optional, nullable) Values: `exterior`, `interior`. - `views` (string[], optional, nullable): A matching listing must have every requested view, not just one. Values: `water`, `landscape`, `city`, `golf`, `park`. at least 1 item. - `directions` (string[], optional, nullable): A matching listing must face every requested direction, not just one. Values: `north`, `south`, `east`, `west`. at least 1 item. - `characteristics` (string[], optional, nullable): A matching listing must have every requested characteristic, not just one. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. at least 1 item. - `has_phone` (boolean, optional, nullable) - `has_email` (boolean, optional, nullable) - `has_agency_name` (boolean, optional, nullable) - `ref_numbers` (string[], optional, nullable) 1–100 items. - `listing_ids` (integer[], optional, nullable) 1–100 items. ### 404 Feed not found. Type: `object`. - `detail` (string, required) Example from the API description: ```json { "detail": "Feed not found." } ``` ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [How do I get alerts delivered to a webhook?](/docs/faq/alerts-webhook) --- # Delete feed `DELETE https://api.casafari.com/alerts-api/feeds/{feed_id}` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Permanently removes the feed. No further alerts will be delivered for it. ## Path parameters - `feed_id` (integer, required) ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X DELETE "https://api.casafari.com/alerts-api/feeds/1" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 Successful Response Type: `object`. - `success` (boolean, required) ### 404 Feed not found. Type: `object`. - `detail` (string, required) Example from the API description: ```json { "detail": "Feed not found." } ``` ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [How do I get alerts delivered to a webhook?](/docs/faq/alerts-webhook) --- # Set webhook URL `PUT https://api.casafari.com/alerts-api/webhooks` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Sets (or replaces) the delivery URL for **all** your alert feeds. Before saving, a **GET** request is sent to the URL — your server must respond with HTTP **200**, otherwise this endpoint returns **400**. Alert deliveries themselves arrive as **POST** requests with a JSON array body. The URL is stored per user: changing it here instantly affects every feed, including alerts already queued for delivery. Feeds cannot be created until the webhook is configured. A signing secret is provisioned on the first call and returned in `secret` **once**; later calls return `secret: null`. Lost it? Use `POST /webhooks/rotate-secret`. ## Request body Content type `application/json`. Required. Type: `object`. - `url` (string (uri), required) 1–2083 characters. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X PUT "https://api.casafari.com/alerts-api/webhooks" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "" }' ``` ## Responses ### 200 Successful Response Type: `object`. - `url` (string, required) - `secret` (string, required) ### 400 Webhook URL verification failed. Type: `object`. - `detail` (string, required) Example from the API description: ```json { "detail": "Webhook URL verification failed: Expected HTTP 200, got 404." } ``` ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [Can I get alerts (new properties, price cuts, sales) over Casafari MCP?](/docs/faq/alerts-over-mcp) - [How do I get alerts delivered to a webhook?](/docs/faq/alerts-webhook) --- # Rotate signing secret `POST https://api.casafari.com/alerts-api/webhooks/rotate-secret` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Issues a new current signing secret. By default the previous secrets stay valid for a **24-hour grace window** so you can install the new key before removing the old one. Pass `{"immediate": true}` to revoke all previous secrets right away — use this only when a secret is compromised. ## Request body Content type `application/json`. Required. Type: `object`. - `immediate` (boolean, optional): When false (default), the previous secrets keep working for a 24-hour grace window so you can switch the new secret before the old one stops signing; deliveries carry a signature for each active secret meanwhile. When true, the previous secrets are revoked immediately and only the new one signs — use this only when a secret is compromised. default false. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/alerts-api/webhooks/rotate-secret" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "immediate": false }' ``` ## Responses ### 200 Successful Response Type: `object`. - `secret` (string, required) ### 422 Validation Error Type: `object`. - `detail` (object[], optional) - `loc` ((string | integer)[], required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (object, optional) ## Questions about this - [Can I get alerts (new properties, price cuts, sales) over Casafari MCP?](/docs/faq/alerts-over-mcp) - [How do I get alerts delivered to a webhook?](/docs/faq/alerts-webhook) --- # References The reference data requests are built from: property types, features and conditions, agencies, agents and the sources the graph is built from, locations with typeahead, and zip-code boundaries. 10 REST operations. ## REST API 10 operations in the public OpenAPI description, all under `https://api.casafari.com` with a bearer token ([how to get one](/docs/rest#get-a-token)). The same list with more detail: [References REST API](/docs/rest/references). - [`GET /api/v1/references/agencies`](/docs/rest/references/get-agencies-v1): Get agencies (v1). Returns a list of all possible agencies with user restrictions. - [`GET /api/v1/references/agents`](/docs/rest/references/get-agents-v1): Get agents (v1). Returns a list of all possible agents with user restrictions. - [`GET /api/v1/references/conditions`](/docs/rest/references/get-conditions-v1): Get conditions (v1). Returns a list of all possible estate conditions. - [`GET /api/v1/references/features`](/docs/rest/references/get-features-v1): Get features (v1). Returns a list of all possible property features. - [`POST /api/v1/references/locations`](/docs/rest/references/get-locations-v1): Get locations (v1). Returns a list of all possible locations with user restrictions. - [`GET /api/v1/references/locations/by-coordinates`](/docs/rest/references/get-location-by-passed-coordinates-v1): Get location by passed coordinates (v1). Returns a location for the given coordinates with user restrictions. - [`POST /api/v1/references/locations/typeahead`](/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1): Get locations typeahead suggestions scoped by country code (v1). Returns location typeahead suggestions within the given country (ES or PT). - [`GET /api/v1/references/sources`](/docs/rest/references/get-sources-v1): Get sources (v1). Returns a list of all domains for the requested location. - [`GET /api/v1/references/types`](/docs/rest/references/get-types-v1): Get types (v1). Returns a list of all possible estate types. - [`POST /api/v1/references/zipcode-boundary`](/docs/rest/references/get-zipcode-boundary-by-zipcode-and-country-code-v1): Get zipcode boundary by zipcode and country code (v1). Get zipcode boundary by zipcode and country code. ## MCP and REST compared Over MCP: 0 tools. Over REST: 10 operations. Available over REST only: MCP has no tool for it. - Related: [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead) and [`POST /api/v1/references/locations/typeahead`](/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1). Details: [MCP and REST compared](/docs/parity#references). ## Questions about this - [Which products does Casafari MCP offer, and how many tools are there?](/docs/faq/which-products) - [What are the References operations for?](/docs/faq/what-is-references) - [How do I turn a place name into a location id?](/docs/faq/location-ids) - [How do I build on the Casafari REST API?](/docs/faq/build-on-rest) --- # References REST API The reference data requests are built from: property types, features and conditions, agencies, agents and the sources the graph is built from, locations with typeahead, and zip-code boundaries. 10 operations, from the public OpenAPI description. Base URL `https://api.casafari.com`; every operation but sign-in needs a bearer token (see [the REST API overview](/docs/rest#get-a-token)). Over MCP, References has no tools: see [MCP and REST compared](/docs/parity#references). ## Operations - [`GET /api/v1/references/agencies`](/docs/rest/references/get-agencies-v1): Get agencies (v1). Returns a list of all possible agencies with user restrictions. - [`GET /api/v1/references/agents`](/docs/rest/references/get-agents-v1): Get agents (v1). Returns a list of all possible agents with user restrictions. - [`GET /api/v1/references/conditions`](/docs/rest/references/get-conditions-v1): Get conditions (v1). Returns a list of all possible estate conditions. - [`GET /api/v1/references/features`](/docs/rest/references/get-features-v1): Get features (v1). Returns a list of all possible property features. - [`POST /api/v1/references/locations`](/docs/rest/references/get-locations-v1): Get locations (v1). Returns a list of all possible locations with user restrictions. - [`GET /api/v1/references/locations/by-coordinates`](/docs/rest/references/get-location-by-passed-coordinates-v1): Get location by passed coordinates (v1). Returns a location for the given coordinates with user restrictions. - [`POST /api/v1/references/locations/typeahead`](/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1): Get locations typeahead suggestions scoped by country code (v1). Returns location typeahead suggestions within the given country (ES or PT). - [`GET /api/v1/references/sources`](/docs/rest/references/get-sources-v1): Get sources (v1). Returns a list of all domains for the requested location. - [`GET /api/v1/references/types`](/docs/rest/references/get-types-v1): Get types (v1). Returns a list of all possible estate types. - [`POST /api/v1/references/zipcode-boundary`](/docs/rest/references/get-zipcode-boundary-by-zipcode-and-country-code-v1): Get zipcode boundary by zipcode and country code (v1). Get zipcode boundary by zipcode and country code. ## Questions about this - [What are the References operations for?](/docs/faq/what-is-references) --- # Get agencies (v1) `GET https://api.casafari.com/api/v1/references/agencies` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#references). ## Description Returns a list of all possible agencies with user restrictions. ## Query parameters - `name` (string, required): A name of the agency to search. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/references/agencies?name=" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object[]`. - `name` (string, required): Name of the agency. - `agency_type` (string, required): Type of the agency. - `source_ids` (integer[], required): List of source IDs that belongs to the agency. Example from the API description: ```json { "agencies": [ { "name": "ComprarCasa Guimarães & Guimarães Centro", "agency_type": "company", "source_ids": [ 1616, 2492 ] }, { "name": "ComprarCasa Setúbal Estádio", "agency_type": "company", "source_ids": [ 1616 ] } ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [What are the References operations for?](/docs/faq/what-is-references) --- # Get agents (v1) `GET https://api.casafari.com/api/v1/references/agents` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#references). ## Description Returns a list of all possible agents with user restrictions. ## Query parameters - `name` (string, required): A name of the agent to search. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/references/agents?name=" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object[]`. - `agents` (string[], required): The list of suggested agents. Example from the API description: ```json { "agents": [ "Paulo Diogo", "Paulo Costa" ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. --- # Get conditions (v1) `GET https://api.casafari.com/api/v1/references/conditions` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#references). ## Description Returns a list of all possible estate conditions. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/references/conditions" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object[]`. - `conditions` (string[], required): List of condition names. Example from the API description (long arrays shortened): ```json { "conditions": [ "used", "ruin" ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [What are the References operations for?](/docs/faq/what-is-references) --- # Get features (v1) `GET https://api.casafari.com/api/v1/references/features` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#references). ## Description Returns a list of all possible property features. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/references/features" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object[]`. - `group` (string, required): Name of the group of features. - `names` (string[], required): List of feature names that belong to a specific group. Example from the API description (long arrays shortened): ```json { "features": [ { "group": "floor", "names": [ "no_floor", "ground" ] }, { "group": "orientation", "names": [ "exterior", "interior" ] } ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [What are the References operations for?](/docs/faq/what-is-references) --- # Get locations (v1) `POST https://api.casafari.com/api/v1/references/locations` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#references). ## Description Returns a list of all possible locations with user restrictions. ## Request body Content type `application/json`. Optional. Type: `object`. - `name` (string, optional): Location name to search. - `coordinates` (object[], optional): Limit search to locations within a closed polygon. First and last points must match. at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `zip_codes` (string[], optional): List of zip codes to filter by. at most 15 items. - `lang` (string, optional): Language to use for the location names in the response. (When the provided language is not supported, the results will be returned in English.) ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/references/locations" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "ferreiras", "coordinates": [ { "longitude": -8.183479, "latitude": 37.1404 }, { "longitude": -8.18482, "latitude": 37.13909 }, { "longitude": -8.1854, "latitude": 37.13805 }, { "longitude": -8.21646, "latitude": 37.11383 }, { "longitude": -8.183479, "latitude": 37.1404 } ], "lang": "pt" }' ``` ## Responses ### 200 OK Type: `object`. - `locations` (object[], required): List of location objects. - `location_id` (integer, required): ID of the location. - `name` (string, required): Name of the location. - `parent_id` (integer, required): ID of the parent level location. - `administrative_level` (string, required): Location administrative level. - `locations_structure` (object[], required): Information about all the parent locations, starting from the top-most level - country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `level` (integer, required): Location level as number. Example from the API description (long arrays shortened): ```json { "locations": [ { "location_id": 1603, "name": "Ferreiras", "parent_id": 1602, "administrative_level": "Freguesia", "locations_structure": [ { "location_id": 499, "name": "Portugal", "administrative_level": "País", "zip_codes": [ "1200-224" ], "level": 1 }, { "location_id": 1597, "name": "Faro", "administrative_level": "Distrito", "zip_codes": [], "level": 2 } ] } ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [What are the References operations for?](/docs/faq/what-is-references) - [How do I turn a place name into a location id?](/docs/faq/location-ids) --- # Get location by passed coordinates (v1) `GET https://api.casafari.com/api/v1/references/locations/by-coordinates` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#references). ## Description Returns a location for the given coordinates with user restrictions. ## Query parameters - `latitude` (number, required): The latitude coordinate. -90–90. - `longitude` (number, required): The longitude coordinate. -180–180. - `lang` (string, optional): Language to use for the location names in the response. (When the provided language is not supported, the results will be returned in English.) ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/references/locations/by-coordinates?latitude=&longitude=" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object`. - `location_id` (integer, required): ID of the location. - `name` (string, required): Name of the location. - `parent_id` (integer, required): ID of the parent level location. - `administrative_level` (string, required): Location administrative level. - `locations_structure` (object[], required): Information about all the parent locations, starting from the top-most level - country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `level` (integer, required): Location level as number. Example from the API description (long arrays shortened): ```json { "location_id": 1615, "name": "São Gonçalo de Lagos", "parent_id": 1611, "administrative_level": "Freguesia", "locations_structure": [ { "location_id": 499, "name": "Portugal", "administrative_level": "País", "zip_codes": [], "level": 1 }, { "location_id": 1597, "name": "Faro", "administrative_level": "Distrito", "zip_codes": [], "level": 2 } ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [How do I turn a place name into a location id?](/docs/faq/location-ids) --- # Get locations typeahead suggestions scoped by country code (v1) `POST https://api.casafari.com/api/v1/references/locations/typeahead` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead) (related). See [MCP and REST compared](/docs/parity#references). ## Description Returns location typeahead suggestions within the given country (ES or PT). ## Request body Content type `application/json`. Optional. Type: `object`. - `country_codes` (string[], required): Country codes to scope the search. Supported: ES, PT. Values: `ES`, `PT`. - `name` (string, required): The location name to search for. 2–100 characters. - `size` (integer, optional): The maximum number of suggestions to return. Default 30, maximum 100. 1–100; default 30. - `lang` (string, optional): Language to use for the location name in the response. One of: en, pt, es, de. Values: `en`, `pt`, `es`, `de`. default "en". ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/references/locations/typeahead" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "country_codes": [ "PT" ], "name": "lisboa", "lang": "en", "size": 30 }' ``` ## Responses ### 200 OK Type: `object`. - `typeahead` (object[], required): The typeahead suggestions. - `location_id` (integer, required): The location id. - `name` (string, required): The location name. - `matched_name` (string, required): The matched name of the location name. at most 256 characters. - `administrative_level` (string, required): The administrative level. - `breadcrumbs` (object[], required): Location breadcrumbs sorted from top to bottom. - `location_id` (integer, required): Location ID. - `name` (string, required): The name of location. Example from the API description: ```json { "typeahead": [ { "location_id": 1296, "name": "Lisboa", "matched_name": "Lisboa", "administrative_level": "Distrito", "breadcrumbs": [ { "location_id": 499, "name": "Portugal" }, { "location_id": 1296, "name": "Lisboa" } ] } ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [Which countries does Casafari cover?](/docs/faq/which-countries) - [Does Casafari cover Spain and Portugal?](/docs/faq/coverage-spain-portugal) - [Does every tool cover all 16 countries?](/docs/faq/per-tool-coverage) - [How do I turn a place name into a location id?](/docs/faq/location-ids) --- # Get sources (v1) `GET https://api.casafari.com/api/v1/references/sources` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#references). ## Description Returns a list of all domains for the requested location. ## Query parameters - `locationId` (integer, required): The location ID to search sources for. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/references/sources?locationId=1" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object[]`. - `domains` (string[], required): The domain urls. Example from the API description: ```json { "domains": [ "barnes-portugal.com" ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [What is the Casafari property graph, and where does the data come from?](/docs/faq/what-is-the-property-graph) --- # Get types (v1) `GET https://api.casafari.com/api/v1/references/types` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#references). ## Description Returns a list of all possible estate types. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl "https://api.casafari.com/api/v1/references/types" \ -H "Authorization: Bearer $CASAFARI_TOKEN" ``` ## Responses ### 200 OK Type: `object[]`. - `types` (object[], required): List of grouped property types. - `group` (string, required): Name of the group of types. - `names` (string[], required): List of type names that belong to a specific group. - `types_with_countries` (object[], required): List of type names with countries where each type is available. - `name` (string, required): Type name. - `countries` (string[], required): List of countries where the type is available. Example from the API description (long arrays shortened): ```json { "types": [ { "group": "apartment", "names": [ "apartment", "studio" ] }, { "group": "house", "names": [ "country_house", "house" ] } ], "types_with_countries": [ { "name": "apartment", "countries": [ "Portugal", "Spain" ] }, { "name": "studio", "countries": [ "Portugal", "Spain" ] } ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [What are the References operations for?](/docs/faq/what-is-references) - [Does Casafari cover rentals and commercial property?](/docs/faq/rentals-and-commercial) --- # Get zipcode boundary by zipcode and country code (v1) `POST https://api.casafari.com/api/v1/references/zipcode-boundary` [References](/docs/references) · [REST API](/docs/rest/references). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#references). ## Description Get zipcode boundary by zipcode and country code. ## Request body Content type `application/json`. Optional. Type: `object`. - `zip_code` (string, required): Zipcode. - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`, `FR`, `DE`, `RE`, `GP`, `MQ`, `GY`, `YT`, `AD`, `MC`. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/references/zipcode-boundary" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "zip_code": "36116", "country_code": "ES" }' ``` ## Responses ### 200 OK Type: `object`. - `zip_code` (string, required): Zipcode. - `boundary` (object[][], required): Zipcode boundary. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. Example from the API description (long arrays shortened): ```json { "zip_code": "36116", "boundary": [ [ { "latitude": 42.59448, "longitude": -8.3877 }, { "latitude": 42.58795, "longitude": -8.38622 } ] ] } ``` ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered. ## Questions about this - [What are the References operations for?](/docs/faq/what-is-references) --- # AgentGraph AI Find the real estate agencies and agents worth partnering with: area screens against partner profiles, full profiles, territory maps, partner briefs and watchlists. Product page: https://agentgraphai.shiny-bird-2f03.workers.dev/ 13 MCP tools. Markets named in the tools' own descriptions: Germany. ## How the MCP server describes itself What `list_servers` returns for this product (the server's own `initialize` instructions): > AgentGraph AI finds the real estate agencies and agents worth partnering with, from Casafari's listing data for Germany. Start with find_location, then screen_agencies (franchise partners, small teams) and screen_agents (individual brokers) for that area; open one with agency_profile or agent_profile using the id a screen returns. territory_map shows where business per broker is high and networks are thin; save_to_watchlist saves agencies and agents, and watchlist_changes says what changed since. list_profiles explains each partner profile's rules. Every figure counts homes, not portal listings: one home on three portals is one home. Exits are listings that ended in the last 12 months, sold or withdrawn; an explicit sold label is rare, so exits stand in for sales until closing prices are linked. Agent figures only cover listings that name the agent. Contacts are business contacts as printed on listings or kept in Casafari's directory; use them in line with your own data-protection obligations. ## MCP tools | Tool | Title | What it does | |---|---|---| | [`agentgraph_find_location`](/docs/agentgraph/find_location) | Find a German location | Finds German cities, districts and states by name and returns their location ids, kinds and parent areas. | | [`agentgraph_list_profiles`](/docs/agentgraph/list_profiles) | Partner profiles | Lists the partner profiles the screens match against, with each one's exact rules, priority and what the listing data cannot show. | | [`agentgraph_screen_agencies`](/docs/agentgraph/screen_agencies) | Screen agencies in an area | Ranks the real estate agencies active in a German area against partner profiles: franchise offices losing momentum and growing independent agencies (solo… | | [`agentgraph_screen_agents`](/docs/agentgraph/screen_agents) | Screen agents in an area | Ranks the individual agents named on listings in a German area against partner profiles: top agents in a small area, top performers with a capped territory,… | | [`agentgraph_agency_profile`](/docs/agentgraph/agency_profile) | Agency in full | One agency's figures, quarter by quarter, its team (named agents on its listings), its places, contacts, and every partner profile it matches, benchmarked… | | [`agentgraph_agent_profile`](/docs/agentgraph/agent_profile) | Agent in full | One agent's own figures, quarter by quarter, their agency, career across agencies (where Casafari's directory has it), contacts, and every partner profile… | | [`agentgraph_partner_brief`](/docs/agentgraph/partner_brief) | Partner brief | A one-page brief on one agency or agent for the person who will approach them: key figures against the area, the partner signals they meet, listing quality… | | [`agentgraph_territory_map`](/docs/agentgraph/territory_map) | Territory map | One row per district or municipality of a German region (state, district or city): active homes, exits in 12 months, number of brokers, exits and active homes… | | [`agentgraph_save_to_watchlist`](/docs/agentgraph/save_to_watchlist) | Save to watchlist | Saves agencies or agents (ids from a screen) to your organisation's shared watchlist, each measured in the area you give. | | [`agentgraph_remove_from_watchlist`](/docs/agentgraph/remove_from_watchlist) | Remove from watchlist | Removes entries from your organisation's watchlist by id. | | [`agentgraph_watchlist`](/docs/agentgraph/watchlist) | Watchlist | Your organisation's watched agencies and agents, with their area, latest priority, active homes and momentum against the area. | | [`agentgraph_watchlist_changes`](/docs/agentgraph/watchlist_changes) | What changed | Changes on your watchlist since a date (default: the last 7 days), most important first within each day: priority and profile changes, momentum turning, price… | | [`agentgraph_area_benchmark`](/docs/agentgraph/area_benchmark) | Area benchmark | What normal looks like for brokers in a German area: percentiles of active homes, exits, days on market, price cuts and momentum, how the market splits… | ## MCP and REST compared Over MCP: 13 tools. Over REST: 0 operations. Available over MCP only: the public REST description has no operation for it. Details: [MCP and REST compared](/docs/parity#agentgraph-ai). ## Ask your assistant > Which independent agencies in München are growing faster than the market? ## Questions about this - [What is Casafari MCP?](/docs/faq/what-is-casafari-mcp) - [Which countries does Casafari cover?](/docs/faq/which-countries) - [Does Casafari cover Germany?](/docs/faq/coverage-germany) - [Does every tool cover all 16 countries?](/docs/faq/per-tool-coverage) - [Which products does Casafari MCP offer, and how many tools are there?](/docs/faq/which-products) --- # `agentgraph_find_location` Find a German location. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_find_location` on `https://mcp.casafari.com/` (the backend's own name is `find_location`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description Finds German cities, districts and states by name and returns their location ids, kinds and parent areas. Use it when a name is ambiguous (several "Neustadt") or to pick a district within a city. ## Parameters - `query` (string, required) at least 2 characters. - `limit` (integer, optional) 1–20; default 8. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_find_location", "arguments": { "query": "…" } } } ``` ## Questions about this - [Does Casafari cover Germany?](/docs/faq/coverage-germany) - [What is AgentGraph AI?](/docs/faq/what-is-agentgraph) - [How do I find agencies or agents to partner with in a German city?](/docs/faq/example-find-agencies-germany) - [How do I turn a place name into a location id?](/docs/faq/location-ids) --- # `agentgraph_list_profiles` Partner profiles. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_list_profiles` on `https://mcp.casafari.com/` (the backend's own name is `list_profiles`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description Lists the partner profiles the screens match against, with each one's exact rules, priority and what the listing data cannot show. ## Parameters No parameters. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_list_profiles", "arguments": {} } } ``` ## Questions about this - [What is AgentGraph AI?](/docs/faq/what-is-agentgraph) - [How do I find agencies or agents to partner with in a German city?](/docs/faq/example-find-agencies-germany) --- # `agentgraph_screen_agencies` Screen agencies in an area. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_screen_agencies` on `https://mcp.casafari.com/` (the backend's own name is `screen_agencies`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description Ranks the real estate agencies active in a German area against partner profiles: franchise offices losing momentum and growing independent agencies (solo brokers and small teams of about 2-10). Each result has its figures (active homes, new homes per quarter, momentum, exits and days on market, price cuts, postcodes), the profile signals it meets and misses, its team, and contacts. Use this to find agencies worth partnering with. ## Parameters - `location` (string | integer, optional): A German city, district or state by name ("München", "Hamburg-Altona", "Bayern") or a location id from find_location. A 5-digit value is read as a postcode. - `zipcodes` (string[], optional): Limit to these postcodes (with or without a location). at most 200 items; pattern `^\d{5}$`. - `profile` (string | string[], optional): Profiles to match: franchise_office_losing_momentum, growing_independent; "all" (default) for any of them, or "none" to rank every broker by volume using filters only. - `operation` (string, optional): Sales listings (default) or rentals. Values: `sale`, `rent`. default "sale". - `limit` (integer, optional) 1–50; default 20. - `filters` (object, optional): Optional thresholds applied on top of the profiles (or alone with profile "none"). Percent values are whole numbers. - `min_active_homes` (integer, optional) ≥ 0. - `max_active_homes` (integer, optional) ≥ 0. - `min_exits_last_12m` (integer, optional) ≥ 0. - `min_momentum_pct` (number, optional) - `max_momentum_pct` (number, optional) - `min_median_days_on_market` (integer, optional) ≥ 0. - `max_median_days_on_market` (integer, optional) ≥ 0. - `min_price_cut_share_pct` (number, optional) 0–100. - `max_postcodes` (integer, optional) ≥ 1. - `min_top_postcode_share_pct` (number, optional) 0–100. - `brand_kinds` (string[], optional) Values: `independent`, `franchise`, `bank_network`, `digital_brokerage`. - `exclude_brands` (string[], optional) - `min_team_size` (integer, optional): Agencies only: named people on its listings. ≥ 0. - `max_team_size` (integer, optional): Agencies only. ≥ 0. - `client_brand` (string, optional): Your own network's name, if you are one. Its offices and agents are not offered as matches from "another network's franchise". ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_screen_agencies", "arguments": { "location": "…" } } } ``` ## Questions about this - [Does Casafari cover Germany?](/docs/faq/coverage-germany) - [What is AgentGraph AI?](/docs/faq/what-is-agentgraph) - [How do I find agencies or agents to partner with in a German city?](/docs/faq/example-find-agencies-germany) --- # `agentgraph_screen_agents` Screen agents in an area. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_screen_agents` on `https://mcp.casafari.com/` (the backend's own name is `screen_agents`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description Ranks the individual agents named on listings in a German area against partner profiles: top agents in a small area, top performers with a capped territory, agents in traditional offices, and brokers in an early phase. Each result has the agent's own figures, agency, signals met and missed, career history where known, and contacts. Only listings that name an agent count (most agency websites name them, portals less often). ## Parameters - `location` (string | integer, optional): A German city, district or state by name ("München", "Hamburg-Altona", "Bayern") or a location id from find_location. A 5-digit value is read as a postcode. - `zipcodes` (string[], optional): Limit to these postcodes (with or without a location). at most 200 items; pattern `^\d{5}$`. - `profile` (string | string[], optional): Profiles to match: top_performer_capped_territory, top_agent_small_area, agent_traditional_office, early_phase_broker; "all" (default) for any of them, or "none" to rank every broker by volume using filters only. - `operation` (string, optional): Sales listings (default) or rentals. Values: `sale`, `rent`. default "sale". - `limit` (integer, optional) 1–50; default 20. - `filters` (object, optional): Optional thresholds applied on top of the profiles (or alone with profile "none"). Percent values are whole numbers. - `min_active_homes` (integer, optional) ≥ 0. - `max_active_homes` (integer, optional) ≥ 0. - `min_exits_last_12m` (integer, optional) ≥ 0. - `min_momentum_pct` (number, optional) - `max_momentum_pct` (number, optional) - `min_median_days_on_market` (integer, optional) ≥ 0. - `max_median_days_on_market` (integer, optional) ≥ 0. - `min_price_cut_share_pct` (number, optional) 0–100. - `max_postcodes` (integer, optional) ≥ 1. - `min_top_postcode_share_pct` (number, optional) 0–100. - `brand_kinds` (string[], optional) Values: `independent`, `franchise`, `bank_network`, `digital_brokerage`. - `exclude_brands` (string[], optional) - `min_team_size` (integer, optional): Agencies only: named people on its listings. ≥ 0. - `max_team_size` (integer, optional): Agencies only. ≥ 0. - `client_brand` (string, optional): Your own network's name, if you are one. Its offices and agents are not offered as matches from "another network's franchise". ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_screen_agents", "arguments": { "location": "…" } } } ``` ## Questions about this - [What is AgentGraph AI?](/docs/faq/what-is-agentgraph) - [How do I find agencies or agents to partner with in a German city?](/docs/faq/example-find-agencies-germany) --- # `agentgraph_agency_profile` Agency in full. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_agency_profile` on `https://mcp.casafari.com/` (the backend's own name is `agency_profile`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description One agency's figures, quarter by quarter, its team (named agents on its listings), its places, contacts, and every partner profile it matches, benchmarked against its main city (or the area you give). Pass an id from screen_agencies, or a name. ## Parameters - `id` (string, optional): The id a screen returned (c:... or k:...). - `name` (string, optional): The agency's name when no id is known. - `location` (string | integer, optional): A German city, district or state by name ("München", "Hamburg-Altona", "Bayern") or a location id from find_location. A 5-digit value is read as a postcode. - `zipcodes` (string[], optional): Limit to these postcodes (with or without a location). at most 200 items; pattern `^\d{5}$`. - `operation` (string, optional): Sales listings (default) or rentals. Values: `sale`, `rent`. default "sale". - `client_brand` (string, optional): Your own network's name, if you are one. Its offices and agents are not offered as matches from "another network's franchise". ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_agency_profile", "arguments": { "id": "…" } } } ``` --- # `agentgraph_agent_profile` Agent in full. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_agent_profile` on `https://mcp.casafari.com/` (the backend's own name is `agent_profile`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description One agent's own figures, quarter by quarter, their agency, career across agencies (where Casafari's directory has it), contacts, and every partner profile they match, benchmarked against their main city (or the area you give). Pass an id from screen_agents, or a name with their agency. ## Parameters - `id` (string, optional): The id a screen returned (a:... or p:...). - `name` (string, optional): The agent's name when no id is known. - `company` (string, optional): Their agency, to tell two people of the same name apart. - `location` (string | integer, optional): A German city, district or state by name ("München", "Hamburg-Altona", "Bayern") or a location id from find_location. A 5-digit value is read as a postcode. - `zipcodes` (string[], optional): Limit to these postcodes (with or without a location). at most 200 items; pattern `^\d{5}$`. - `operation` (string, optional): Sales listings (default) or rentals. Values: `sale`, `rent`. default "sale". - `client_brand` (string, optional): Your own network's name, if you are one. Its offices and agents are not offered as matches from "another network's franchise". ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_agent_profile", "arguments": { "id": "…" } } } ``` --- # `agentgraph_partner_brief` Partner brief. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_partner_brief` on `https://mcp.casafari.com/` (the backend's own name is `partner_brief`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description A one-page brief on one agency or agent for the person who will approach them: key figures against the area, the partner signals they meet, listing quality (photos, descriptions, sole-agent mandates, price cuts, own website vs portals), team or career, a map of their active listings, two or three talking points, and how they may lawfully be approached in Germany. Returns the brief and brief_url, a printable page valid for 7 days (share it only inside your organisation). Pass an id from a screen and the area to compare against. ## Parameters - `id` (string, required): An id from screen_agencies, screen_agents or a profile (c:, k:, a: or p:). - `location` (string | integer, optional): A German city, district or state by name ("München", "Hamburg-Altona", "Bayern") or a location id from find_location. A 5-digit value is read as a postcode. - `zipcodes` (string[], optional): Limit to these postcodes (with or without a location). at most 200 items; pattern `^\d{5}$`. - `operation` (string, optional): Sales listings (default) or rentals. Values: `sale`, `rent`. default "sale". - `client_brand` (string, optional): Your own network's name, if you are one. Its offices and agents are not offered as matches from "another network's franchise". ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_partner_brief", "arguments": { "id": "…" } } } ``` ## Questions about this - [What is AgentGraph AI?](/docs/faq/what-is-agentgraph) - [How do I find agencies or agents to partner with in a German city?](/docs/faq/example-find-agencies-germany) --- # `agentgraph_territory_map` Territory map. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_territory_map` on `https://mcp.casafari.com/` (the backend's own name is `territory_map`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description One row per district or municipality of a German region (state, district or city): active homes, exits in 12 months, number of brokers, exits and active homes per broker, the share held by franchise networks and by independents, your own network's share, the top networks, a centre point for drawing a map, and an opportunity score. Use it to decide where to open or grow next; then screen_agencies or screen_agents in the best areas. ## Parameters - `location` (string | integer, required): A German city, district or state by name ("München", "Hamburg-Altona", "Bayern") or a location id from find_location. A 5-digit value is read as a postcode. - `operation` (string, optional): Sales listings (default) or rentals. Values: `sale`, `rent`. default "sale". - `client_brand` (string, optional): Your own network's name, if you are one. Its offices and agents are not offered as matches from "another network's franchise". ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_territory_map", "arguments": { "location": "…" } } } ``` ## Questions about this - [What is AgentGraph AI?](/docs/faq/what-is-agentgraph) --- # `agentgraph_save_to_watchlist` Save to watchlist. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Writes data, Idempotent. Call it as `agentgraph_save_to_watchlist` on `https://mcp.casafari.com/` (the backend's own name is `save_to_watchlist`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description Saves agencies or agents (ids from a screen) to your organisation's shared watchlist, each measured in the area you give. AgentGraph AI re-measures the list every day and records changes: priority or profile changes, momentum turning against the area, more price cuts, slower exits, stock falling, an agent listing under a new agency, or no new listings for 60 days. Up to 200 entries. ## Parameters - `ids` (string[], required): Ids from screen_agencies, screen_agents or a profile. 1–50 items. - `location` (string | integer, optional): A German city, district or state by name ("München", "Hamburg-Altona", "Bayern") or a location id from find_location. A 5-digit value is read as a postcode. - `zipcodes` (string[], optional): Limit to these postcodes (with or without a location). at most 200 items; pattern `^\d{5}$`. - `operation` (string, optional): Sales listings (default) or rentals. Values: `sale`, `rent`. default "sale". - `label` (string, optional): An optional note shown with the entry, e.g. 'Q4 outreach'. at most 60 characters. - `client_brand` (string, optional): Your own network's name, if you are one. Its offices and agents are not offered as matches from "another network's franchise". ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_save_to_watchlist", "arguments": { "ids": [ "…" ] } } } ``` ## Questions about this - [What is AgentGraph AI?](/docs/faq/what-is-agentgraph) - [How do I find agencies or agents to partner with in a German city?](/docs/faq/example-find-agencies-germany) --- # `agentgraph_remove_from_watchlist` Remove from watchlist. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Writes data, Destructive, Idempotent. Call it as `agentgraph_remove_from_watchlist` on `https://mcp.casafari.com/` (the backend's own name is `remove_from_watchlist`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description Removes entries from your organisation's watchlist by id. ## Parameters - `ids` (string[], required) at least 1 item. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_remove_from_watchlist", "arguments": { "ids": [ "…" ] } } } ``` --- # `agentgraph_watchlist` Watchlist. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_watchlist` on `https://mcp.casafari.com/` (the backend's own name is `watchlist`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description Your organisation's watched agencies and agents, with their area, latest priority, active homes and momentum against the area. ## Parameters No parameters. ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_watchlist", "arguments": {} } } ``` --- # `agentgraph_watchlist_changes` What changed. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_watchlist_changes` on `https://mcp.casafari.com/` (the backend's own name is `watchlist_changes`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description Changes on your watchlist since a date (default: the last 7 days), most important first within each day: priority and profile changes, momentum turning, price cuts, slower exits, falling or growing stock, agents moving agency, going quiet. refresh: true re-measures now instead of waiting for the daily run (slower). ## Parameters - `since` (string, optional): YYYY-MM-DD - `refresh` (boolean, optional) default false. - `min_importance` (string, optional) Values: `high`, `medium`, `low`. default "low". ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_watchlist_changes", "arguments": { "since": "…" } } } ``` ## Questions about this - [How do I find agencies or agents to partner with in a German city?](/docs/faq/example-find-agencies-germany) --- # `agentgraph_area_benchmark` Area benchmark. Product: [AgentGraph AI](/docs/agentgraph). Annotations: Read-only. Call it as `agentgraph_area_benchmark` on `https://mcp.casafari.com/` (the backend's own name is `area_benchmark`). Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#agentgraph-ai). ## Description What normal looks like for brokers in a German area: percentiles of active homes, exits, days on market, price cuts and momentum, how the market splits between independents, franchises, banks and online brokerages, and the biggest networks there. ## Parameters - `location` (string | integer, optional): A German city, district or state by name ("München", "Hamburg-Altona", "Bayern") or a location id from find_location. A 5-digit value is read as a postcode. - `zipcodes` (string[], optional): Limit to these postcodes (with or without a location). at most 200 items; pattern `^\d{5}$`. - `unit` (string, optional) Values: `agency`, `agent`. default "agency". - `operation` (string, optional): Sales listings (default) or rentals. Values: `sale`, `rent`. default "sale". ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agentgraph_area_benchmark", "arguments": { "location": "…" } } } ``` --- # Gateway The gateway is the server at `https://mcp.casafari.com/`. It signs you in, checks your account's rights on every call and forwards each tool to the service that owns it. Besides the data tools it has one tool of its own. ## Server instructions Sent to every client when it connects: > This server provides a unified set of tools grouped by domain. Each tool is named `_`, where the prefix identifies its group — always call a tool by its full name. Before calling any tool, read its description and input schema: they define the required arguments and the tool's behavior. Some tools may be unavailable depending on the access granted to your token. Before using a group for the first time, call `list_servers`: it returns each available group's own description and usage instructions (for example, which tool to start with), which are not repeated in the tool descriptions. ## Tools | Tool | Title | What it does | |---|---|---| | [`list_servers`](/docs/gateway/list_servers) | List Servers | List the tool groups available to you. | ## Questions about this - [What is the Casafari MCP gateway, and what does `list_servers` do?](/docs/faq/gateway-and-list-servers) --- # `list_servers` List Servers. Gateway: [Gateway](/docs/gateway). Annotations: Read-only. Call it as `list_servers` on `https://mcp.casafari.com/`. ## Description List the tool groups available to you. Each entry is {namespace, title, description, instructions} as the group's server describes itself; tools in a group are named '_'. Call this before using a group for the first time: the instructions say how to use its tools (for example, which one to start with). ## Parameters No parameters. ## Response The result is returned as `result`: - `result` (map of string[], required) ## Example call Required arguments only, with placeholder values; see the parameters above for real ones. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_servers", "arguments": {} } } ``` ## Questions about this - [What is Casafari MCP?](/docs/faq/what-is-casafari-mcp) - [What is the difference between Casafari MCP and the Casafari REST API?](/docs/faq/mcp-vs-rest-api) - [What is the Casafari MCP gateway, and what does `list_servers` do?](/docs/faq/gateway-and-list-servers) - [Which products does Casafari MCP offer, and how many tools are there?](/docs/faq/which-products) - [How are Casafari MCP tools named?](/docs/faq/tool-naming)