Platform

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.The most complete property index in Europe: a deduplicated, cleaned property graph.

How the graph is built

Property data in your product · Use case

How do I build property search into my application with the Casafari REST API?

Create a platform API key, turn place names into location ids with Location Lookup's GET /v1/locations/search, then query the property graph with Property Sourcing's POST /v1/property-sourcing/searches. Each result is one deduplicated property; page with next and fetch details with GET /v1/property-sourcing/properties/{property_id}. Reference vocabularies and smart links stay on the Legacy API.

Products: Property Sourcing, References

Short answer

The Casafari REST API at https://platform.casafari.com takes a platform API key on every call; there is no sign-in step. Location Lookup turns place names and postcodes into location ids.

POST /v1/property-sourcing/searches then queries the property graph by location_ids, with filters for operation, type, price, size, rooms and features. Every result is one property, deduplicated across agencies and portals; GET /v1/property-sourcing/properties/{property_id} adds its advertisements and price history. The full flow is described in the REST API guide and in Property Sourcing. Existing clients on the Legacy API call POST /api/v2/properties/search.

Steps

Authenticate: a platform API key; no POST /login or GET /refresh-token

  1. Create a platform API key (cf_sk_...) in the console at https://platform.casafari.com/console. Send it as Authorization: Bearer $CASAFARI_API_KEY, or in X-API-Key, on every call. See platform API keys.
    • There is no sign-in call and no refresh step.
    • Never put the key in a query string; the API answers 400 key_in_query.
    • Existing clients sign in to the Legacy API with POST /login and renew with GET /refresh-token: how to sign in.

Valid values: types and features in the search body; Legacy API vocabularies GET /api/v1/references/types, GET /api/v1/references/conditions, GET /api/v1/references/features

  1. The platform takes the values inline, with no vocabulary call:
    • types: lower-case property types, for example apartment, penthouse, house or villa.
    • features and exclude_features: balcony, elevator, garage, garden, parking, storage, swimming_pool, terrace, rental_license, furniture, no_elevator, rented_out, life_annuity, business_transfer, smoke_outlet.
    • The vocabulary routes GET /api/v1/references/types, GET /api/v1/references/conditions (used, ruin, very-good, new, other) and GET /api/v1/references/features are Legacy API only (References); the platform has no route for them yet.

Resolve places: GET /v1/locations/search (name or postcode)

  1. Call GET /v1/locations/search with query (a place name), or postcode with postcode_match (exact or prefix). Add country when you know it and lang for the language of the names returned. Keep the location ids.
    • It is free, which suits a typeahead box: size takes at most 25.
    • Postcodes cover Spain, France (partly) and Portugal (parts of Lisbon) only.
    • For a point, use GET /v1/locations/by-coordinates. Polygons have no platform equivalent.

Search: POST /v1/property-sourcing/searches with location_ids, operation, types, price, bedrooms, living_area_sqm, features

  1. Build the body from these fields:
    • location_ids (required, 1 to 100) and optionally country.
    • operation: sale (default) or rent.
    • Ranges as {"min": n, "max": n}: price, price_per_sqm, bedrooms, bathrooms, living_area_sqm and plot_area_sqm.
    • types, features and exclude_features.
    • sort (newest, oldest, recently_updated, price_asc, price_desc, price_per_sqm_asc, price_per_sqm_desc, largest, largest_price_cut) and page_size (1 to 100).
    • Filters only the merged record knows: days_on_market as {"min": n, "max": n} in whole days, counted across every source; below_market_pct (0 to 100: at least this many percent below Casafari's estimated market value); private (true for private sellers only, false for professionals only); exclusive (true for homes offered through one agency or private seller only); new_build (true or false); first_seen_after and changed_after as YYYY-MM-DD.
    • rental_yield as {"min": n, "max": n} in percent a year (1 to 20), for operation rent only; for homes for sale read each result's rental_yield instead.
    • price_cut_pct (homes for sale whose asking price was cut by at least this many percent in all, largest cuts first). It cannot be combined with features, exclude_features, days_on_market, exclusive, rental_yield, changed_after, first_seen_after or new_build.
    • include_special_sales: true also returns special sales left out by default, such as prices far below market value or adverts selling a share, a debt, no possession or a parking space.
    • Legacy API filters with no platform equivalent yet: custom_location_boundary, energy_ratings, the characteristics object, gross_yield_from/gross_yield_to, and bank or auction filters.

Page: GET /v1/property-sourcing/searches/{cursor}

  1. When next is not null, call that URL, GET /v1/property-sourcing/searches/{cursor}, for the next page. It stays valid for one hour. One search reaches at most 1000 results.

Detail: GET /v1/property-sourcing/properties/{property_id}

  1. Fetch one property when a user opens it, with expand=listings,history for every advertisement and its price history. See the operation's page.

Share (Legacy API only): POST /api/v1/properties/smart-links from primary_listing_ids

  1. The platform has no route for shareable client links yet. Existing clients send the selected properties' primary ad ids from Legacy API records in primary_listing_ids, with settings, user and company, as described on the operation's page. Platform prop_ ids are not those ids.

Example request and response

This example searches 2-bedroom apartments for sale in Lisbon under 400,000.

First resolve Lisbon to a location id:

bash
curl "https://platform.casafari.com/v1/locations/search?query=Lisbon&country=PT" \
  -H "Authorization: Bearer $CASAFARI_API_KEY"

Then search. Replace LISBON_LOCATION_ID with the id returned above, and check accepted values on the reference page:

bash
curl -X POST "https://platform.casafari.com/v1/property-sourcing/searches" \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "location_ids": [LISBON_LOCATION_ID],
  "country": "PT",
  "operation": "sale",
  "types": ["apartment"],
  "bedrooms": { "min": 2, "max": 2 },
  "price": { "max": 400000 },
  "sort": "newest",
  "page_size": 25
}'

A trimmed answer with one property is shown below. Values are elided; the reference page has a sample with values.

json
{
  "results": [
    {
      "id": "prop_...",
      "type": "apartment",
      "operation": "sale",
      "price": { "amount": "...", "currency": "...", "per_sqm": "..." },
      "bedrooms": "...",
      "living_area_sqm": "...",
      "location": { "id": "...", "name": "...", "coordinates": { "lat": "...", "lon": "..." } },
      "first_seen": "...",
      "listings_count": null,
      "matched_tags": null
    }
  ],
  "total": "...",
  "next": "https://platform.casafari.com/v1/property-sourcing/searches/..."
}

How to read the result

Each result is a property, not an advertisement. total is the number of distinct homes that match, when known, so you can show it to users as supply without double counting.

One record per property: price, operation and first_seen

Each result is read for one operation, sale or rent, given in operation.

  • Price: price.amount in the currency given by price.currency, and price.per_sqm. Prices are asking prices; amount is null when the price is on request.
  • Age on the market: first_seen is when the property came on the market for this operation.
  • Merged-record fields: days_on_market, market_value and asking_vs_market_pct (market value is Casafari's estimate, never an asking or a closing price), private, exclusive, bank, auction, new_build, rental_yield, last_changed and price_change (first and current asking price, change_pct, cuts_count).
  • More detail: bathrooms, total and plot area, construction year, energy_rating, condition, features, address, description and status come from the property read.

listings_count is null in search results; read the property with expand=listings to know it.

Legacy API only: deprecated fields floor, view, direction, energy_certificate; use floors, views, directions, energy_ratings

These apply to existing clients on the Legacy API. There the singular fields floor, view, direction, energy_certificate and energy_certificates are marked deprecated and will be removed in the next major update; build on floors, views, directions and energy_ratings. The characteristics filter changed from an array of strings to an object. None of these fields exist on the platform.

Limits

Searching the property graph, paging and fetching one property are self-serve on the Casafari API and MCP Platform over REST, with a platform API key, and over MCP. Reference vocabularies and smart links are Legacy API operations for existing clients; the platform has no route for them yet.

The sources give no figures for quotas, rate limits, refresh frequency or SLAs. Ask Casafari at https://www.casafari.com/. To see what exists over MCP and over REST, read MCP vs REST API: which to use.

Legacy API: v1 and v2 search both exist; the hub documents both

For existing clients, POST /api/v1/properties/search and POST /api/v2/properties/search are both live and both documented, with the same published request fields. The sources give no retirement date for v1. New integrations use POST /v1/property-sourcing/searches.

POST /api/v1/properties/smart-links is marked BETA. Expect its behaviour to change, and keep the link step separate in your code. See also How do I build on the Casafari REST API? and How do I sign in to the Legacy API?.

Ask in Claude or ChatGPT

Property Sourcing has an MCP server, https://platform.casafari.com/mcp/property-sourcing, so an assistant can run this from a chat. In Claude or ChatGPT, add a custom connector with that URL; in Claude Code: claude mcp add --transport http casafari-property-sourcing https://platform.casafari.com/mcp/property-sourcing. Sign in with your Casafari Platform account in the browser (a new account starts on the Free plan). Then ask, for example:

Flats in Madrid under €650K, 2+ bedrooms: show each with every agency advertising it and its price history.

The assistant finds the place with locations_search (free), searches with property-sourcing_search (5 tokens a page of up to 10 homes, property-sourcing_next_page for more), reads each home with property-sourcing_get_property (2 tokens: every agency and portal advertising it and its asking price history) and turns a pasted portal or agency link into its home with property-sourcing_resolve_listing (2 tokens). Prices are asking prices. See Property Sourcing.

Questions

For a new integration, neither: use the platform's POST /v1/property-sourcing/searches with a platform API key. Existing clients on the Legacy API have both POST /api/v1/properties/search and POST /api/v2/properties/search, documented with the same published request fields; the sources give no retirement date for v1 and no list of differences in the responses, so compare the two reference pages. Existing v1 integrations keep working with the documented fields.

How do I authenticate an unattended integration?

Use a platform API key: create it in the console at https://platform.casafari.com/console and send it as Authorization: Bearer $CASAFARI_API_KEY or in X-API-Key. There is no token exchange and no refresh step; see /docs/rest#platform-api-keys. Existing clients on the Legacy API use an API client's client_id and client_secret with the client credentials grant at POST https://api.casafari.com/oauth/token.

Can I search by zip code?

Yes, through location ids, because the search filters by location_ids. Call GET /v1/locations/search with postcode (and postcode_match exact or prefix) to get the places a postcode covers, smallest first, then pass their ids to the search. Postcodes cover Spain, France (partly) and Portugal (parts of Lisbon) only. A zip code boundary as a polygon is Legacy API only: POST /api/v1/references/zipcode-boundary with custom_location_boundary; the platform has no route for it yet.

Is there a bulk export instead of searching?

Data Export is documented at /docs/data-export: it describes bulk delivery and the fields of each entity, including properties, alerts and locations. It suits teams that want the graph in their own warehouse rather than calling search, where one search reaches at most 1000 results. The sources publish no terms or delivery schedule for it; ask Casafari at https://www.casafari.com/.

Can an MCP assistant call these operations?

Yes for search and detail. Property Sourcing has an MCP server at https://platform.casafari.com/mcp/property-sourcing (also on https://platform.casafari.com/mcp) with property-sourcing_search, property-sourcing_next_page, property-sourcing_get_property and property-sourcing_resolve_listing, plus the free locations_search. An AI agent can also call the REST operations with a platform API key. Reference vocabularies and smart links are Legacy API only. The page at /docs/parity compares MCP and REST.

Related: Deduplicated buyer shortlist from a plain-language brief, Grounded property tool for an AI assistant

All use cases

Tip: add .md to any URL to read it as Markdown.