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:

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. 

To add the building to portfolio, provide buildingId and name. To calculate renovations for building you need to provide floorArea, buildYear, buildingType, floors and location details. Location details should be address, postalCode and city.

Parameters

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.

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.

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