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

> **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'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' `ma_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 `comps_get-comparables` results.

Products: [Area Insights](/docs/area-insights), [References](/docs/references), [Property Sourcing](/docs/property-sourcing), [Comparables & Valuation](/docs/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 `ma_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 `comps_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](/docs/property-graph)).

## Steps

### Resolve the area

1. Call `ma_get_location_typeahead` 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 `comps_get-comparables` uses kilometers.

### ma_get_time_series_data with business_type rent and avg_price_psqm; repeat with business_type sale

2. Call `ma_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 `ma_get_time_series_operations` with `mean` or `movavg_last_3` on each series. That tool is available over MCP only.

### Segment by bedrooms with ma_get_bedrooms_distribution for both operations

5. Call `ma_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](/docs/rest/property-sourcing/search-properties-v2).

### Validate a target: comps_get-comparables and the gross_yield field

7. Call `comps_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. `list_servers`.
2. `ma_get_location_typeahead` with `Porto`.
3. `ma_get_bedrooms_distribution` with `type_group` `apartment`, `bedrooms_range` min 1 and max 1, `business_type` `rent`.
4. The same call with `business_type` `sale`.
5. Optionally, `ma_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:

```json
{
  "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

`comps_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.

Availability:

- The Area Insights tools, including `ma_get_heatmap`, and `comps_get-comparables` are available to Casafari clients with MCP access, using their Casafari account.
- Self-serve access for new users is coming soon, for these tools and for the property search.

Coverage limits:

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

Commercial and other types: see [rentals and commercial](/docs/faq/rentals-and-commercial).

### Property-level yield search is REST only

`POST /api/v2/properties/search` with `gross_yield_from` and `gross_yield_to` is for Casafari client accounts and is not offered over Casafari MCP. Without it, check yield property by property with `comps_get-comparables`.

The sources give no figures for pricing, quotas, rate limits or data refresh frequency; ask [Casafari](https://www.casafari.com/).

## Questions

### Is gross_yield based on asking prices?

These docs do not document how `gross_yield` is calculated. The field is defined only as gross yield in percentage, on `comps_get-comparables` results and as a filter on `POST /api/v2/properties/search`. The area yield you compute from Area Insights uses advertised prices, and the product's own example speaks of asking price per m². For the exact method behind `gross_yield`, ask Casafari at https://www.casafari.com/.

### Can I compare yields across districts in one go?

Yes. Use `ma_get_heatmap`, which returns a value for each child location of a `location_id`, such as the districts of a city. Call it with `data_point` `avg_price_psqm` once with `business_type` `rent` and once with `sale`, then divide per district after annualising rent. The heatmap includes only active properties. `ma_get_time_series_data` returns one series per call, not one per district.

### Can I get a yield heatmap?

Not directly, because `ma_get_heatmap` has no yield `data_point`. Build the heatmap yourself: run `ma_get_heatmap` twice on the same `location_id`, `type_group` and `date_range`, once for rent and once for sale `avg_price_psqm`. Then divide each district's annualised rent value by its sale value. Each row's `location_id` and `location_name` let you join the two results and draw the map.

### How do I move from gross to net yield?

Subtract your own costs, because Casafari data does not include them. The calculation is net yield = (annual rent − taxes, maintenance, management, insurance, fees and expected vacancy) ÷ purchase price, including your purchase costs. None of these inputs are in the Area Insights, comparables or property search fields. Use your own figures or an adviser's for each market.

All use cases: [Use cases](/docs/use-cases#investment).