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 values

apartment 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 values

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.

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": [
    "rented",
    "rent"
  ],
  "conditions": [
    "used"
  ],
  "location_ids": [
    499
  ],
  "custom_location_boundary": {
    "circle": {
      "distance": 30,
      "target_point": {
        "coordinates": {
          "latitude": 38.71,
          "longitude": -9.17
        }
      }
    }
  },
  "price_from": 800,
  "price_to": 10000,
  "price_per_sqm_from": 5,
  "price_per_sqm_to": 50,
  "bedrooms_from": 1,
  "bedrooms_to": 3,
  "bathrooms_from": 1,
  "bathrooms_to": 2,
  "rooms_from": 1,
  "rooms_to": 4,
  "total_area_from": 30,
  "total_area_to": 1000,
  "living_area_from": 20,
  "living_area_to": 800,
  "floor_numbers": [
    1,
    2,
    3
  ],
  "views": [
    "city"
  ],
  "directions": [
    "west",
    "south"
  ],
  "floors": [
    "middle",
    "top"
  ],
  "energy_ratings": [
    "A",
    "B",
    "C"
  ],
  "casafari_connect": true
}'

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 values

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

Search properties (v2)

#Description

#Query parameters

#Request body

#Example request

#Responses

#200 OK

#400 Bad Request

#401 Unauthorized

#403 Forbidden

#Questions about this

Description

Query parameters

Request body

Example request

Responses

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

Questions about this