Efestio Data Feed Service

1. Introduction

This document will provide instructions on how to import properties to efestio.com using the Efestio RESTfull API. This documentation will assume that you are already familiar with RESTfull services, HTTP requests and JSON documents. Before actually importing your listings, you must first test your application in our Sandbox API. The sandbox api is identical to the public api except the fact that it uses different resourses and only serves as a training ground for developers that wish to use our API. In order to gain access to the Sandbox, firstly you register at https://www.efestio.eu (which is the sandbox front end) and then contact us to request RTDF access. Using those you will be able to connect to the sandbox and start testing your application.

1.1 Real Time Data Feed Documentation

In order to import properties automatically using our API, you must follow our RTDF (Real Time Data Feed) Specifications.

The basic requirements for using the API are the following:

• Understanding REST architecture
• Experience with Token Based Authentication
• Experience with JSON Format

In order to qualify for the public version of the API you must firstly ensure that you can add/update/delete properties in the sandbox version of the efestio website ( www.efestio.eu ).

2. Simple technical overview

2.1 Requests

Each request must have the following headers:

Each and everyone of your requests to the API must have the above headers included.

2.2 Authentication

For the v1 version of the API, we are using Token Based Authentication. In order to use the API you must first register a user at www.efestio.com (after you have tested your application in the sandbox). Using the credentials of this user, you can login to the system and start uploading. Upon sending the authentication request, the server will return a JSON document with the user’s data along with the token, user id, the client id and the expiration date of the session in the response’s headers like so:

2.2.1 JSON RESPONSE

"data": {
    "id": 1,
    "email": "example@somemail.gr",
    "provider": "email",
    "uid": "example@somemail.gr",
    "name": null,
    "nickname": null,
    "image": null,
    "type": "user"
}
                        

The required headers below are necessary for the authentication process. After this, in order to authenticate each request, you must include these headers every time.

2.2 Endpoints

The main endpoints of our service are 4 ( four ) in number : Login, Update/Create, Delete and Get Branch.

3. Objects Model

In this section, we will explore the data schema of our API and what it means. Using the information in this chapter, you will be able to create appropriate JSON documents to import your listings and to interpret the server’s responses.

3.1 The Property Model

Notes :

• The system supports properties with price on request. In order to proclaim a property with price on request you must set the base_price value to “999999999”. In any other case, the price will be shown and your property will likely be removed for inaccurate information.
• If you wish to update your properties, you can use the user_updated_at attribute to check if there have been any changes made to your listing before importing it again. If the dates match, then the server will not update the listing. Bare in mind that you are strongly discouraged to update all the listings regardless of modifications.
• Provide as much “accurate” information as possible. Each listing is assigned a value that determines it’s qualification to “Premium” status as well as it’s position in all search results. This value is influenced in part from the information you provide, especially images and descriptions.
• Provide descriptions in any language you have. Bare in mind that each description is evaluated based on the complexity and quality of the text. This means that if your description in some language is not good you should consider not including it.

3.3 The Amenities Model ( JSON String )

In this subchapter we will explore the structure of the amenities JSON string. A sample of such string can be seen here:

amenities: "{
  "wifi": false,
  "parking": false,
  "ac": true,
  "basement": false,
  "storage": false,
  "elevator": true,
  "fireplace": true,
  "hvac": false,
  "bbq": true,
  "garden": false,
  "pool": false,
  "road_access": false,
  "corner": false,
  "watter_supply": false,
  "heat_type": 0,
  "electricity": false
}"
                

Notice that the whole object is wrapped in double quotes "", this is because as we said earlier, the amenities are represented as JSON String, in order to be easily parsed from javascript, and keep the database as simple as possible.

Not all amenities are always available. There are different amenities for each parent category. For example, if the listing has hope_type_id = 1 (e.g Appartment), the amenities that belongs to Land or Commercial listings ( watter supply, road access, corner, etc.. ) will be ignored, regardless if they are set to true in the amenities object.

Below is a list with the Amenities that every category has

3.4 The Images Model ( JSON String )

Images can strongly influence a user's impression of a listing so it is important to provide good quality images which are representative of the property.

Images are stored as JSON object string attribute, that contains some attributes respectively. The first attribute is the “featured” key, which is the link of the featured image of the listing ( that will be shown on the single property view) and “image_array” which are the links of the images themselves. You can see an example of such object for a single image of the array here:

"{
  "featured": "https://cdn2.examplecdn.com/images/large/example.jpg",
  "image_array": [
    {"image_name":"388428fsdf823f.jpg","image_name_no_guid":null,"original_url":"...","large":"...","medium":"...","small":"...","thumbnail":"...","floor_id":0,"image_name_no_extension":"388428fsdf823f"},
    {"image_name":"388428fsdf823f.jpg","image_name_no_guid":null,"original_url":"...","large":"...","medium":"...","small":"...","thumbnail":"...","floor_id":0,"image_name_no_extension":"388428fsdf823f"},
    {"image_name":"388428fsdf823f.jpg","image_name_no_guid":null,"original_url":"...","large":"...","medium":"...","small":"...","thumbnail":"...","floor_id":0,"image_name_no_extension":"388428fsdf823f"},
    {"image_name":"388428fsdf823f.jpg","image_name_no_guid":null,"original_url":"...","large":"...","medium":"...","small":"...","thumbnail":"...","floor_id":0,"image_name_no_extension":"388428fsdf823f"},
    {"image_name":"388428fsdf823f.jpg","image_name_no_guid":null,"original_url":"...","large":"...","medium":"...","small":"...","thumbnail":"...","floor_id":0,"image_name_no_extension":"388428fsdf823f"}
  ]
}"
                    

Notice that the whole object is wrapped in double quotes"", this is because as we said earlier, the Images are represented as JSON String, in order to be easily parsed from javascript, and keep the database as simple as possible.

There are several fields for each image. You can use all the fields or you can just provide the “large” image url. Our server automatically will try to download the images but it would be best practice if your provided all the information depicted above. You can include up to 25 images for each listing. You should remember that choosing images with high quality increases greatly the value of each listing.

The featured image should ideally be of the exterior of the property.

Do not send agent logos or placeholder images. These will removed from our websites.

We recommend images have a size of at least 1280x960. Please note that we provide users access to original images and they should display larger than the default view on our listing detail page. Large images are particularly important for mobile devices when viewed full screen.

3.5 The Descriptions Model ( JSON String )

The “descritpions” attribute is fairly simple as seen bellow

{
  {"lang_id":"en","text": "Property description"}, 
  {"lang_id":"gr","text": "Περιγραφή"},
  {"lang_id":"ru","text": "Описание недвижимости"}
}
                

Each object has two fields, “lang_id” and “text”. The first is used to declare the language of the description, and it uses ISO 639-1 coding. The second one is the description itself which should contain only text with no special characters or mark-up language. You can add descriptions in all languages, not just the ones that are available on our website. This is because our site will be always expanding and when those languages will be available, your listings will have already descriptions.