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 comparables_get_comparables, property search or alert search.

Products: References, Comparables & Valuation, Property Sourcing, New Market Leads

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

• comparables_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.

#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: comparables_get_comparables location_boundary.polygon (first and last points match, at least 4)

2. Call comparables_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), or Location Lookup's GET /v1/locations/by-coordinates on the self-serve platform, which takes lat and lon. Its parameters are on the operation page.

#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 comparables_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, locations_search 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. Zip-code boundary has no self-serve equivalent.
• Property Sourcing's POST /api/v2/properties/search.
• Alert search.

Availability on the self-serve Casafari API and MCP Platform:

• comparables_get_comparables, which accepts the polygon, over MCP and over REST.
• Location Lookup: GET /v1/locations/by-coordinates, plus search by name, get by id and children (the MCP tools locations_search and locations_get). locations_search also looks places up by postcode, free, over MCP and REST: exact or prefix match, the matching places smallest area first, and every location carries its postcodes. Postcode coverage is Spain fully and France partly; Portugal is not covered yet. They do not return a zip-code boundary.

Coverage:

• Spanish cadastral references are an alternative target point in comparables_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