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
- Create a platform API key (
cf_sk_...) in the console at https://platform.casafari.com/console. Send it asAuthorization: Bearer $CASAFARI_API_KEY, or inX-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
400key_in_query. - Existing clients sign in to the Legacy API with
POST /loginand renew withGET /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
- The platform takes the values inline, with no vocabulary call:
types: lower-case property types, for exampleapartment,penthouse,houseorvilla.featuresandexclude_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) andGET /api/v1/references/featuresare Legacy API only (References); the platform has no route for them yet.
Resolve places: GET /v1/locations/search (name or postcode)
- Call
GET /v1/locations/searchwithquery(a place name), orpostcodewithpostcode_match(exactorprefix). Addcountrywhen you know it andlangfor the language of the names returned. Keep the location ids.- It is free, which suits a typeahead box:
sizetakes 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.
- It is free, which suits a typeahead box:
Search: POST /v1/property-sourcing/searches with location_ids, operation, types, price, bedrooms, living_area_sqm, features
- Build the body from these fields:
location_ids(required, 1 to 100) and optionallycountry.operation:sale(default) orrent.- Ranges as
{"min": n, "max": n}:price,price_per_sqm,bedrooms,bathrooms,living_area_sqmandplot_area_sqm. types,featuresandexclude_features.sort(newest,oldest,recently_updated,price_asc,price_desc,price_per_sqm_asc,price_per_sqm_desc,largest,largest_price_cut) andpage_size(1 to 100).- Filters only the merged record knows:
days_on_marketas{"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_afterandchanged_afterasYYYY-MM-DD. rental_yieldas{"min": n, "max": n}in percent a year (1 to 20), foroperationrentonly; for homes for sale read each result'srental_yieldinstead.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 withfeatures,exclude_features,days_on_market,exclusive,rental_yield,changed_after,first_seen_afterornew_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, thecharacteristicsobject,gross_yield_from/gross_yield_to, and bank or auction filters.
Page: GET /v1/property-sourcing/searches/{cursor}
- When
nextis 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}
- Fetch one property when a user opens it, with
expand=listings,historyfor 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
- 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, withsettings,userandcompany, as described on the operation's page. Platformprop_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:
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:
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.
{
"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.amountin the currency given byprice.currency, andprice.per_sqm. Prices are asking prices;amountis null when the price is on request. - Age on the market:
first_seenis when the property came on the market for this operation. - Merged-record fields:
days_on_market,market_valueandasking_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_changedandprice_change(first and current asking price,change_pct,cuts_count). - More detail: bathrooms, total and plot area, construction year,
energy_rating,condition,features,address,descriptionandstatuscome 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.
Smart links are BETA, on the Legacy API only
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
Should I use v1 or v2 search?
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