Past Performance API
Service Description¶
This API endpoint can be used to calculate the past performance of a portfolio. This can be done by providing start holdings and a series of transactions, or by providing a series of portfolio valuations and flows.
The Insight API endpoint for the past performance calculations is accessed through the following endpoints:
Below, we elaborate further on how to use these endpoints in practice.
Past Performance (from transactions) POST¶
The endpoint has a range of predefined fields to query data for. Let us look at an example.
curl -X "POST" \
"https://api.data.investsuite.com/performance/portfolio-past/" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "X-TENANT-ID: $TENANT_ID" \
-H "X-Api-Key: $IVS_API_SECRET" \
-d '{
"currency": "EUR",
"start_date": "2022-01-22",
"end_date": "2022-12-31",
"sample_frequency": "M",
"items_to_return": ["TWR", "PNL", "VALUE"],
"start_holdings": {"BE0003604155": 100.0, "$EUR": 50000},
"transactions": [
{
"deleted": false,
"movements": [
{
"type": "BUY",
"status": "EXECUTED",
"datetime": "2022-04-01T00:00:00+00:00",
"instrument_id": "BE0003604155",
"quantity": 5.0
},
{
"type": "SELL",
"status": "EXECUTED",
"datetime": "2022-04-01T00:00:00+00:00",
"instrument_id": "$EUR",
"quantity": -30150
}
]
}
]
}'
POST /performance/portfolio-past/ HTTP/1.1
Host: api.data.investsuite.com
X-TENANT-ID: $TENANT_ID
X-Api-Key: $IVS_API_SECRET
accept: application/json
Content-Type: application/json
{
"currency": "EUR",
"start_date": "2022-01-22",
"end_date": "2022-12-31",
"sample_frequency": "M",
"items_to_return": ["TWR", "PNL", "VALUE"],
"start_holdings": {"BE0003604155": 100.0, "$EUR": 50000},
"transactions": [
{
"deleted": false,
"movements": [
{
"type": "BUY",
"status": "EXECUTED",
"datetime": "2022-04-01T00:00:00+00:00",
"instrument_id": "BE0003604155",
"quantity": 5.0
},
{
"type": "SELL",
"status": "EXECUTED",
"datetime": "2022-04-01T00:00:00+00:00",
"instrument_id": "$EUR",
"quantity": -30150
}
]
}
]
}
| Field | Description | Data type | Example | Required |
|---|---|---|---|---|
start_holdings |
A dictionary containing the positions of the portfolio at the start date. | dict |
{"US46090E1038": 100.0, "$USD": 50000} | no |
start_date |
Start date of the performance period. If not given defaults to the first transaction date. | date |
"2022-01-31" | no |
end_date |
End date of the performance period. If not given defaults to the last transaction date. | date |
"2022-12-31" | no |
currency |
The currency of the portfolio in ISO format. | str |
"USD" | no |
transactions |
A list of transactions. | list |
yes | |
items_to_return |
Which calculations need to be returned. Options are "TWR", "PNL" and "VALUE". | list |
["TWR", "PNL"] | no |
sample_frequency |
Frequency for which the scenarios should be generated. Options are "D", "W", "M" or "Y". | str |
"M" | no |
The transactions can be provided by the following structure.
| Field | Description | Data type | Example | Required |
|---|---|---|---|---|
movements |
A list of movements within the transaction. | list |
yes | |
deleted |
A boolean flag to indicate a transaction was deleted. | bool |
false | no |
The movements can be provided by the following structure.
| Field | Description | Data type | Example | Required |
|---|---|---|---|---|
datetime |
The timestamp of the movement. | datetime |
"2022-04-01T00:00:00+00:00" | yes |
instrument_id |
The identifier of the instrument. | str |
"BE0003604155" | yes |
quantity |
The quantity transacted. | float |
5 | yes |
type |
The type of the transaction. | str |
"BUY" | yes |
status |
The status the transaction. | str |
"EXECUTED" | yes |
After uploading data, we get a response back:
{
"data": {
"PNL": {
"$EUR": {
"2022-01-31": 0.0,
"2022-02-28": 0.0,
"2022-03-31": 0.0,
"2022-04-30": 0.0,
"2022-05-31": 0.0,
"2022-06-30": 0.0,
"2022-07-31": 0.0,
"2022-08-31": 0.0,
"2022-09-30": 0.0,
"2022-10-31": 0.0,
"2022-11-30": 0.0,
"2022-12-31": 0.0
},
"BE0003604155": {
"2022-01-31": 20000.0,
"2022-02-28": -23000.0,
"2022-03-31": -74000.0,
"2022-04-30": -5850.0,
"2022-05-31": -93525.0,
"2022-06-30": -22650.0,
"2022-07-31": 10950.0,
"2022-08-31": 21450.0,
"2022-09-30": -21600.0,
"2022-10-31": 18300.0,
"2022-11-30": 69750.0,
"2022-12-31": 90750.0
},
"Other": {
"2022-01-31": 0.0,
"2022-02-28": 0.0,
"2022-03-31": 0.0,
"2022-04-30": 0.0,
"2022-05-31": 0.0,
"2022-06-30": 0.0,
"2022-07-31": 0.0,
"2022-08-31": 0.0,
"2022-09-30": 0.0,
"2022-10-31": 0.0,
"2022-11-30": 0.0,
"2022-12-31": 0.0
}
},
"TWR": {
"TWR": {
"2022-01-31": 1.0333889816360602,
"2022-02-28": 0.9616026711185311,
"2022-03-31": 0.8764607679465772,
"2022-04-30": 0.990233722871452,
"2022-05-31": 0.8438647746243736,
"2022-06-30": 0.9621869782971615,
"2022-07-31": 1.0182804674457429,
"2022-08-31": 1.0358096828046746,
"2022-09-30": 0.9639398998330555,
"2022-10-31": 1.0305509181969954,
"2022-11-30": 1.1164440734557601,
"2022-12-31": 1.1515025041736233
}
},
"VALUE": {
"$EUR": {
"2022-01-31": 50000.0,
"2022-02-28": 50000.0,
"2022-03-31": 50000.0,
"2022-04-30": 26150.0,
"2022-05-31": 26150.0,
"2022-06-30": 26150.0,
"2022-07-31": 26150.0,
"2022-08-31": 26150.0,
"2022-09-30": 26150.0,
"2022-10-31": 26150.0,
"2022-11-30": 26150.0,
"2022-12-31": 26150.0
},
"BE0003604155": {
"2022-01-31": 569000.0,
"2022-02-28": 526000.0,
"2022-03-31": 475000.0,
"2022-04-30": 567000.0,
"2022-05-31": 479325.0,
"2022-06-30": 550200.0,
"2022-07-31": 583800.0,
"2022-08-31": 594300.0,
"2022-09-30": 551250.0,
"2022-10-31": 591150.0,
"2022-11-30": 642600.0,
"2022-12-31": 663600.0
}
}
},
"meta": null
}
| Field | Description | Data type | Example | Required |
|---|---|---|---|---|
data |
Holds all the past performance data. | object |
yes | |
value |
The value of the positions in the portfolio over time. | dict |
yes | |
pnl |
The cumulative P&L of the positions in the portfolio over time. | dict |
yes | |
twr |
The time weighted return series of the portfolio. | dict |
yes |
Past Performance (from portfolio valuations and flows) POST¶
The endpoint has a range of predefined fields to query data for. Let us look at an example.
curl -X "POST" \
"https://api.data.investsuite.com/performance/portfolio-values-to-return/" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "X-TENANT-ID: $TENANT_ID" \
-H "X-Api-Key: $IVS_API_SECRET" \
-d '{
"portfolio_values": {
"portfolio_1": {"2020-01-01": 1, "2020-01-02": 12.1, "2020-01-03": 11.1},
"portfolio_2": {"2020-01-01": 1, "2020-01-02": 1.1, "2020-01-03": 1.1}
},
"calculation_methods": ["TWR"],
"flows": {"portfolio_1": {"2020-01-02": 11}, "portfolio_2": {"2020-01-01": 1}},
"sample_frequency": "D",
"flow_timing": "END_OF_PERIOD"
}'
POST /performance/portfolio-values-to-return/ HTTP/1.1
Host: api.data.investsuite.com
X-TENANT-ID: $TENANT_ID
X-Api-Key: $IVS_API_SECRET
accept: application/json
Content-Type: application/json
{
"portfolio_values": {
"portfolio_1": {"2020-01-01": 1, "2020-01-02": 12.1, "2020-01-03": 11.1},
"portfolio_2": {"2020-01-01": 1, "2020-01-02": 1.1, "2020-01-03": 1.1}
},
"calculation_methods": ["TWR"],
"flows": {"portfolio_1": {"2020-01-02": 11}, "portfolio_2": {"2020-01-01": 1}},
"sample_frequency": "D",
"flow_timing": "END_OF_PERIOD"
}
| Field | Description | Data type | Example | Required |
|---|---|---|---|---|
portfolio_values |
A dictionary containing the values of the portfolios over time. | dict |
{"portfolio_1": {"2020-01-01": 1, "2020-01-02": 12.1}} | yes |
calculation_methods |
The list of calculation methods to use. Only time weighted return is available now: "TWR". | list |
["TWR"] | yes |
flows |
A dictionary containing the flows of the portfolios over time. | dict |
{"portfolio_1": {"2020-01-02": 11}} | yes |
sample_frequency |
Frequency for which the scenarios should be generated. Options are "D", "W", "M" or "Y". | str |
"M" | no |
flow_timing |
The timing of the flows. Options are "START_OF_PERIOD" or "END_OF_PERIOD". Defaults to "END_OF_PERIOD". | str |
"END_OF_PERIOD" | no |
After uploading data, we get a response back:
{
"data": {
"TWR": {
"portfolio_1": {
"2020-01-01": 1.0,
"2020-01-02": 1.0999999999999996,
"2020-01-03": 1.0090909090909086
},
"portfolio_2": {
"2020-01-01": 1.0,
"2020-01-02": 1.1,
"2020-01-03": 1.1
}
}
},
"meta": null
}
| Field | Description | Data type | Example | Required |
|---|---|---|---|---|
data |
Holds all the past performance data. | object |
yes | |
twr |
The time weighted return series of the portfolios. | dict |
no |