# How do I analyse a zip code or postcode area with Casafari?

> **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).

To analyse a postcode with Casafari, turn it into a boundary. The References operation `POST /api/v1/references/zipcode-boundary` takes `zip_code` and `country_code` and returns the zip code's boundary. Pass that boundary as a closed polygon to `comps_get-comparables`, property search or alert search. In Germany, AgentGraph AI tools accept 5-digit postcodes directly.

Products: [References](/docs/references), [Comparables & Valuation](/docs/comparables-valuation), [Property Sourcing](/docs/property-sourcing), [New Market Leads](/docs/alerts), [AgentGraph AI](/docs/agentgraph).

## Short answer

The References operation `POST /api/v1/references/zipcode-boundary` returns the boundary of a zip code. You then use that boundary in other calls:

- `comps_get-comparables` takes it as `location_boundary.polygon`.
- Property search (`POST /api/v2/properties/search`) takes it as `custom_location_boundary`.
- Alert search takes it as `custom_location`.

Area Insights over MCP is different: it takes location ids or a circle, not polygons. In Germany, AgentGraph AI accepts 5-digit postcodes as input, so no boundary call is needed there.

## Steps

### POST /api/v1/references/zipcode-boundary with zip_code and country_code

1. Send `POST /api/v1/references/zipcode-boundary` with:
   - `zip_code`.
   - `country_code` (ISO 3166-1 alpha-2).

   The response format is documented on the [operation page](/docs/rest/references/get-zipcode-boundary-by-zipcode-and-country-code-v1).

### Pass the polygon: comps_get-comparables location_boundary.polygon (first and last points match, at least 4)

2. Call `comps_get-comparables` with `location_boundary.polygon`. The polygon must meet these rules:
   - It is a list of `latitude` and `longitude` objects.
   - It has at least 4 points.
   - The first and last points are the same.

   Also send the required `comparables_count` (1 to 50), `operation` and `comparables_types`.

### `POST /api/v2/properties/search` custom_location_boundary; `POST /api/v1/listing-alerts/search` custom_location

3. For property search, send `POST /api/v2/properties/search` with `custom_location_boundary`, which accepts a polygon of geo-points or a circle.
4. For alert search, send `POST /api/v1/listing-alerts/search` with `custom_location`, a closed polygon. Alert search also accepts `custom_locations`, a list of polygons, for several postcodes at once.

### Reverse lookup: GET /api/v1/references/locations/by-coordinates

5. To find which location in Casafari's location tree contains a point, call `GET /api/v1/references/locations/by-coordinates` (Casafari client accounts). Its parameters are on the [operation page](/docs/rest/references/get-location-by-passed-coordinates-v1).

### In Germany: agentgraph_screen_agencies with zipcodes

6. In Germany, call `agentgraph_screen_agencies` with `zipcodes`, a list of up to 200 five-digit postcodes. You can add a `location` as well, and a 5-digit `location` value is read as a postcode. `agentgraph_screen_agents` and `agentgraph_area_benchmark` take `zipcodes` the same way.

## Example: a Lisbon postcode

Goal: *"What are 2-bedroom apartments for sale in postcode 1200, Lisbon, worth?"*

First, a Casafari client account requests the boundary over REST:

```json
{"zip_code": "1200", "country_code": "PT"}
```

Then the boundary's points go into `comps_get-comparables`. An assistant or script can make this call over MCP:

```json
{
  "comparables_count": 20,
  "location_boundary": {"polygon": [
    {"latitude": LAT_1, "longitude": LON_1},
    {"latitude": LAT_2, "longitude": LON_2},
    {"latitude": LAT_3, "longitude": LON_3},
    {"latitude": LAT_1, "longitude": LON_1}
  ]},
  "operation": "sale",
  "comparables_types": ["apartment"],
  "bedrooms": 2
}
```

In practice, the polygon carries every boundary point, closed on the first one. Read the result in this order:

- `estimated_prices` for a value range: `fast_sell_price`, `fair_market_price` and `out_of_market_price`.
- `statistics` for `average_price_per_sqm` and `average_time_on_the_market`.
- `results` for the comparable properties, each with a `similarity_score` between 0 and 1.

The figures come from the live calls; these docs publish none.

## How to read the result

### distance is not calculated for polygon searches

In polygon searches, `distance` in each comparable is not calculated. Rank comparables by `similarity_score`, which shows how close each property's parameters are to the ones you requested.

### Location breadcrumbs for the containing district

Each comparable carries `location` and `locations_structure`. `locations_structure` lists every parent location up to the country, and both include `zip_codes` where known. Use them to name the district that contains the postcode. Over MCP, `ma_get_location_typeahead` returns the same kind of parent chain as `breadcrumbs`.

## Limits

Availability for Casafari client accounts:

- The References operations: zip-code boundary, the REST typeahead, `POST /api/v1/references/locations` and the REST by-coordinates lookup.
- Property Sourcing's `POST /api/v2/properties/search`.
- Alert search.

Availability over the Casafari MCP server, for Casafari clients with MCP access:

- `comps_get-comparables`, which accepts the polygon.
- AgentGraph AI, whose tools take 5-digit postcodes directly. Its tool descriptions name Germany only.
- Self-serve access for new users is coming soon, for these and for the property search.

Coverage:

- Spanish cadastral references are an alternative target point in `comps_get-comparables`; that input is Spain only.
- See [per-tool coverage](/docs/faq/per-tool-coverage).

### The REST typeahead takes country codes ES or PT

`POST /api/v1/references/locations/typeahead` accepts:

- `country_codes`: `ES` and `PT` only.
- `name`.
- `size`: default 30, maximum 100.
- `lang`: `en`, `pt`, `es` or `de`.

For other markets, use `POST /api/v1/references/locations` with `name` or `zip_codes`.

### Area Insights MCP boundaries are location ids or a circle, not polygons

The Area Insights MCP tools take `location_ids` (up to 10) or a `circle` of 50 to 50,000 metres. A zip-code polygon cannot be passed to them directly.

## Questions

### Can I get a price trend for a single postcode?

Only approximately over MCP. Area Insights tools take location ids or a circle, not polygons. You can pass a circle of 50 to 50,000 metres centred inside the postcode. Or, as a client account, find a matching location id with `POST /api/v1/references/locations` and its `zip_codes` filter, then use it in `ma_get_time_series_data`. A circle will not follow the postcode's exact boundary.

### Which countries does the zip-code boundary operation support?

The hub publishes no country list for `POST /api/v1/references/zipcode-boundary`. The operation takes a `zip_code` and an ISO 3166-1 alpha-2 `country_code`. The API's permissions cover 16 markets, but support for a given country's postcodes is not stated. Check the operation page or ask Casafari at https://www.casafari.com/ before you rely on a specific country.

### Can I search several postcodes at once?

It depends on the operation. Alert search accepts `custom_locations`, a list of closed polygons. Property search accepts a list of `location_ids`. In Germany, AgentGraph AI tools accept up to 200 five-digit postcodes in `zipcodes`. `comps_get-comparables` takes one polygon or one circle per request, so for comparables run one request per postcode.

### How do I find the location id for a postcode?

Over REST, as a Casafari client account, send `POST /api/v1/references/locations` with `zip_codes`; it returns matching locations from the location tree. In Spain and Portugal, the REST typeahead also finds locations by name. Over MCP, `ma_get_location_typeahead` takes English place names; its description does not say it accepts postcodes. Comparables results also show `zip_codes` inside each `location`.

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