Oikotie Listing API¶
This document contains the details on how to manage listings over the listing api. Integrating with the API has some requirements which are addressed within this document aswell.
Onboarding¶
Requirements¶
To be able to handle listings over the api you will need to have a contract with Oikotie and receive and vendor identifier which is a company specific key. In addition, you will need to have an api key with permissions to the listings api. Permissions will be granted upon onboarding.
- Contract with Oikotie real estate
- Integration identifier for company
- Api key
- Permissions for listing api
- Access to test environment
Authentication¶
Authentication to the api is done using the api key which can be generated from the company settings page. The key will need additional permissions which will be added upon onboarding.
The api key may be passed in via an HTTP GET parameter called key or as an HTTP Header, also called key. See available authorizations section
in the swagger spec (Press authorize button on top right).
curl -H 'key: 32j4hg324k23h4...' https://asunnot.oikotie.fi/api/...
or
curl https://asunnot.oikotie.fi/api/...?key=32j4hg324k23h4...
Testing¶
Testing is carried out in testing environment provided by Oikotie real estate. The access to the environment will be granted during the onboarding process.
Endpoints¶
GET¶
Path: /api/latest/listing/:vendorAdId/:vendorCompanyId
Endpoint which can be used to validate the listings status and also possibly as a callback to validate that listing was created.
POST¶
Path: /api/latest/listing/:vendorAdId/:vendorCompanyId
Endpoint for creating and updating a listing. Requires entire payload for a listing.
Example payload to create an apartment for sale:
{
"vendorAdId": "listingid",
"vendorCompanyId":"companyvendorid",
"objectType":"KT",
"habitationType":"OM",
"streetAddress":"Mannerheimintie 1 B 50",
"city":"Helsinki",
"country":"Suomi",
"description":"Hieno kohde keskustasta",
"price":"100000",
"priceSell":"110000",
"size":"100"
"sourceType": "9"
}
Note: Both vendorAdId and vendorCompanyId are required in the payload.
DELETE¶
Path: /api/latest/listing/:vendorAdId/:vendorCompanyId
Endpoint which will remove the listing from being visible in the service. The listing can be re-activated for two months after being disabled.
Example payload to disable listing:
{
"vendorAdId": "listingid",
"vendorCompanyId":"companyvendorid"
}
Api specification¶
The documentation for the fields in the api are hosted both under this documentation platform and in https://api.asunnot.oikotie.fi. The listing api specific endpoints are under "listing" title in the documentation.
Enum and constant mapping documentation for fields is located under the api specification.
General documentation¶
Under this chapter exists some documentation around the most general behaviours and functionalities regarding listings in Oikotie real estate portal.
Defining listing type¶
Which type of listing will be created depends on fields objectType and habitationType. ObjectType defined the type of the listing (ie apartment, lot etc) and habitation mode defines whether the listing is of type ownership, rental or partial ownership.
ObjectType¶
Lots (only for sale)
| Value | Explanation |
|---|---|
| OKTT | Private lot |
| VT | Leisure lot |
| RTT | Rowhouse lot |
| TO | Lot |
Apartments / Houses
| Value | Explanation |
|---|---|
| KT | Apartment |
| OT | House |
| RT | Row house |
| PT | Semi detached / Pair house |
| ET | Detached house |
| PUUT | Wooden house |
| LUHT | Luhti talo |
Parking slots
| Value | Explanation |
|---|---|
| AP | Parking slot |
| AT | Garage |
| PH | Parking hall slot |
Vacationhomes
| Value | Explanation |
|---|---|
| MO | Building |
| LH | Apartment |
| UL | Apartment |
| LO | Time share |
Business premises
| Value | Explanation |
|---|---|
| VART | Storage |
| TOT | Office |
| LT | Office premises |
| TUT | Production space |
| RAV | Restaurant |
| NAY | Show area |
| HAR | Hobby area |
| HUB | Hub area |
| TMUU | Other |
Farms (only for sale)
| Value | Explanation |
|---|---|
| MAT | Farm |
| MET | Forrest |
HabitationType¶
Sell
| Value | Explanation |
|---|---|
| OM | Ownership |
| OO | Partial ownership |
| AO | Right of occupancy |
| UU | New development |
Rent
| Value | Explanation |
|---|---|
| VU | Rent |
Listing status flow¶
When listing is created via api it will receive active status (1). When listing gets removed with the DELETE endpoint its status changes to disabled (4). Whilst the listing is in disabled status it can be re-activated and will be visible with same id in the service.
If listing has been disabled over 2 calendar months its status will change to deleted (2) and can not be activated anymore. If the same vendor listing id and company id is used to post a listing it will be created as a new listing with new id.
Addresses and location¶
Oikotie real estate uses VRK data to maintain a hierarchy of addresses. The hierarchy consists of a address that has a street, the street has a city, city has a county and county has a country. In addition the address has a zip code and can have multiple districts linked. The hierarchy only exists for Finland.
Based on the address data a listing will be matched to an address in Oikotie address hierarchy, if Oikotie is unable to determine an location for a address the address data will be stored as is as an override.
If a listing is not given any coordinates and the address where it will be resolved to does not have any coordinates Oikotie will try to geocode the address and use the response whilst taking into account the quality of the result.
Medias¶
When uploading medias, only the first image will be processed instantly. This is to make sure that the search guards matching the listing will contain image of the listing and the search page also has a media to display for the listing. The remaining images will be added to media handling queue and processed as soon as possible. Usually this does not take longer than a minute or a few, but can also be affected by the location/bandwidth of the image hosting provider.
Image media¶
Image media refers to various pictures that are shown on the Oikotie site, such as profile pictures, logos and listing target page pictures. Oikotie supports most common image formats currently in wide use. Recommended formats are PNG, JPG, GIF and WebP. In addition to these common image types, we support a few less common media formats that are included in the full list of "mimetypes". Image media is validated according to its "mimetype" and will fail to load if it's not supported.
Supported mimetypes: image/gif, image/jp2, image/jpeg, image/pjpeg, image/png, image/tiff, image/vnd.adobe.photoshop, image/webp, image/x-ms-bmp
Additional listing features¶
Application link¶
Application link can be used to direct the user to make the contact / lead in the listing owners portal. This can replace the contact form entirely by hiding the contact form from the listing.
Extra visibility¶
Extra visiblity is a product that will resend the matches to users search guard for the listing and update ordering on the search page to make the listing appear as a new listing on the search page granting the listing the audience of a new listing.
Campaign lift¶
Campaign lift is a section on the listing page which can contain customization regarding colours. images and text content for the listing.
Kohdenumero¶
If you wish your listing to be found in the search page in the kohdenumero- haku you may provide an additional id for the listing for this in iggloId field.