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

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.

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

Inserts a new unit to a portfolio corresponding the id.

Parameters

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.

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.

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

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.

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

On error, returns 404.

Portfolio

Portfolios are collections of properties.

POST /api/v1/portfolio 

Creates a new portfolio.

Parameters

Results

On success, returns 200:

On error, returns 404.

PUT /api/v1/portfolio/:portfolioId 

Updates given portfolio with given id.

Parameters

Results

On success, returns 200:

On error, returns 404.

GET /api/v1/portfolio/:portfolioId 

Gets details of given portfolio.

Parameters

None

Results

On success, returns 200:

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.

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

Results

On Success, returns 200.

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

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

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

Results

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

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

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

Results

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

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:

On error, returns 404.

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

Sets property details. 

The current property detail keys are:

Parameters

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:

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

On error, returns 404.