Understand an area · Use case

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

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, Comparables & Valuation, Property Sourcing, New Market Leads, AgentGraph AI

#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.

#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.

#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:

{"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:

{
  "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.

#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

All use cases