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 (v2)

POSThttps://api.casafari.com/api/v2/properties/search
Bearer token80 parameters

Send Authorization: Bearer $CASAFARI_TOKEN; see how to get a token.

Over MCP: no tool does this. MCP and REST compared.

Description

Search properties.

Query parameters

limitinteger
Number of results to return per page.
≤ 100default 20
orderstring
The order of search results.
asc desc
default "asc"
order_bystring
The field by which to sort the results.
price price_per_sqm total_area plot_area bedrooms construction_year last_update time_on_market

Request body

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

search_operationsstring[]required
Search business types for which the property is available.
sale sold sale_hold rent rented rent_hold
location_idsinteger[]
List of location IDs, as returned by the POST /api/v1/references/locations endpoint.
at most 100 items1–2147483647
custom_location_boundaryobject
Custom location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided.
3 properties
polygonobject[]
Closed polygon of geo-points to search within. First and last points must match. This field is deprecated and will be removed in the next major update. Please, use polygons field instead.
at least 4 items
2 properties
latitudenumberrequired
Latitude.
-90–90
longitudenumberrequired
Longitude.
-180–180
circleobject
Circle boundary to search within.
2 properties
distancenumber
Maximum distance in kilometers from the requested target_point to the properties.
0.05–50default 5
target_pointobjectrequired
Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided.
3 properties
coordinatesobject
Target point coordinates to search around.
2 properties
latitudenumberrequired
Latitude.
-90–90
longitudenumberrequired
Longitude.
-180–180
addressstring
Address of the property to define the point to search around.
cadastral_referenceobject
Cadastral reference of the property to define the point to search around. For now available only for Spain.
4 properties
country_codestringrequired
Country code following the ISO 3166-1 alpha-2 rules.
ES
cadastral_referencestringrequired
Cadastral reference of the estate.
provincestring
Name of the estate's province.
municipalitystring
Name of the estate's municipality.
polygonsobject[][]
List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed.
at most 4 items
2 properties
latitudenumberrequired
Latitude.
-90–90
longitudenumberrequired
Longitude.
-180–180
conditionsstring[]
Property condition, as returned by the GET /api/v1/references/conditions endpoint.
used ruin very-good new other
property_date_fromstring (date)
Start date (in the format YYYY-MM-DD) of the period for property of interest.
property_date_tostring (date)
End date (in the format YYYY-MM-DD) of the period for property of interest.
created_date_fromstring (date-time)
Created date from (in the format YYYY-MM-DDTHH:mm:ss).
created_date_tostring (date-time)
Created date to (in the format YYYY-MM-DDTHH:mm:ss).
updated_date_fromstring (date-time)
Updated date from (in the format YYYY-MM-DDTHH:mm:ss).
updated_date_tostring (date-time)
Updated date to (in the format YYYY-MM-DDTHH:mm:ss).
price_frominteger
Minimum price value.
1–2147483647
price_tointeger
Maximum price value.
1–2147483647
price_per_sqm_frominteger
Minimum value for price per square meter.
1–2147483647
price_per_sqm_tointeger
Maximum value for price per square meter.
1–2147483647
bedrooms_frominteger
Minimum number of bedrooms.
0–15000
bedrooms_tointeger
Maximum number of bedrooms.
0–15000
bathrooms_frominteger
Minimum number of bathrooms.
1–15000
bathrooms_tointeger
Maximum number of bathrooms.
1–15000
total_area_frominteger
Minimum total area.
1–10000000
total_area_tointeger
Maximum total area.
1–10000000
plot_area_frominteger
Minimum plot area.
1–10000000
plot_area_tointeger
Maximum plot area.
1–10000000
construction_year_frominteger
Minimum construction year.
1–3000
construction_year_tointeger
Maximum construction year.
1–3000
floorstring
Floor type. This field is deprecated and will be removed in the next major update. Please, use floors field instead.
no_floor ground middle top
floorsstring[]
List of floor types.
no_floor ground middle top
orientationstring
Property view orientation.
exterior interior
viewstring
View from the property. This field is deprecated and will be removed in the next major update. Please, use views field instead.
water landscape city golf park
viewsstring[]
List of views from the property.
water landscape city golf park
directionstring
Cardinal direction the property faces. This field is deprecated and will be removed in the next major update. Please, use directions field instead.
north south east west
directionsstring[]
List of cardinal directions the property faces.
north south east west
characteristicsobject
Property characteristics. The field was changed from Array of strings to object. Backwards compatibility is still supported.
2 properties
must_havestring[]
Include only properties that have all these characteristics.
balcony elevator no_elevator garage garden parking storage swimming_pool terrace rental_license furniture rented_out life_annuity
excludestring[]
Exclude properties that contain any of these characteristics.
balcony elevator no_elevator garage garden parking storage swimming_pool terrace rental_license furniture rented_out life_annuity
typesstring[]
Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: apartment: penthouse, apartment, dachgeschosswohnung, erdgeschosswohnung, duplex, etagenwohnung, studio house: einfamilienhaus, family_house (DEPRECATED), reihenmittelhaus, house, villa, country_house, zweifamilienhaus, landwirtschaftliche_betriebe, palace, bungalow, townhouse, reihenhaus, chalet, country_estate, reihenendhaus room: room building: mix_use_building, office_building, apartment_building investment: other_commercial, warehouse, office, retail, hotel, werkstatt, industrial, restaurant plot: urban_plot, plot (DEPRECATED), rural_plot other: garage, other, parking
40 allowed valuesapartment studio duplex penthouse dachgeschosswohnung etagenwohnung erdgeschosswohnung country_house house palace townhouse villa country_estate chalet bungalow family_house reihenhaus reihenendhaus reihenmittelhaus einfamilienhaus zweifamilienhaus landwirtschaftliche_betriebe retail office industrial warehouse hotel other_commercial restaurant werkstatt plot urban_plot rural_plot room other garage parking apartment_building office_building mix_use_building
property_typesstring[]
Property types, as returned by the GET /api/v1/references/types endpoint. This field is deprecated and will be removed in the next major update. Please, use types field instead.
40 allowed valuesapartment studio duplex penthouse dachgeschosswohnung etagenwohnung erdgeschosswohnung country_house house palace townhouse villa country_estate chalet bungalow family_house reihenhaus reihenendhaus reihenmittelhaus einfamilienhaus zweifamilienhaus landwirtschaftliche_betriebe retail office industrial warehouse hotel other_commercial restaurant werkstatt plot urban_plot rural_plot room other garage parking apartment_building office_building mix_use_building
privateboolean
Whether to return properties listed by a private individual, as opposed to an agent or a professional.
auctionboolean
Whether to return auction properties. (If the bank filter is also set, the result will contain both auction and bank properties)
bankboolean
Whether to return bank properties. (If the auction filter is also set, the result will contain both bank and auction properties)
casafari_connectboolean
Whether to return properties that have at least one listing with a company connected to Casafari Connect.
listing_agentsstring[]
Return properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint.
with_agenciesstring[]
Return properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint.
without_agenciesstring[]
Exclude properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint.
exclusiveboolean
Whether to return properties that are available on market exclusively from a single agency or private individual. Can be passed only along with at least one of the fields: private, with_agencies, without_agencies.
ref_numbersstring[]
List of reference numbers from listings.
energy_certificatestring
Energy certificate. This field is deprecated and will be removed in the next major update. Please, use energy_ratings field instead.
Unknown A+ A B C D E F G H
energy_certificatesstring[]
List of energy certificates. This field is deprecated and will be removed in the next major update. Please, use energy_ratings field instead.
Unknown A+ A B C D E F G H
energy_ratingsstring[]
List of energy ratings.
Unknown A+ A B C D E F G H
days_on_market_frominteger
Minimum days on market value.
1–10000
days_on_market_tointeger
Maximum days on market value.
1–10000
gross_yield_fromnumber
Minimum gross yield value.
1–20
gross_yield_tonumber
Maximum gross yield value.
1–20
rooms_frominteger
Minimum number of rooms.
1–15000
rooms_tointeger
Maximum number of rooms.
1–15000
number_of_parkings_frominteger
Minimum number of parking spaces.
1–15000
number_of_parkings_tointeger
Maximum number of parking spaces.
1–15000
living_area_frominteger
Minimum living area.
1–10000000
living_area_tointeger
Maximum living area.
1–10000000
floor_numbersinteger[]
Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250.
-250–250

Example request

Placeholders only: replace the token and the values with your own. Tested against the API on 2026-10-12: 2-3 bedroom apartments for sale in Lisbon (city, location 1600), EUR 300k-700k: 2,398 results when tested.

curl
curl -X POST "https://api.casafari.com/api/v2/properties/search" \
  -H "Authorization: Bearer $CASAFARI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "search_operations": [
    "sale"
  ],
  "types": [
    "apartment"
  ],
  "location_ids": [
    1600
  ],
  "bedrooms_from": 2,
  "bedrooms_to": 3,
  "price_from": 300000,
  "price_to": 700000
}'

Responses

200 OK

Type: object[].

Show the response shape (168 fields)
property_idintegerrequired
ID of the property.
primary_listing_idintegerrequired
Primary listing (ad) ID of the property which is defined after the matching into property.
typestringrequired
Property type, as returned by the GET /api/v1/references/types endpoint.
40 allowed valuesapartment studio duplex penthouse dachgeschosswohnung etagenwohnung erdgeschosswohnung country_house house palace townhouse villa country_estate chalet bungalow family_house reihenhaus reihenendhaus reihenmittelhaus einfamilienhaus zweifamilienhaus landwirtschaftliche_betriebe retail office industrial warehouse hotel other_commercial restaurant werkstatt plot urban_plot rural_plot room other garage parking apartment_building office_building mix_use_building
type_groupstringrequired
Property type group, as returned by the GET /api/v1/references/types endpoint.
operationsstring[]required
Operation types for which property is available.
sale rent
locationobjectrequired
Information about property location.
4 properties
location_idintegerrequired
Location ID, as returned by the POST /api/v1/references/locations endpoint.
namestringrequired
Location name.
administrative_levelstringrequired
Location administrative level.
zip_codesstring[]
The location zip codes.
default []
locations_structureobject[]required
Information about all the parent locations (including property location) up to the country.
4 properties
location_idintegerrequired
Location ID, as returned by the POST /api/v1/references/locations endpoint.
namestringrequired
Location name.
administrative_levelstringrequired
Location administrative level.
zip_codesstring[]
The location zip codes.
default []
coordinatesobjectrequired
Property coordinates.
2 properties
latitudenumberrequired
Latitude.
longitudenumberrequired
Longitude.
total_areaintegerrequired
Total area.
living_areaintegerrequired
Living area.
plot_areaintegerrequired
Plot area.
terrace_areaintegerrequired
Terrace area.
bathroomsintegerrequired
Number of bathrooms.
bedroomsintegerrequired
Number of bedrooms.
roomsintegerrequired
Number of rooms.
number_of_parkingsintegernullable
Number of parking spaces.
floor_numberintegerrequired
Exact floor number. Negative values indicate underground floors (e.g. basements).
rent_currencystringrequired
Rent price currency code.
rent_periodstringrequired
Rent period.
day week fortnight month year none
rent_priceintegerrequired
Current rent price, in the currency of the listings (specified by the rent_currency field).
rent_statusstringrequired
Current rent status of the property.
active reserved hold rented none
sale_currencystringrequired
Sale price currency code.
sale_priceintegerrequired
Current sale price, in the currency of the listings (specified by the sale_currency field).
sale_statusstringrequired
Current sale status of the property.
active reserved hold sold none
is_private_propertybooleanrequired
Whether the property is listed by a private individual, as opposed to an agent or a professional.
featuresobjectrequired
Property features, as returned by the GET /api/v1/references/features endpoint.
7 properties
floorstringrequired
Floor type.
no_floor ground middle top
orientationstringrequired
Property view orientation.
exterior interior
viewstringrequired
View from the property. This field is deprecated and will be removed in the next major update. Please, use views field instead.
water landscape city golf park
viewsstring[]required
List of views from the property.
water landscape city golf park
directionstringrequired
Cardinal direction the property faces. This field is deprecated and will be removed in the next major update. Please, use directions field instead.
north south east west
directionsstring[]required
List of cardinal directions the property faces.
north south east west
characteristicsstring[]required
Property characteristics.
balcony elevator no_elevator garage garden parking storage swimming_pool terrace rental_license furniture rented_out life_annuity
conditionstringrequired
Property condition, as returned by the GET /api/v1/references/conditions endpoint.
used ruin very-good new other
sale_time_on_marketobjectrequired
Information about the property last activity on the sales market.
4 properties
date_startstring (date)required
Start date of activity on the market.
date_endstring (date)required
End date of activity on the market.
days_on_marketintegerrequired
Number of days property was / is on the market.
has_untracked_periodbooleanrequired
Whether the property was already on the market when it started being tracked.
rent_time_on_marketobjectrequired
Information about the property last activity on the rental market.
4 properties
date_startstring (date)required
Start date of activity on the market.
date_endstring (date)required
End date of activity on the market.
days_on_marketintegerrequired
Number of days property was / is on the market.
has_untracked_periodbooleanrequired
Whether the property was already on the market when it started being tracked.
listingsobject[]required
The list of listings related to the property.
36 properties
listing_idintegerrequired
ID of the listing (ad).
total_areaintegerrequired
Total area.
plot_areaintegerrequired
Plot area.
terrace_areaintegerrequired
Terrace area.
bedroomsintegerrequired
Number of bedrooms.
bathroomsintegerrequired
Number of bathrooms.
roomsintegerrequired
Number of rooms.
sale_statusstringrequired
Current sale status of the listing.
active reserved hold sold none
sale_currencystringrequired
Sale price currency code.
sale_priceintegerrequired
Current sale price, in the currency of the listing (specified by the sale_currency field).
sale_price_baseintegerrequired
Current sale price, in Euros.
rent_statusstringrequired
Current rent status of the listing.
active reserved hold rented none
rent_currencystringrequired
Rent price currency code.
rent_priceintegerrequired
Current rent price, in the currency of the listing (specified by the rent_currency field).
rent_price_baseintegerrequired
Current rent price, in Euros.
agency_legal_idstringrequired
Agency legal identifier specified on the source. Only for France and its overseas territories(DROM and COM).
agencystringrequired
The company that manages the listing.
listing_urlstringnullable
URL of the listing. Available only for currently active listings.
listing_old_urlstringnullable
Old URL of the listing. Available only for currently inactive listings.
descriptionstringrequired
Property description.
listing_uidstringrequired
Unique ID of the listing on the source site.
construction_yearintegerrequired
Construction year.
source_namestringrequired
The name of the source where the listing is displayed.
contacts_infoobjectrequired
Information about listing contacts.
3 properties
namestringrequired
The owner name. Only for FSBO listings.
emailstring (email)required
The email contact.
phonestringrequired
The phone contact.
energy_certificatestringrequired
Energy certificate classification that attests to the energy efficiency of a property. This field is deprecated and will be removed in the next major update. Please, use energy_rating field instead.
energy_ratingstringrequired
Energy rating that attests to the energy efficiency of a property.
heating_typestringrequired
Type of heating.
ceiling_labelstringrequired
Ceiling height in meters. Available only for Germany.
commissionnumberrequired
Commission percentage. Available only for Germany.
min_rent_areaintegerrequired
Minimum rental area in square meters (mainly applicable to commercial properties). Available only for Germany.
companiesobject[]required
Companies to which the listing belongs.
2 properties
namestringrequired
Company name.
casafari_connect_onbooleanrequired
Whether the company is connected to Casafari Connect.
created_atstring (date)required
The datetime when the listing was added.
floor_numberintegerrequired
Exact floor number. Negative values indicate underground floors (e.g. basements).
is_privatebooleanrequired
Whether the listing is listed by a private individual, as opposed to an agent or a professional.
casafari_connectbooleanrequired
Whether the company is connected to Casafari Connect.
thumbnailsstring[]
List of the thumbnail image URLs.
historyobject[]
List of sale and rent price history data. This field is deprecated and will be removed in the next major update. Please, use sale_price_history and rent_price_history field instead.
default []
5 properties
sale_priceintegerrequired
Sale price, in the currency of the listings (specified by the sale_currency field).
sale_currencystringrequired
Sale price currency code.
rent_priceintegerrequired
Rent price, in the currency of the listings (specified by the rent_currency field).
rent_currencystringrequired
Rent price currency code.
changed_atstring (date)required
Date when the estate was last updated.
sale_price_historyobject[]
List of sale price history data.
default []
4 properties
date_startstring (date)required
Start date when the change was applied.
date_endstring (date)required
End date when the change was applied.
sale_price_oldintegerrequired
Old sale price, in the currency of the listings.
sale_price_newintegerrequired
New sale price, in the currency of the listings.
rent_price_historyobject[]
List of rent price history data.
default []
4 properties
date_startstring (date)required
Start date when the change was applied.
date_endstring (date)required
End date when the change was applied.
rent_price_oldintegerrequired
Old rent price, in the currency of the listings.
rent_price_newintegerrequired
New rent price, in the currency of the listings.
sale_status_historyobject[]
List of sale status history data.
default []
4 properties
date_startstring (date)required
Start date when the change was applied.
date_endstring (date)required
End date when the change was applied.
sale_status_oldstringrequired
Old sale status, in the currency of the listings.
sale_status_newstringrequired
New sale status, in the currency of the listings.
rent_status_historyobject[]
List of rent status history data.
default []
4 properties
date_startstring (date)required
Start date when the change was applied.
date_endstring (date)required
End date when the change was applied.
rent_status_oldstringrequired
Old rent status, in the currency of the listings.
rent_status_newstringrequired
New rent status, in the currency of the listings.
property_urlstringnullable
URL of the property in the CASAFARI website.
addressstringrequired
Property address.
zip_codestringrequired
The location zip code.
distancenumbernullable
Distance in kilometers from target point to the property.Available only when the custom_location_boundary.circle field is defined in the request.
descriptionstringrequired
Property description.
construction_yearintegerrequired
Construction year.
rent_price_baseintegerrequired
Current rent price, in Euros.
rent_price_per_sqmnumberrequired
Current rent price per square meter, in the currency of the listings (specified by the rent_currency field).
rent_price_per_sqm_basenumberrequired
Current rent price per square meter, in Euros.
sale_price_baseintegerrequired
Current sale price, in Euros.
sale_price_per_sqmnumberrequired
Current sale price per square meter, in the currency of the listings (specified by the sale_currency field).
sale_price_per_sqm_basenumberrequired
Current sale price per square meter, in Euros.
is_auction_propertybooleanrequired
Whether the property is an auction property.
is_bank_propertybooleanrequired
Whether the property is a bank property.
changed_atstring (date)required
The date and time when the property was last updated.
sale_price_last_changeobjectrequired
Information about the last change of sale price.
3 properties
change_datestring (date)required
Date of the change.
old_valueintegerrequired
Value before change.
new_valueintegerrequired
Value after change.
rent_price_last_changeobjectrequired
Information about the last change of rent price.
3 properties
change_datestring (date)required
Date of the change.
old_valueintegerrequired
Value before change.
new_valueintegerrequired
Value after change.
thumbnailsstring[]
List of the thumbnail image URLs.
picturesstring[]
List of the original picture image URLs.
gross_yieldnumberrequired
Gross yield in percentage.
titlestringrequired
Property title.
energy_certificatestringrequired
Energy certificate classification that attests to the energy efficiency of a property. This field is deprecated and will be removed in the next major update. Please, use energy_rating field instead.
energy_ratingstringrequired
Energy rating that attests to the energy efficiency of a property.
ceiling_labelstringrequired
Ceiling height in meters. Available only for Germany.
min_rent_areaintegerrequired
Minimum rental area in square meters (mainly applicable to commercial properties). Available only for Germany.
ref_numbersstring[]
List of reference numbers from listings.
casafari_connectbooleanrequired
Whether the company is connected to Casafari Connect.
source_floor_numbersinteger[]
List of property floor numbers based on listings data. Negative values indicate underground floors (e.g. basements).
default []
retail_dataobjectnullable
Retail-related attributes of the property. Null for non-commercial properties or if the retail data is not available.
6 properties
facade_measurementsobjectrequired
Facade measurements of the commercial property (height, length, surface in meters).
3 properties
heightnumberrequired
Facade height in meters.
lengthnumberrequired
Facade length in meters.
surfacenumberrequired
Facade surface area in square meters.
transfer_price_rangeobjectrequired
Price range if the property is available for transfer.
2 properties
gteintegerrequired
Lower bound of the transfer price range.
lteintegerrequired
Upper bound of the transfer price range.
is_street_levelbooleanrequired
Whether the commercial entrance is situated at the street level, without having to go upstairs/downstairs to reach it.
number_of_floorsintegerrequired
The number of commercial property floors.
number_of_premisesintegerrequired
The number of property usable rooms/premises.
possible_business_typesstring[]required
What kind of business can/did run in this commercial property (e.g. cafe, restaurant, grocery store, dental clinic).

400 Bad Request

Type: object.

Show the response shape (1 fields)
errorsobject
Description of the errors encountered.

401 Unauthorized

Type: object.

Show the response shape (1 fields)
detailstring
Description of the error encountered.

403 Forbidden

Type: object.

Show the response shape (1 fields)
detailstring
Description of the error encountered.

Questions about this

Esc

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