Skenarios API documentation

Skenarios service has an API which can be used to maintain portfolio and properties. The base URL for all requests is https://api.skenarios.com/

Swagger

Swagger documentation can be found here:

https://app.skenarios.com/ui/vendor/swagger-ui/index.html#/

Authorization and security

Authentication is handled by JSON Web Tokens. The token must be passed as a query parameter (apiKey) or as an HTTP header parameter (Authorization). The token is provided same way is in the JWT specification with Bearer initials. For example Authorization: Bearer <your JWT token here>

An optional way of providing the toke is to add it to end of the requested URL as a query parameter: apiKey=<your JWT token here>

The user's token can be found in the Settings page after the user has logged in. Since the API token allows full access as a user of the Skenarios service, it is very important to keep the token in a secure place.

Only secure HTTPS connections are allowed.

Data format and response codes

The API accepts only JSON as a parameter, except those parameters, which are delivered as a query parameter. All responses are in JSON.

By default, the service sends the following responses:

ResponseExplanation
200 OKYour request was processed successfully
201 CreatedYour request was processed successfully, an object was created
400 Bad RequestSomething is wrong in the received data or query. This is most likely a format issue.
401 UnauthorizedYour request was not authorized, please check the JWT token.
403 ForbiddenThe user-specified in the JWT token has no access privileges on the given object.
404 Not FoundThe requested service doesn't exist
422 Unprocessable EntitySent parameters were understood, but their content was problematic. Please check your input.
500 Internal Server ErrorWhoops! This is embarrassing, something unexpected happened. We'll take a look at the issue as soon as possible. 

Examples

This is an example, how to create a new portfolio for the user.

Create a portfolio

wget --quiet \
--method POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your JWT token here>' \
--header 'Cache-Control: no-cache' \
--body-data '{"title":"My new portfolio!", "description":"All your base are belong to us!","countryCode":"FI"
}' \
--output-document \
- https://api.skenarios.com/api/v1/portfolio

The expected response should look like something like this:

{"portfolioId":961,"title":"My new portfolio!","description":"All your base are belong to us!","ownerUserId":"<username>","organization":"SkenarioLabs",

"dataCountry":{"countryCode":"FI","name":"Finland","currencyName":"EURO","currencyCode":"EUR","currencySymbol":"€"}

,"projectId":961}

Take a note about the portfolioId, that's needed later for adding properties into the portfolio.

Create a property to the portfolio

First, we need to add a building to a recently created portfolio.

wget --quiet \
--method POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your JWT token here>' \
--header 'Cache-Control: no-cache' \
--body-data '[{"country":"FI","address":"Ruutikuja 1","postalCode":"02650","city":"Espoo"}]' \
--output-document \
- https://api.skenarios.com/api/v1/portfolio/<portfolioId>/property

This might take a while and the response should be something like:

[
{
"prototypeId": 34,
"buildYear": 1995,
"demolitionYear": null,
"electricityId": 7,
"heatingId": 20,
"coolingId": null,
"floors": 3,
"floorArea": 730,
"volume": null,
"propertyBuildingId": 150605,
"propertyGroupId": 61837,
"balconies": 0,
"units": null,
"lifts": 0,
"name": "Ruutikuja 1",
"address": "Ruutikuja 1",
"postalCode": "02650",
"city": "Espoo",
"key": "1002854993",
"groupKey": "49-51-79-2",
"polygonUniqueId": "ud9wsg7u5_2",
"country": "FI",
"description": null,
"lat": 60.223643550000006,
"lon": 24.8234182,
"analyticsLat": 60.223643550000006,
"analyticsLon": 24.8234182
}
]

Here, remember the propertyBuildingId, which is needed for creating the unit into the building.

Add a unit into the property and getting its values

Each property consists of units, which are typically for example apartments.

wget --quiet \
--method POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your JWT token here>' \
--header 'Cache-Control: no-cache' \
--body-data '{"key":"A4","description":"Studio apartment","usageType":"RESIDENTIAL","address":"Ruutikuja 1 A 4","zipCode":"02650","propertyBuildingId":<propertyBuildingId>,"city":"Espoo","floorArea":28,"floor":2}' \
--output-document \
- https://api.skenarios.com/api/v1/unit

This adds a new unit to the property. The result contains property unit details.

{
"propertyUnitId": 168046,
"propertyBuildingId": 150605,
"propertyGroupId": 61837,
"floorArea": 28,
"floor": 2,
"name": null,
"key": "A4",
"description": "Studio apartment",
"address": "Ruutikuja 1 A 4",
"zipCode": "02650",
"city": "Espoo",
"countryCode": "FI",
"buildingKey": "1002854993",
"usageType": "RESIDENTIAL",
"params": {},
"lat": null,
"lon": null
}

To get value for the new property unit, get the analytics values:

wget --quiet \
--method GET \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your JWT token here>' \
--header 'Cache-Control: no-cache' \
--output-document \
- https://api.skenarios.com/api/v1/unit/<propertyUnitId>/analytics

The response consists of an array of possible analytical values created by Skenarios service. Here is an example of property value.

[
{
"year": 2018,
"month": null,
"propertyBuildingId": null,
"propertyUnitId": 168046,
"valueId": 1254209,
"value": 147000,
"type": "PROPERTY_TOTAL_VALUE",
"periodStart": "2018-09-18T11:55:49.909",
"periodEnd": "2099-12-31T23:59:59"
}
]

The value is in the user's organization's local currency. The results may also contain historical and estimated value development. Those values can be found by their period start and end days.

At the moment the value is still a little bit inaccurate. To improve the valuation, check what kind of properties were used in calculating the value.

wget --quiet \
--method GET \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your JWT token here>' \
--header 'Cache-Control: no-cache' \
--output-document \
- https://api.skenarios.com/api/v1/unit/168046/properties


The query returns an array of property values. 


{
"title": "Condition",
"externalKey": "CONDITION",
"valueType": "TEXT",
"value": null,
"valueOptions": [
"Good",
"Mediocre",
"Poor"
],
"parameterTypeId": 15
}

...
]

Currently, the property has no condition level set, which means that it's assumed to be in mediocre condition.

To change that, put a condition value for the property:

wget --quiet \
--method PUT \
--header 'Content-Type: application/json' \
--header 'Authorization: ' \
--header 'Cache-Control: no-cache' \
--body-data '{"value": "Good","externalKey": "CONDITION"}' \
--output-document \
- http://api.skenarios.com/api/v1/unit/115486/properties


After this, you can get the properties value estimation again. 



Common interfaces

In following general overview of the available APIs are presented.

Property valuation interfaces

This section contains the two main interfaces needed for the property value estimations. These calls are essentially the same that can be used to add any kind of property to the portfolio.

Typically the process goes:

  1. Add (POST) a property to the API, the API returns used building id and property id's which are necessary for the next step
  2. Add (POST) unit for the property. Use previous building and property id. The API result set contains value estimations of the given unit.

POST /api/v1/portfolio/:portfolioId/property 

Inserts a building to a portfolio corresponding the id. Portfolio Id is got either from the API call or from the web service's portfolio overview.

Parameters

NameTypeIs mandatory?Description
buildingIdString
Unique Building id, given by the organization
buildYearInteger
Build year of the property building
descriptionString
Free text description of the property
countryStringYesCountry code of the property building, allowed values are FI and UK.
buildingTypeString
Type of the main property: row house, office, commercial building, detached house, leisure house, apartment, school, retail building, industrial building, garage, warehouse, generic building
facadeMaterialString
The primary building material of the walls of the building. Allowed values are empty, brick, wood, concrete
heatingEnergyTypeString
primary heating source, allowed values are: ground, electric, district, wood, oil, gas, other.
balconiesInteger
Number of balconies in the property
unitsInteger
Total number of property units in the property
liftsInteger
Total number of lifts in the property
floorsInteger/Double
The total number of floors in the property, the ground floor being 1. If a double value is sent, it will be rounded up to the nearest integer e.g. 1.5 will be rounded to 2
balconiesInteger
Total number of balconies in the property
floorAreaInteger/Double
Total gross floor area of the property, including cold and heated spaces in m2. If a double value is sent, it will be rounded up to the nearest integer e.g. 99.80 will be rounded to 100
volumeInteger
Total gross volume of the property, including cold and heated spaces in m3.
addressStringYesStreet address of a building. This is mandatory unless building id matches with known national property ids.
postalCodeStringYesPostcode of a building.
cityStringYesCity where a building is located.
useExistingIfAvailableboolean
If true, tries to find an existing property with building and address details. If found uses that and updates with given other details. Otherwise, creates a new one and returns it.
propertiesarray
An array of specific properties related to this building. The exact keys depend on the organization, however, common keys for everybody are presented in table below. For example: [{"propertyId":"LOT_OWNED", "value" :"yes"},{"propertyId":"LOT_SIZE", "value" :1400}]

measures

array
An array of specific values related to this property. Keys are presented in the table below. For example: [{"type":"MONTHLY_LOT_LEASE_AMOUNT", "value" :350}]

Property properties

Values used with the properties array. Note, that all of these values can be left out, however, they make value estimations much more accurate.

Property idDescription
LOT_OWNEDA boolean value, if the lot is owned by the property
LOT_SIZESize of the lot in square meters.
LOT_LEASE_ENDEnd year of current lot lease contract, if applicable
PARKINGType of available parking for the property. Allowed values are: None, Parking space, Garage, Carport, Undercover parking
IS_HOUSING_COMPANYA boolean value, true when the property is a housing company. Generally, this is already part of the value estimation algorithm, but setting this can give more accurate results for example for single family houses, if applicable.
GARDEN_BUILDINGSA boolean value, set true if the property has one or more unheated buildings in the property such as garden sheds or barbecue huts.
WATERSIDE_LOTA boolean value to indicate if the plot is next to a body of water, such as lake, river or sea.
ALL_YEAR_ROUND_LIVINGA boolean value to indicate if the property is suitable for all year round living. This is applicable for properties which building type is "leisure house" and it's not relevant for other property types.

These properties are given as JSON array, as property id/value pairs in the above call's 'properties' property. For example: [{"propertyId":"LOT_OWNED", "value" :"yes"},{"propertyId":"LOT_SIZE", "value" :1400}]

Property measures

Property measurements are values related to property which also may have time element and they may vary over the course of time. Values used with the properties array. Note, that all of these values can be left out, however, they make value estimations much more accurate.

Property idDescription
MONTHLY_LOT_LEASE_AMOUNTMonthly lot lease in local currency.
ANNUAL_PROPERTY_TAX_AMOUNTAnnual property tax in local currency.
ANNUAL_HEATING_COSTSAnnual heating costs in local currency.

These properties are given as JSON array, as property id/value pairs in the above call's 'properties' property. For example: [{"type":"MONTHLY_LOT_LEASE_AMOUNT", "value" :350},{"type":"ANNUAL_HEATING_COSTS", "value" :1400}]

Results

On success, returns 200

NameTypeDescription
addressStringStreet address of the building
analyticsLatDoubleLatitude inside building outlines or in the vicinity of the building
analyticsLonDoubleLongitude inside building outlines or in the vicinity of the building
balconiesIntegerCount of balconies in the building
buildYearIntegerBuild year of the building
cityStringCity of the building
coolingIdIntegerThe ID of the cooling system used in the building
countryStringCountry code
demolitionYearIntegerYear of the demolition of the building
descriptionStringDescription text
electricityIdIntegerThe ID of the electricity system used in the building
floorAreaIntegerTotal floor area of the building
floorsIntegerCount of floors in the building
groupKeyStringMutable key of the property group
heatingIdIntegerThe ID of the heating system used in the building
keyStringA mutable ID of the building
latDoubleLatitude inside building outlines
liftsIntegerCount of lifts in the building
lonDoubleLongitude inside building outlines
nameStringName of the building
polygonUniqueIdStringAn immutable ID of the building
postalCodeStringPostcode of the building
propertyBuildingIdIntegerAn immutable ID of the building
propertyGroupIdIntegerAn immutable ID of the property group
prototypeIdIntegerAn immutable ID of the building prototype
unitsIntegerAmount of property units in the building
volumeIntegerThe total volume of the building
measuresArrayAn array containing measures related to the property.
propertiesArrayAn array containing properties and their values related to the property.
analyticsArrayAn array containing analytics values related to the property. Analytics values are generated by Skenarios service and can't be set anywhere, however they are based on the property features, properties and measures.

On error, returns 404.

Measures and analytics arrays

The measures and analytics arrays have the following format. Note, that result set may contain multiple same type values, but different validity periods.

Field nameDescription
accuracyThe accuracy of the estimated value. This is always null for the measured values. Accuracy is presented as a value between 0 and 1, indicating an estimated error in 70% accuracy. The smaller value is better. The possible range depends on the accuracy of the properties of the property.
valueIdA unique identifier for the stored value.
valueThe actual value may be either number, boolean or string.
typeThe type code of the value.
periodStartStart of value's (estimated) validity.
periodEndThe end of value's (estimated) validity.

POST /api/v1/portfolio/:portfolioId/unit

Inserts a new unit to a portfolio corresponding the id.

Parameters

Name

TypeDescription
buildingIdStringBuilding id from the create building. Group id or building id is mandatory. 
groupIdStringThe group id of this property group. Group id or building id is mandatory.
floorAreaInteger/DoubleFloor area of the unit in m2 This is mandatory for getting value estimation. If a double value is sent, it will be rounded up to the nearest integer e.g. 99.80 will be rounded to 100
floorInteger/DoubleFloor number of the unit, ground floor being 1. If a double value is sent, it will be rounded up to the nearest integer e.g. 1.5 will be rounded to 2
nameStringName of the unit
unitIdStringIdentifying id for the unit, for example, apartment number. Must be unique within the building id. If not given, it'll be generated.
descriptionStringDescription of the unit.
usageTypeStringType of the property unit, the allowed values are RESIDENTIAL, OFFICE, RETAIL, STORAGE, OTHER. None is defined, this defaults to RESIDENTIAL. Property value is estimated only for the RESIDENTIAL type.
addressStringStreet address, with the house and apartment number, if available.
postalCodeStringPostal code of the address. This is mandatory for getting value estimation.
cityStringCity name of the address. This is mandatory for getting value estimation.
countryCodeStringEither FI or UK
useExistingIfAvailableBooleanTrue or False, if true, tries to find an existing unit from the group which matches with the unit id or address. If found updates it and returns, otherwise creates a new one with given data.
propertiesArrayAn array of specific properties related to this unit. The exact keys depend on the organization, however, common keys for everybody are presented in the table below. For example: [{"propertyId":"SAUNA", "value" :"true"},{"propertyId":"NUMBER_OF_ROOMS", "value" :3}]. These values are elementary for getting the correct price estimation.
measuresArrayAn array of specific values related to this property. Keys are presented in the table below. For example: [{"type":"MONTHLY_MAINTENANCE_FEE", "value" :240}]

Property properties

The current property detail keys are as follows. Also note, that all of these values can be left out, however they make value estimations much more accurate.

PropertyIdDescription
NUMBER_OF_ROOMSTotal count of bedrooms and living room(s). Leave out kitchen and bathrooms. This is mandatory for getting value estimation.
KITCHEN_TYPEType of the kitchen in the property. Allowed values are: Kitchen, Open Plan Kitchen, Kitchenette, Small Kitchen, Kitchenette w/ window, Scullery
SAUNADoes the property have a sauna, Allowed values are: Yes, No, Sauna building, Lakeside sauna.
BALCONY_TYPEType of the balcony in the property. Allowed values are: Balcony, Glazed Balcony, French Balcony
CONDITIONThe general condition of the property, allowed values are: New, Excellent, Good, Mediocre, Poor. This is very good for getting the correct value estimation.
TERRACE_TYPEType of the terrace in the property. Allowed values are: Yes, No, Glazed Terrace

These properties are given as JSON array, as property id/value pairs in the above call's 'properties' property. For example: [{"propertyId":"SAUNA", "value" :"true"},{"propertyId":"NUMBER_OF_ROOMS", "value" :3}]

Property measures

Property measurements are values related to the property which also may have a time element and they may vary over the course of time. Values used with the properties array. Note, that all of these values can be left out, however, they make value estimations much more accurate.

Property idDescription
MONTHLY_MAINTENANCE_FEEMonthly total maintenance fee in local currency.
MONTHLY_HOUSING_LOAN_FEEMonthly total housing loan fee in local currency.
PROPERTY_VALUE_WITHOUT_DEBTTotal property value without the housing debt part of the unit. "Myyntihinta"
PROPERTY_TOTAL_VALUETotal property value. "Velatonhinta"
TOTAL_HOUSING_COMPANY_LOANTotal housing company debt coming with this property. Usually same as  distract PROPERTY_TOTAL_VALUE from PROPERTY_VALUE_WITHOUT_DEBT
MONTHLY_RENTMonthly total rent in local currency.

These properties are given as JSON array, as property id/value pairs in the above call's 'measures' property. For example: [{"type":"MONTHLY_MAINTENANCE_FEE", "value" :320},{"type":"MONTHLY_HOUSING_LOAN_FEE", "value" :145}]

Results

On success, returns 200

On Success, returns 200 and a list of property unit related analytics values where one element consists of the following parameters

Name

TypeDescription
propertyUnitIdIntegerThe id of the property unit
propertyBuildingIdIntegerThe id of the property building this unit is part of. 
propertyGroupIdIntegerThe id of the property group this unit is part of. 
floorAreaIntegerFloor area of the unit in m2
floorIntegerFloor number of the unit, ground floor being 1.
nameStringName of the unit
keyStringIdentifying id for the unit
descriptionStringDescription of the unit
usageTypeStringType of the property unit, the allowed values are: RESIDENTIAL, OFFICE, RETAIL, STORAGE, OTHER
addressStringStreet address, with the house and apartment number, if available.
zipCodeStringPostal code of the address
cityStringCity name of the address
countryCodeStringEither FI or UK
propertiesArrayContains unit properties
measuresArrayContains unit measurements, which were added to the unit.
analyticsArrayAn array containing analytics values related to the property. Analytics values are generated by Skenarios service and can't be set anywhere, however they are based on the property features, properties and measurements. The format of the returned arrays is described above.

On error, returns 404.

Property analytics values

Property analytics values are values related to property which are generated through Skenarios service. They are always best effort estimates. The accuracy of the relevant estimation is provided along with the value. At the moment property units get only one value.

Property idDescription
PROPERTY_TOTAL_VALUETotal property value in local currency. This includes possible house debt for the apartments. This value is only calculated for residential buildings when (building) postal code, unit floor area, amount of rooms -property parameter and (building) city are available and unit's usage type is either null or RESIDENTIAL. In other cases, it's left out. 


GET /api/v1/portfolio/: portfolioId/building/:buildingId/renovation

Get all renovations of a building (buildingId) in a portfolio (portfolioId).

Parameters

None.

Results

On Success, returns 200 and an array of renovations where one element consists of the following parameters

Name

TypeDescription
yearIntegerRenovation year
propertyBuildingIdIntegerImmutable building ID
partPeriodIdIntegerImmutable building part period ID
propertyUnitIdIntegerImmutable unit ID
costIntegerCost of renovation
partIdIntegerImmutable building part ID
renovationIdIntegerImmutable renovation ID
unitCostIntegerCost per effective unit of a renovation
quantityIntegerThe amount in effective units to calculate the cost
descriptionStringDescription text
titleStringTitle of renovation
partTypeStringBuilding part type under renovation. Values are: 

LIFT, FIRE_PROTECTION, AUTOMATION, COOLING_SYSTEM, HEAT_DISTRIBUTION, HEATING_SYSTEM,

INTERIOR, BALCONY, SITEWORK, VENTILATION, ELECTRIC, PIPE, FACADE, WINDOW, OUTER_WALL,

ROOF, FOUNDATION, FLOOR, BASE_FLOOR, and OTHER

changeTypeString

Refers to the state of a building part period. ORIGINAL denotes the part to be original, ASSUMED denotes the part is statistically assumed to be installed and PLANNED denotes the part known to be installed.

partNameStringName of the building part
renovationTypeStringType of renovation. Values are

PART_CHANGE, TIMBER_CLADDING_PAINTING, CONCRETE_ELEMENT_MORTAR_JOINT, 

FACADE_PAINTING, BRICK_CLADDING_MORTAR_JOINT, WINDOW_FENCES_AND_FRAMES_PAINTING, 

WINDOW_SEALING, ROOF_PAINTING, and MISC.

effectiveUnitStringThe effective unit used in cost calculation

On error, returns 404.


Portfolio

Portfolios are collections of properties.

POST /api/v1/portfolio 

Creates a new portfolio.

Parameters

NameTypeIs mandatory?Description
titleStringYesTitle of the new portfolio.
descriptionString
Description text
ownerUserIdStringYesUsername of the owner of the portfolio
organizationStringYesName of the owning organization
dataCountryStringYesData country. Allowed values are either FI or UK

Results

On success, returns 200:

NameTypeDescription
portfolioIdNumberID of created portfolio.
titleStringTitle of the new portfolio.
descriptionStringDescription text
ownerUserIdStringUser name of the owner of the portfolio
organizationStringName of the owning organization
dataCountryStringData code of the country.
projectIdNumberID of the project.

On error, returns 404.

PUT /api/v1/portfolio/:portfolioId 

Updates given portfolio with given id.

Parameters

NameTypeIs mandatory?Description
titleStringYesTitle of the new portfolio.
descriptionString
Description text
ownerUserIdString
User name of the owner of the portfolio
organizationStringYesName of the owning organization
dataCountryStringYesData country. Allowed values are either FI or UK

Results

On success, returns 200:

NameTypeDescription
portfolioIdNumberID of the portfolio.
titleStringTitle of the portfolio.
descriptionStringDescription text
ownerUserIdStringUser name of the owner of the portfolio
organizationStringName of the owning organization
dataCountryStringData code of the country.
projectIdNumberID of the project.

On error, returns 404.

GET /api/v1/portfolio/:portfolioId 

Gets details of given portfolio.

Parameters

None

Results

On success, returns 200:

NameTypeDescription
portfolioIdNumberID of the portfolio.
titleStringTitle of the portfolio.
descriptionStringDescription text
ownerUserIdStringUsername of the owner of the portfolio
organizationStringName of the owning organization
dataCountryStringData code of the country.
projectIdNumberID of the project.

On error, returns 404.

GET /api/v1/portfolio/:portfolioId/search 

Do text search to portfolios properties. Add query parameter query to the URL. Search matches property names and addresses.

Parameters

Query parameter: quert

Results

On success, returns 200. The Response contains an array for matched units, buildings and groups.

NameTypeDescription
propertyUnitIdNumberThe id of the property unit if applicable.
propertyBuildingIdNumberThe id of the property building if applicable.
propertyGroupIdNumberThe id of the property group if applicable.
nameStringName of the property
addressStringAddress of the property
keyStringUser set key of the property
parentKeyStringUser set key of the parent property of the current property

On error, returns 404.

DELETE /api/v1/portfolio/:portfolioId 

Removes portfolio with given ID.

Parameters

None.

Results

On Success, returns 200.

On error, returns 404.

Buildings

Buildings are physical constructions. A building is a part of the property group and may contain property units. Renovations are done for the building.

For more building-related APIs, please refer to the property valuation part in this document.

DELETE /api/v1/portfolio/:portfolioId/building/:buildingId

Removes a property building (buildingId) from a portfolio (portfolioId).

Parameters

None.

Results

On Success, returns 200.

On error, returns 404.

DELETE /api/v1/portfolio/:portfolioId/group/:groupId

Removes a property group (groupId) from a portfolio (portfolioId).

Parameters

None.

Results

On Success, returns 200.

On error, returns 404.

POST /api/v1/building/:propertyBuildingId/renovation 

Inserts a renovation into a building (buildingId) in a portfolio (portfolioId).

Parameters

NameTypeIs mandatory?Description
yearIntegerYesRenovation year
partTypeStringYes

Part subject to renovation, allowed values are LIFT, FIRE_PROTECTION, AUTOMATION, COOLING_SYSTEM, HEAT_DISTRIBUTION, HEATING_SYSTEM,

INTERIOR, BALCONY, SITEWORK, VENTILATION, ELECTRIC, PIPE, FACADE, WINDOW, OUTER_WALL,

ROOF, FOUNDATION, FLOOR, BASE_FLOOR, and OTHER

renovationTypeStringYes

Type of renovation, allowed values are

 PART_CHANGE, TIMBER_CLADDING_PAINTING, CONCRETE_ELEMENT_MORTAR_JOINT, 

FACADE_PAINTING, BRICK_CLADDING_MORTAR_JOINT, WINDOW_FENCES_AND_FRAMES_PAINTING, 

WINDOW_SEALING, ROOF_PAINTING, and MISC.

partPeriodIdInteger
Immutable building part period ID
propertyBuildingIdInteger
Immutable building ID

Results

On Success, returns 200.

Name

TypeDescription
yearIntegerRenovation year
propertyBuildingIdIntegerImmutable building ID
partPeriodIdIntegerImmutable building part period ID
propertyUnitIdIntegerImmutable unit ID
costIntegerCost of renovation
partIdIntegerImmutable building part ID
renovationIdIntegerImmutable renovation ID
unitCostIntegerCost per effective unit of a renovation
quantityIntegerAmount in effective units to calculate cost
descriptionStringDescription text
titleStringTitle of renovation
partTypeStringBuilding part type under renovation
changeTypeString

Refers to the state of a building part period. ORIGINAL denotes the part to be original, ASSUMED denotes the part is statistically assumed to be installed and PLANNED denotes the part known to be installed.

partNameStringName of the building part
renovationTypeStringType of renovation
effectiveUnitStringEffective unit used in cost calculation

On error, returns 404.

GET /api/v1/building/:propertyBuildingId/renovation

Get all renovations of a building (buildingId) in a portfolio (portfolioId).

Parameters

None.

Results

On Success, returns 200 and a list of renovations where one element consists of the following parameters

Name

TypeDescription
yearIntegerRenovation year
propertyBuildingIdIntegerImmutable building ID
partPeriodIdIntegerImmutable building part period ID
propertyUnitIdIntegerImmutable unit ID
costIntegerCost of renovation
partIdIntegerImmutable building part ID
renovationIdIntegerImmutable renovation ID
unitCostIntegerCost per effective unit of a renovation
quantityIntegerAmount in effective units to calculate cost
descriptionStringDescription text
titleStringTitle of renovation
partTypeStringBuilding part type under renovation
changeTypeString

Refers to the state of a building part period. ORIGINAL denotes the part to be original, ASSUMED denotes the part is statistically assumed to be installed and PLANNED denotes the part known to be installed.

partNameStringName of the building part
renovationTypeStringType of renovation
effectiveUnitStringEffective unit used in cost calculation

On error, returns 404.

DELETE /api/v1/buildingRenovation/:renovationId

Removes a renovation (renovationId).

Parameters

None.

Results

On Success, returns 200.

On error, returns 404.

GET /api/v1/building/:buildingId/analytics

Get analytical values of a building (buildingId).

Parameters

None.

Results

On Success, returns 200 and a list of building-related analytics values where one element consists of the following parameters

Name

TypeDescription
yearIntegerValue year
month
Value month
propertyBuildingIdIntegerImmutable building ID
propertyUnitIdIntegerImmutable unit ID
valueIdIntegerImmutable value ID
valueIntegerAnalytics value
typeStringAnalytics type
periodStartStringValue's validity period start
periodEndStringValue's validity period start

On error, returns 404.

Units

Property units are leasable units within properties, such as apartments, parking places or commercial spaces.

POST /api/v1/unit

Adds a new property unit. A typical property unit is a commercial place in a shopping centre or an apartment in an apartment block.

Parameters

Name

TypeDescription
propertyBuildingIdIntegerThe id of the property building this unit is part of. This or property group id is mandatory.
propertyGroupId
The id of the property group this unit is part of. This or property building id is mandatory.
floorAreaIntegerFloor area of the unit in m2
floorIntegerFloor number of the unit, ground floor being 1.
nameStringName of the unit
keyStringIdentifying id for the unit
descriptionStringDescription of the unit
usageTypeStringType of the property unit, the allowed values are: RESIDENTIAL, OFFICE, RETAIL, STORAGE, OTHER
addressStringStreet address, with the house and apartment number, if available.
zipCodeStringPostal code of the address
cityStringCity name of the address
countryCodeStringEither FI or UK

Results

On Success, returns 200 and a list of property unit related analytics values where one element consists of the following parameters

Name

TypeDescription
propertyUnitIdIntegerThe id of the property unit
propertyBuildingIdIntegerThe id of the property building this unit is part of. 
propertyGroupIdIntegerThe id of the property group this unit is part of. 
floorAreaIntegerFloor area of the unit in m2
floorIntegerFloor number of the unit, ground floor being 1.
nameStringName of the unit
keyStringIdentifying id for the unit
descriptionStringDescription of the unit
usageTypeStringType of the property unit, the allowed values are: RESIDENTIAL, OFFICE, RETAIL, STORAGE, OTHER
addressStringStreet address, with the house and apartment number, if available.
zipCodeStringPostal code of the address
cityStringCity name of the address
countryCodeStringEither FI or UK

On error, returns 404.

GET /api/v1/unit/:unitId

Gets the property unit with given id. A typical property unit is a commercial place in a shopping center or an apartment in an apartment block.

Parameters

None

Results

On Success, returns 200 and a list of property unit related analytics values where one element consists of the following parameters

Name

TypeDescription
propertyUnitIdIntegerThe id of the property unit
propertyBuildingIdIntegerThe id of the property building this unit is part of. 
propertyGroupIdIntegerThe id of the property group this unit is part of. 
floorAreaIntegerFloor area of the unit in m2
floorIntegerFloor number of the unit, ground floor being 1.
nameStringName of the unit
keyStringIdentifying id for the unit
descriptionStringDescription of the unit
usageTypeStringType of the property unit, the allowed values are: RESIDENTIAL, OFFICE, RETAIL, STORAGE, OTHER
addressStringStreet address, with the house and apartment number, if available.
zipCodeStringPostal code of the address
cityStringCity name of the address
countryCodeStringEither FI or UK

On error, returns 404.


PUT /api/v1/unit/:unitId

Updates an existing property unit specified by the ID in the URL. All fields must have value when updating or else they will be replaced with empty values.

Parameters

Name

TypeDescription
propertyBuildingIdIntegerThe id of the property building this unit is part of. This or property group id is mandatory.
propertyGroupId
The id of the property group this unit is part of. This or property building id is mandatory.
floorAreaIntegerFloor area of the unit in m2
floorIntegerFloor number of the unit, ground floor being 1.
nameStringName of the unit
keyStringIdentifying id for the unit
descriptionStringDescription of the unit
usageTypeStringType of the property unit, the allowed values are: RESIDENTIAL, OFFICE, RETAIL, STORAGE, OTHER
addressStringStreet address, with the house and apartment number, if available.
zipCodeStringPostal code of the address
cityStringCity name of the address
countryCodeStringEither FI or UK

Results

On Success, returns 200 and a list of property unit related analytics values where one element consists of the following parameters

Name

TypeDescription
propertyUnitIdIntegerThe id of the property unit
propertyBuildingIdIntegerThe id of the property building this unit is part of. 
propertyGroupIdIntegerThe id of the property group this unit is part of. 
floorAreaIntegerFloor area of the unit in m2
floorIntegerFloor number of the unit, ground floor being 1.
nameStringName of the unit
keyStringIdentifying id for the unit
descriptionStringDescription of the unit
usageTypeStringType of the property unit, the allowed values are: RESIDENTIAL, OFFICE, RETAIL, STORAGE, OTHER
addressStringStreet address, with the house and apartment number, if available.
zipCodeStringPostal code of the address
cityStringCity name of the address
countryCodeStringEither FI or UK

On error, returns 404.

DELETE /api/v1/unit/:unitId

Removes the property unit with given id.

Parameters

None

Results

On Success, returns 200

GET /api/v1/unit/:unitId/properties

Gets all property unit related properties. Properties are additional details related to the property unit.

Parameters

None

Results

On Success, returns 200 and an array of properties and their values. The array contains following fields:

Name

TypeDescription
titleStringTitle of the property
externalKeyStringIdentifying key of the property
valueTypeStringType of the expected value. May be TEXT, NUMBERIC or BOOLEAN
valueString/NumericThe current value for the propery
valueOptionsArrayAn array containing allowed values for the property. If empty, doesn't contain any restriction for the value.
parameterTypeIdNumericIdentifying id for the property

On error, returns 404.

PUT /api/v1/unit/:unitId/properties

Sets property details. 

The current property detail keys are:


ExternalKeyValue
NUMBER_OF_ROOMSNumber
KITCHEN_TYPEKitchen , Open Plan Kitchen , Kitchenette , Small Kitchen , Kitchenette w/ window , Scullery
SAUNATrue / False
BALCONY_TYPEBalcony,Glazed Balcony,French Balcony
LOT_SIZENumber
LOT_OWNEDTrue / False
CONDITIONNew, Excellent, Good, Mediocre, Poor

Parameters

Name

TypeDescription
valueString/NumericThe new current value for the property
externalKeyStringIdentifying key for the property value

Results

On Success, returns 200 and an array of properties and their values. It's recommended to check these parameters before getting value for the property since they can affect in that. The array contains following fields:

Name

TypeDescription
titleStringTitle of the property
externalKeyStringIdentifying key of the property
valueTypeStringType of the expected value. The value is either TEXT, NUMERIC or BOOLEAN
valueString/NumericThe current value for the property
valueOptionsArrayAn array containing allowed values for the property. If empty, doesn't contain any restriction for the value.
parameterTypeIdNumericIdentifying id for the property

On error, returns 404.

GET /api/v1/unit/:unitId/analytics

Get analytical values, such as monetary value of a unit. (unitId).

Parameters

None.

Results

On Success, returns 200 and a list of property unit related analytics values where one element consists of the following parameters

Name

TypeDescription
yearIntegerValue year
month
Value month
propertyBuildingIdIntegerImmutable building ID
propertyUnitIdIntegerImmutable unit ID
valueIdIntegerImmutable value ID
valueIntegerAnalytics value
typeStringAnalytics type
periodStartStringValue's validity period start
periodEndStringValue's validity period start

On error, returns 404.