Estates

Resource type: estate

Returns a list of estates.

The parameter filterid can be used to restrict the selection of estates. With self-created filters from enterprise you could e.g. retrieve the last modified estates. Or you can use the parameter filter to specify the filter expression directly in the API call.

In addresses, estates and other modules you can set relations like e.g. tenant, buyer, owner, contact person, estate units etc. These relations are not queried and set via estate or address calls, but this information is queried or set via the API calls “Create, Modify, Delete and Get relations”. For more information on the relations of the multi-property module, which manages property complexes, see here.

To read out estate images on the “Files” tab, use the calls for images Estate images published on Homepage and Estate files.

If you work with multilingual estates, you must use the estatelanguage parameter if you want to retrieve other language versions of the estates. The main language in your client is the set system language (Extras >> Settings >> Basic settings, on botton left of the page). The parameter addestatelanguage is generally useful when working with multilingual real estates. See the example below.

You can find more information about multilingual estates via API here.

A general explanation of multilingual real estate can be found in the online help.

Parameters:

  • data
    ARRAY of fields that you want to read. All fields specified in the enterprise administration are valid here.
    If you want to read out the marketing status of an estate, you need you include verkauft and reserviert in the parameter data. In the response verkauft = 1 defines the marketing status “Sold” or “Rented”, depeding on the marketing method. reserviert = 1 stands for the marketing status “Reserved”.  verkauft = 0 and reserviert = 0 represent the marketing status “Open”.
  • filterid
    INTEGER. Filter-ID. This parameter can also be used to restrict the selection of estates via estate filters created in enterprise. The filter IDs of your created filters can be read out via the API call Filter. For more information about filters, see our online help.
  • filter
    OBJECT. Key: field, value: array of objects with filter expressions in the format "status": [{"op": "=", "val": 1}]. With op you specify the operator. Possible values for op are the following SQL operators:
    is or =, >, <, >=, <=, != or <>, between, like, not like, in, not in

    For the operator like the value % can be specified as a placeholder.

    With val you specify the value which should be applied to the filtering. The individual filter expressions are linked with the AND operation. See also the example below.

  • listlimit
    INTEGER. Maximum number of estates in the list. Default value: 20, maximum: 500.
  • listoffset
    INTEGER. Offset of the list, that means from which data record onwards the list should be output.
  • sortby
    OBJECT. Fields to sort by. The field name is used as the key, and the type of sorting as the value. Notation: {"kaufpreis": "ASC", "warmmiete": "DESC"}
    Possible values for sorting are ASC for ascending, DESC for descending. It is also possible to specify only field names without sort information and use sortorder together with parameters, e.g. "sortby": "kaufpreis".
  • sortorder
    STRING. Possible values: ASC or DESC. Ascending or descending. Only applicable if sortby was specified as a string without sorting information, e.g. "sortby": "kaufpreis".
  • formatoutput
    BOOLEAN. Enable formatted output. If set to true, the contents of the single- and multi-select fields (column content in the enterprise administration on tabs singleselect und multiselect) instead of the field (column field in the administration on tabs singleselect und multiselect) are outputted.
    Fields that represent, for example, prices, areas, quantities, are also returned with the corresponding unit (€, qm² etc).
  • estatelanguage
    STRING. Language of the object, only relevant for multi-language estates. Specified in ISO format with 3 characters, e.g. DEU, ENG. You cannot query properties in a different language without specifying this parameter. Only the ID is not sufficient! You can only query directly via ID if the property is in the main language.
  • outputlanguage
    STRING. Output language. E.g. the contents of the single- and multi-select fields are output in the specified language. Parameter formatoutput must be set to true.
  • addestatelanguage
    BOOLEAN. Adds estate language to the response. If set to true, in the result language is set to the A3 abbreviation of the language if it is a multilingual estate, or an empty string if the estate is in the default language.
  • addMainLangId
    BOOLEAN. Adds the estate ID of the estate in the main language to the response.
  • georangesearch
    OBJECT. Radius search. Syntax: "georangesearch": {"country": "DEU", "zip": 52068, "radius": 10 }. country and radius are mandatory. Instead of zip, also city can be used as center of the radius search. zip gives more exact results usually.
    The second variant of the radius search is based on geocoordinates. Syntax: "georangesearch": {"latitude": 50, "longitude": 6, "radius": 100 }. See example below for usage.

Example: active property with purchase price < 300000

...
{
	"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
	"resourceid": "",
	"identifier": "",
	"resourcetype": "estate",
	"parameters": {
		"data":["Id", "kaufpreis", "lage"],
		"filter": {
			"status": [{"op": "=", "val": 1}],
			"kaufpreis": [{"op": "<", "val": 300000}]
		},
		"listlimit": 100,
		"listoffset": 0,
		"sortby": {"kaufpreis": "ASC", "warmmiete": "ASC"}
	}
}
...

Example: Real estate changed after 01.01.2018

...
{
    "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
    "resourceid": "",
    "identifier": "",
    "resourcetype": "estate",
    "parameters": {
        "data":["Id", "kaufpreis", "lage"],
        "filter": {
            "geaendert_am": [{"op": "<", "val": "2018-01-01 00:00"}]
        }
    }
}
...

Example: Filter estates by “last change”

{
    "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
    "resourceid": "",
    "identifier": "",
    "resourcetype": "estate",
    "parameters": {
        "data":["Id", "kaufpreis", "lage"],
        "filterid":109,
        "sortby": {"kaufpreis": "ASC", "warmmiete": "ASC"}
    }
}

The expression used in the filter is: `ObjTech`.`geaendert_am` >= '2018-01-01 00:00' AND `ObjTech`.`geaendert_am` <= '2018-01-31 23:59'

Example: Marketing status

{
    "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
    "resourceid": "",
    "identifier": "",
    "resourcetype": "estate",
    "parameters": {
        "data":["Id", "kaufpreis", "reserviert", "verkauft"],
        "filter": {
            "status": [{"op": "=", "val": 1}],
            "kaufpreis": [{"op": "<", "val": 300000}]
        }
    }
}

Example: Usage of georange (Umkreissuche)

{
    "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
    "resourceid": "",
    "identifier": "",
    "resourcetype": "estate",
    "parameters": {
        "data":["Id", "kaufpreis", "laengengrad", "breitengrad", "ort"],
        "filter": {
            "status": [{"op": "=", "val": 1}],
            "kaufpreis": [{"op": "<", "val": 300000}]
        },
		"georangesearch": {
			"country": "DEU",
			"zip": 52068,
			"radius": 10
		},
        "listoffset": 0
    }
}

Example: Multilingual estate

...
    {
        "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
        "resourceid": "4457",
        "identifier": "",
        "resourcetype": "estate",
        "parameters": {
            "data": [
                "Id",
                "objekttitel",
                "kaufpreis"
            ],
            "estatelanguage": "ENG",
            "addestatelanguage": true,
            "addMainLangId": true
        }
    }
...

Response: Multilingual estate

{
    "status": {
        "code": 200,
        "errorcode": 0,
        "message": "OK"
    },
    "response": {
        "results": [
            {
                "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:read",
                "resourceid": "4457",
                "resourcetype": "estate",
                "cacheable": true,
                "identifier": "",
                "data": {
                    "meta": {
                        "cntabsolute": 1
                    },
                    "records": [
                        {
                            "id": 4483,
                            "type": "estate",
                            "elements": {
                                "Id": "4483",
                                "objekttitel": "A nice home!",
                                "kaufpreis": "0.00",
                                "mainLangId": "4457",
                                "language": "ENG"
                            }
                        }
                    ]
                },
                "status": {
                    "errorcode": 0,
                    "message": "OK"
                }
            }
        ]
    }
}