Recommendations API

The (watchlist-) recommendations service provides for a particualar geo object and property type other geo objects and property types for which it is reasonable to also search for. Geo object in this context means either a location from the geo hierarchy (city/district) or a zip code. The recommendations are based on live users watchlists.

GET http://rest.immobilienscout24.de/restapi/api/search/v1.0/recommendations/geo

Examples:

As an example you may want to retrieve geo recommendations for APARTMENT_RENT in Berlin Mitte (GeoId is 1276003001017) or for the Zip Code 12167 in Berlin Steglitz:

http://rest.immobilienscout24.de/restapi/api/search/v1.0/recommendations/geo?geoids=1276003001017&realestatetype=APARTMENT_RENT

http://rest.immobilienscout24.de/restapi/api/search/v1.0/recommendations/geo?zip=12167&zipLocationName=Berlin&realestatetype=APARTMENT_RENT

Supported media types

  • XML (Accept: application/xml)  (default)
  • JSON (Accept: application/json)
  • JSONP (Accept: application/jsonp)
    Since standard mime types do not provide a dedicated content-type for jsonp, requesting jsonp is different: To get the json-output wrapped in a javascript-function jsonp-alike you have to call the resource recommendation with .jsonp as file extension.
    For example:
    http://rest.immobilienscout24.de/restapi/api/search/v1.0/recommendations/geo.jsonp?geoids=1276003001017&realestatetype=APARTMENT_RENT

Authorization requirements

  • At least a System Key is required for this operation. See Authentication via Two-legged OAuth for further details.
  • No special permission is needed.

Request

Query Parameters

Two types of searches exists:

  1. You can provide geoids (IS24 geo hierarchy (geoid search)) or 
  2. you can provide a zip code (zip-code search)

To get meaningful recommendations out of the service make use of the following parameters, where the location must either be provided by geo ids or a zip code + zip location name (s. *)

Parameter name Optional? Type Default Description
realestatetype no Enum   The property type for which was searched. Note that the recommendations may also include properties of another type (see stricttype-parameter)
geoids no* List of Strings   Comma separated list of GeoIds for which recommendations are asked for. These GeoIds must be of the same hierarchy level.
zip no* String   A german zip code.
ziplocationname no* String   The location part of the zip code.
stricttype yes Boolean false If true only recommendations of the property type given by the parameter realestatetype will be provided.
limit yes Integer null (Unbegrenzt) If positiv, limits the number of recommendations in the response.
threshold yes Double 0.3 A value between 0.0 and 1.0 that determines the minimun score of recommended objects.

Response

The structure and attribute names of the output are the same in json or in xml. The only difference is that the xml output is wrapped in an <result/> tag while the json is always wrapped in an object.

The root node (<result/> or the root object) contains two elements: recommendations and selection. Recommendations contains all the recommended geo objects and property types while selection repeats the geo objects and real estate type that was requested plus some extra informations.

Some attributes that need explanation:

Attribute-/Tag-Name

Meaning

hitsOnShortlist This attribute tells how many watchlists, that were processed, contained this geo object. This might give a hint how stable the recommendations are, since a geo object that was found on lots of watchlists will come with stronger recommendations compared to those of a geo object that ware calculated by only a very few watchlists.
rank Although the recommendations come in an unordered list they own an interior order which ist represented by this attribute. Note that the order must not correlate with the scores.
score A value between 0.0 and 1.0 where 1.0 means that this geo object is totally recommended for the given selection while 0.0 means it is not even worth a thought.

Header

No special headers.

Body

<result>
    <recommendations>
        <recommendation>
            <rank>1</rank>
            <zip>12163</zip>
            <zipLocationName>Berlin</zipLocationName>
            <geoX>222479</geoX>
            <geoY>2505736</geoY>
            <realEstateType>APARTMENT_RENT</realEstateType>
            <score>0.862307</score>
        </recommendation>
    </recommendations>
    <selection>
        <realEstateType>0</realEstateType>
        <hitsOnShortLists>14373</hitsOnShortLists>
        <geoObjects>
            <geoObject>
                <zip>12167</zip>
                <zipLocationName>Berlin</zipLocationName>
            </geoObject>
        </geoObjects>
    </selection>
</result>

JSON


{
  "recommendations": [
    {
      "zip": "12163",
      "rank": 0,
      "realEstateType": "APARTMENT_RENT",
      "geoX": 222479,
      "zipLocationName": "Berlin",
      "score": 0.862307,
      "geoY": 2505736
    }
  ],
  "selection": {
    "geoObjects": [
      {
        "zip": "12167",
        "zipLocationName": "Berlin"
      }
    ],
    "realEstateType": "APARTMENT_RENT",
    "hitsOnShortLists": 14373
  }
}