Screen investments · Use case

What gross rental yield can I expect in this area, and which properties beat it?

Casafari's tools do not return an area yield directly. You compute gross yield by dividing annualised rent per m² by sale price per m², both from Area Insights' area-insights_get_time_series_data on the same boundary. To find properties that beat it, filter POST /api/v2/properties/search by gross_yield_from, then check gross_yield on comparables_get_comparables results.

Products: Area Insights, References, Property Sourcing, Comparables & Valuation

#Short answer

Area gross yield = annual rent per m² ÷ sale price per m² × 100. Compare like with like: same boundary, type group, bedroom range and period.

Area Insights gives you both inputs. Call area-insights_get_time_series_data with data_point avg_price_psqm twice: once with business_type rent, once with business_type sale.

At property level, gross_yield appears in two places:

• as a filter on POST /api/v2/properties/search, through gross_yield_from and gross_yield_to
• as a field on each comparables_get_comparables result, described as gross yield in percentage

The property graph keeps one record per property, so a home advertised by several agencies is counted once on both the rent side and the sale side (The property graph).

#Steps

#Resolve the area

1. Call locations_search with an English place name, for example Porto. Check administrative_level and breadcrumbs to choose between a city and a district with the same name, and keep the location_id.

   You can use a circle instead: a target_point plus a distance in meters, from 50 to 50000. Note that the Area Insights tools measure the circle in meters, while comparables_get_comparables uses kilometers.

#area-insights_get_time_series_data with business_type rent and avg_price_psqm; repeat with business_type sale

2. Call area-insights_get_time_series_data with:
   • type_group: apartment
   • business_type: rent
   • data_point: avg_price_psqm
   • date_interval: month
   • date_range.min
   • alias: for example Porto rent
   • custom_location_boundary.location_ids
3. Repeat the call with business_type sale and a new alias, keeping every other field the same.
4. Take the latest value from each series. To smooth out a single period, you can instead run area-insights_get_time_series_operations with mean or movavg_last_3 on each series. That tool is available over MCP only.

#Segment by bedrooms with area-insights_get_bedrooms_distribution for both operations

5. Call area-insights_get_bedrooms_distribution with the same boundary, once with business_type rent and once with sale. On this tool, bedrooms_range goes up to 10.

   Each row returns bedrooms, properties_count, average_price and average_price_per_sqm. The yield for a bedroom segment is that segment's annualised rent average_price_per_sqm ÷ its sale average_price_per_sqm. properties_count shows how many properties stand behind each figure.

#Shortlist properties: POST /api/v2/properties/search with gross_yield_from

6. Call POST /api/v2/properties/search with:

   • search_operations: sale
   • location_ids: documented as those returned by POST /api/v1/references/locations
   • types
   • bedrooms_from and bedrooms_to
   • gross_yield_from: at or above the area yield you computed

   The field is described only as the "minimum gross yield value", with no unit stated. Comparables report gross_yield in percentage, but check the unit on the operation page.

#Validate a target: comparables_get_comparables and the gross_yield field

7. Call comparables_get_comparables around the target's address or coordinates with operation rent. Read estimated_prices.fair_market_price and the rent_period of the results.
8. Call it again with operation sale, and compare the annualised fair rent with the asking price.
9. Read gross_yield on the returned comparables to see what similar properties yield nearby.

#Example: 1-bedroom apartments in Porto

A person asks their assistant: "What is the gross yield for 1-bedroom apartments in Porto, and which ones beat it?"

The assistant makes these calls:

1. locations_search with Porto.
2. area-insights_get_bedrooms_distribution with type_group apartment, bedrooms_range min 1 and max 1, business_type rent.
3. The same call with business_type sale.
4. Optionally, area-insights_get_time_series_data for both operations to see the trend.

The calculation, with the values each response returns:

• Call the rent row's average_price_per_sqm R and the sale row's S.
• If R is a monthly figure, the area gross yield is R × 12 ÷ S × 100.
• For one property, divide its annualised rent by its asking price.

The shortlist runs over REST, with a Casafari client account (the self-serve Property Sourcing search has no yield filter):

{
  "search_operations": ["sale"],
  "location_ids": ["<LOCATION_ID>"],
  "types": ["apartment"],
  "bedrooms_from": 1,
  "bedrooms_to": 1,
  "gross_yield_from": "<AREA_YIELD>"
}

Replace the placeholders with numbers, and check value formats on the operation page. This page gives no market figures: every number comes from the responses.

#How to read the result

#Check rent_period: monthly figures must be annualised

comparables_get_comparables results carry rent_period, which is one of day, week, fortnight, month, year or none. Annualise before you divide: multiply monthly figures by 12 and weekly figures by 52.

The Area Insights tool descriptions do not state the period behind rent values. Confirm it before annualising, for example by comparing with rent_price_per_sqm and rent_period on comparables in the same area.

Keep both sides in the same currency. Comparables give sale_price_per_sqm_base and rent_price_per_sqm_base in Euros.

#Gross, not net: costs and vacancy are yours to add

Gross yield ignores taxes, maintenance, management, insurance, fees and vacancy, and none of these are in the data.

Area Insights figures describe advertised prices; the product's own example speaks of asking price per m². They are not achieved rents. Treat the result as a screen, not an underwriting figure.

#Limits

#The tools do not return an area yield; you compute it

No Area Insights data_point is a yield: the data points cover price, price per m², supply and activity. You build the yield from a rent call and a sale call.

What is self-serve:

• The Area Insights tools, including area-insights_get_heatmap, and comparables_get_comparables are self-serve on the Casafari API and MCP Platform. Comparables is self-serve over REST as well as MCP: the platform's REST comparables search takes the same input as comparables_get_comparables and returns the same answer.
• Existing Casafari clients sign up there too; contract clients are set up on the Custom plan.

Coverage limits:

• The API's permissions list 16 markets.
• The Area Insights tools take type_group apartment or house only.
• locations_search expects English names.
• The cadastral-reference input of comparables_get_comparables is Spain only.
• Other tools name no market.

Commercial and other types: see rentals and commercial.

#Property-level yield search is REST only

POST /api/v2/properties/search with gross_yield_from and gross_yield_to is available to Casafari client accounts over REST; the self-serve Property Sourcing search has no yield filter. It is not offered over Casafari MCP. Without REST, check yield property by property with comparables_get_comparables.

The sources give no figures for pricing, quotas, rate limits or data refresh frequency; ask Casafari.

#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 (50 tokens a page, property-sourcing_next_page for more), reads each home with property-sourcing_get_property (10 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 (25 tokens). Prices are asking prices. See Property Sourcing.

#Questions

All use cases