Platform
Get started

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.The most complete property index in Europe: a deduplicated, cleaned property graph.

How the graph is built
Markdown Open in Claude Open in ChatGPT

Property Sourcing · REST API

Search properties

POSThttps://platform.casafari.com/v1/property-sourcing/searches
API key100 units per page26 parameters

Send Authorization: Bearer $CASAFARI_API_KEY: a platform API key or OAuth access token; see platform sign-in. Costs 100 units per page (1 unit = EUR 0.04).

Over MCP: none; this product is REST only.

Description

Structured search of the property graph: one request body for every country. Name the places with location_ids (find them with GET /v1/locations/search), then filter by property type, price, price per m², bedrooms, bathrooms, living and plot area and features, and sort. Each result is one property, however many listings advertise it, with an opaque prop_ id. next is a URL for the following page (valid for one hour, bound to your account) or null. Plain-language phrases go to POST /v1/property-sourcing/searches/describe. 100 units per page.

Request body

Content type application/json. Required. Type: object.

location_idsinteger[]required
1 to 100 location ids, from GET /v1/locations/search?query=<place>.
1–100 items
countrystring
ISO 3166-1 alpha-2 code, e.g. "ES". Needed when the location ids do not include the country's own id and the account covers more than one country.
operationstring
For sale or for rent.
sale rent
default "sale"
typesstring[]
Property type names in lower case, e.g. "apartment", "house", "villa".
at most 40 items
priceobject
Asking price range.
2 properties
mininteger
Lowest value, inclusive.
maxinteger
Highest value, inclusive.
price_per_sqmobject
Asking price per m² range.
2 properties
mininteger
Lowest value, inclusive.
maxinteger
Highest value, inclusive.
bedroomsobject
Bedrooms, 0 to 100.
2 properties
mininteger
Lowest value, inclusive.
maxinteger
Highest value, inclusive.
bathroomsobject
Bathrooms, 1 to 100.
2 properties
mininteger
Lowest value, inclusive.
maxinteger
Highest value, inclusive.
living_area_sqmobject
Living area in m².
2 properties
mininteger
Lowest value, inclusive.
maxinteger
Highest value, inclusive.
plot_area_sqmobject
Plot area in m².
2 properties
mininteger
Lowest value, inclusive.
maxinteger
Highest value, inclusive.
featuresstring[]
Features every result must have.
balcony elevator garage garden parking storage swimming_pool terrace rental_license furniture no_elevator rented_out life_annuity business_transfer smoke_outlet
exclude_featuresstring[]
Features no result may have.
balcony elevator garage garden parking storage swimming_pool terrace rental_license furniture no_elevator rented_out life_annuity business_transfer smoke_outlet
sortstring
Order of the results.
newest oldest recently_updated price_asc price_desc price_per_sqm_asc price_per_sqm_desc largest
page_sizeinteger
Results per page: up to 100 (25 on Free).
1–100default 25

Example request

Placeholders only: replace the token and the values with your own.

curl
curl -X POST "https://platform.casafari.com/v1/property-sourcing/searches" \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "location_ids": [
    12345
  ],
  "country": "ES",
  "operation": "sale",
  "types": [
    "apartment"
  ],
  "price": {
    "max": 450000
  },
  "bedrooms": {
    "min": 2
  },
  "features": [
    "terrace",
    "elevator"
  ],
  "sort": "newest",
  "page_size": 25
}'

Responses

200 One page of properties.

Type: object.

Show the response shape (21 fields)
resultsobject[]
10 properties
idstring
Opaque property id, prop_....
typestringnullable
Property type.
operationstring
sale rent
priceobject
3 properties
amountnumbernullable
Asking price; null when the price is on request.
currencystringnullable
ISO 4217 currency code.
per_sqmnumbernullable
Asking price per m².
bedroomsnumbernullable
living_area_sqmnumbernullable
locationobject
3 properties
idintegernullable
Location id.
namestringnullable
Location name.
coordinatesobjectnullable
Latitude and longitude.
2 properties
latnumber
lonnumber
first_seenstringnullable
When the property came on the market for this operation.
listings_countintegernullable
How many listings advertise it; known on a property read with expand=listings, null in search results.
matched_tagsstring[]nullable
The phrases of a plain-language search this property matched; null for structured searches.
totalintegernullable
How many properties match, when known.
nextstringnullable
URL of the next page (valid one hour), or null.
Example with sample values (ids and figures are illustrative)
JSON
{
  "results": [
    {
      "id": "prop_7Hq2pZk1vY0sW4nB8cR3tL",
      "type": "apartment",
      "operation": "sale",
      "price": {
        "amount": 425000,
        "currency": "EUR",
        "per_sqm": 4474
      },
      "bedrooms": 3,
      "living_area_sqm": 95,
      "location": {
        "id": 12345,
        "name": "Sample district",
        "coordinates": {
          "lat": 39.462,
          "lon": -0.376
        }
      },
      "first_seen": "2026-09-28",
      "listings_count": null,
      "matched_tags": null
    }
  ],
  "total": 312,
  "next": "https://platform.casafari.com/v1/property-sourcing/searches/cur_SAMPLE"
}

400 Invalid request: the problem names each field to fix (`invalid_request`), or `page_size` is over the plan's limit (`page_depth_exceeded`).

Type: object.

Show the response shape (10 fields)
typestring
The problem's documentation URL.
titlestring
statusinteger
detailstring
What happened and how to fix it.
instancestring
codestring
e.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstring
errorsobject[]
One entry per field to fix.
2 properties
fieldstring
messagestring

401 Missing or unknown API key or token.

Type: object.

Show the response shape (10 fields)
typestring
The problem's documentation URL.
titlestring
statusinteger
detailstring
What happened and how to fix it.
instancestring
codestring
e.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstring
errorsobject[]
One entry per field to fix.
2 properties
fieldstring
messagestring

402 No units left to fund the call (`payment_required`, with `reason` and an `upgrade_url`).

Type: object.

Show the response shape (10 fields)
typestring
The problem's documentation URL.
titlestring
statusinteger
detailstring
What happened and how to fix it.
instancestring
codestring
e.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstring
errorsobject[]
One entry per field to fix.
2 properties
fieldstring
messagestring

403 The account is not entitled to this product or country (`not_entitled`).

Type: object.

Show the response shape (10 fields)
typestring
The problem's documentation URL.
titlestring
statusinteger
detailstring
What happened and how to fix it.
instancestring
codestring
e.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstring
errorsobject[]
One entry per field to fix.
2 properties
fieldstring
messagestring

429 A request limit of the plan was reached (`request_limit_reached`, with `window` and `Retry-After`).

Type: object.

Show the response shape (10 fields)
typestring
The problem's documentation URL.
titlestring
statusinteger
detailstring
What happened and how to fix it.
instancestring
codestring
e.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstring
errorsobject[]
One entry per field to fix.
2 properties
fieldstring
messagestring
Esc

Tip: add .md to any URL to read it as Markdown.