Property data in your product · Use case

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

Sign in to the Casafari REST API with POST /login (or an API client) and load valid values from the References operations. Then query the property graph with Property Sourcing's POST /api/v2/properties/search, by location ids or a custom boundary. Each result is one deduplicated property; fetch details by id and share selections with smart links.

Products: References, Property Sourcing

#Short answer

The Casafari REST API at https://api.casafari.com signs in with an email and password, or with an API client for unattended integrations. The References operations give you the valid property types, conditions, features and location ids.

POST /api/v2/properties/search then queries the property graph by location_ids or a custom_location_boundary. Every result is one property, deduplicated across agencies and portals, with its price and status history. The full flow is described in the REST API guide and the public OpenAPI description at https://docs.api.casafari.com/openapi.json.

#Steps

#Sign in: POST /login; renew with GET /refresh-token

1. Send email and password as JSON to POST /login. Keep the access_token and refresh_token (JWT). Send Authorization: Bearer <access_token> on every call.
   • When the token expires, call GET /refresh-token with the refresh token as the bearer to receive a new access_token.
   • A 401 from GET /refresh-token means you must log in again.

#Load vocabularies: GET /api/v1/references/types, GET /api/v1/references/conditions, GET /api/v1/references/features

2. Load the valid values once and cache them.
   • GET /api/v1/references/types returns property types and their country availability.
   • GET /api/v1/references/conditions returns conditions such as used, ruin, very-good, new and other.
   • GET /api/v1/references/features returns property features.

#Resolve places: POST /api/v1/references/locations (name, polygon or zip_codes)

3. Send name, a closed polygon in coordinates (first and last points must match) or zip_codes. Use lang for the language of the names returned. Keep the location ids.
   • For a typeahead box in Spain or Portugal, use POST /api/v1/references/locations/typeahead.
   • Its country_codes field supports ES and PT.
   • Its size field defaults to 30, with a maximum of 100.
   • Its lang field takes en, pt, es or de.

#Search: POST /api/v2/properties/search with search_operations, location_ids or custom_location_boundary, price, bedrooms, total_area, energy_ratings, characteristics, days_on_market

4. Build the body from these fields:
   • search_operations for sale or rent.
   • location_ids, or custom_location_boundary (a polygon or a circle).
   • Ranges such as price_from/price_to, bedrooms_from/bedrooms_to, total_area_from/total_area_to and days_on_market_from/days_on_market_to.
   • energy_ratings, characteristics and types.
   • Optional filters include private, gross_yield_from/gross_yield_to and ref_numbers.

#Detail: GET /api/v1/properties/search/{property_id}

5. Fetch one property with its full history when a user opens it. See the operation's page.

#Share: POST /api/v1/properties/smart-links from primary_listing_ids

6. Send the selected properties' primary ad ids in primary_listing_ids, with settings, user and company as described on the operation's page. The result is a shareable link for a client.

#Example request and response

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

First resolve Lisbon to a location id:

POST https://api.casafari.com/api/v1/references/locations
Authorization: Bearer <access_token>
Content-Type: application/json

{ "name": "Lisbon" }

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

POST https://api.casafari.com/api/v2/properties/search
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "search_operations": ["sale"],
  "location_ids": [LISBON_LOCATION_ID],
  "types": ["apartment"],
  "bedrooms_from": 2,
  "bedrooms_to": 2,
  "price_to": 400000
}

A trimmed result for one property is shown below. These are field names Casafari uses in its property records. Values are elided, and the envelope and paging are on the reference page.

{
  "property_id": "...",
  "primary_listing_id": "...",
  "type": "apartment",
  "bedrooms": "...",
  "total_area": "...",
  "energy_rating": "...",
  "sale_status": "...",
  "sale_price": "...",
  "sale_currency": "...",
  "sale_price_per_sqm": "...",
  "rent_status": "...",
  "rent_price": "...",
  "gross_yield": "..."
}

#How to read the result

Each result is a property, not an advertisement. Your result count is the number of distinct homes, so you can show it to users as supply without double counting.

#One record per property with sale and rent fields side by side

One record can hold both sale and rent fields.

• Sale side: sale_status, sale_price in the currency given by sale_currency, sale_price_base in euros, and sale_price_per_sqm.
• Rent side: the same set with rent_ in place of sale_, plus rent_period.
• Yield: gross_yield is the gross yield in percent, which helps investors shortlist.

Use the _base fields when you compare prices across currencies.

#Deprecated fields: floor, view, direction, energy_certificate; use floors, views, directions, energy_ratings

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. Check its shape on the reference page.

#Limits

Property Sourcing and References are REST operations for Casafari client accounts. They are not offered over MCP. For property search and fetch, self-serve access for new users is coming soon.

The sources give no figures for pricing, 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.

#v1 and v2 search both exist; the hub documents both

POST /api/v1/properties/search and POST /api/v2/properties/search are both live and both documented. Their published request fields are the same. The sources give no retirement date for v1.

#Smart links are BETA

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 authenticate with the Casafari REST API?.

#Questions

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

All use cases