Proposed portfolio API

Methods

Each request includes a user token for authentication in addition to the parameters specified below and may cause an authentication-related error such as AUTH_TOKEN_INVALID or AUTH_TOKEN_EXPIRED.

GET /portfolio/list

Gets all portfolios of the current user with basic information to display in the portfolio dashboard.

Response

parameter	type
portfolios	portfolioOverview[]

Errors

(no errors)

GET /portfolio/details/{id}

Gets portfolio details including key figures, scores and positions.

URL parameters

parameter	type
id	string

Response

parameter	type
portfolio	portfolioDetails

Errors

• PORTFOLIO_ID_INVALID

GET /portfolio/performance/{id}

Gets the data points to display a performance chart.

URL parameters

parameter	type
id	string

Response

parameter	type	description
chart	[number, number][]	Each datapoint is a tuple of timestamp and value

Errors

• PORTFOLIO_ID_INVALID

GET /portfolio/stock/{symbol}

Gets the portfolio name and quantity of a specified stock for all portfolios of the current user. This information is displayed to the user when adding a stock to his portfolios.

URL parameters

parameter	type
symbol	string

Response

parameter	type
portfolios	portfolioStock[]

Errors

• SYMBOL_INVALID

PUT /portfolio/stock/{symbol}

Modifies a stock's quantity within multiple portfolios simultaneously.

If the specified quantity for a portfolio is 0, the position in the specified portfolio is deleted if it exists.
If there is no position in the specified portfolio, a new position with the specified quantity is created.
Otherwise, the position in the specified portfolio is updated to match the specified quantity.

Positions not included in the request remain unchanged.

URL parameters

parameter	type
symbol	string

Request body

parameter	type
modifications	portfolioQty[]

Response

(empty)

Errors

• PORTFOLIO_ID_INVALID
• SYMBOL_INVALID
• QTY_INVALID
• REAL_PORTFOLIO_MODIFICATION

POST /portfolio/create

Creates a new, empty, virtual portfolio and saves the timestamp of the portfolio creation in the portfolio's history.

Request body

parameter	type
name	string

Response

parameter	type
id	string

Errors

• PORTFOLIO_NAME_INVALID
• PORTFOLIO_NAME_DUPLICATE

DELETE /portfolio/{id}

Deletes a portfolio.

URL parameters

parameter	type
id	string

Response

(empty)

Errors

• PORTFOLIO_ID_INVALID

PUT /portfolio/rename/{id}

Renames a portfolio.

URL parameters

parameter	type
id	string

Request body

parameter	type
name	string

Response

(empty)

Errors

• PORTFOLIO_ID_INVALID
• PORTFOLIO_NAME_INVALID
• PORTFOLIO_NAME_DUPLICATE

PUT /portfolio/modify/{id}

Modifies the positions of a portfolio and saves the timestamp of the modification in the portfolio's history.

If the specified quantity of a position is 0, the position of the specified stock is deleted if it exists.
If there is no position of the specified stock, a new position with the specified quantity is created.
Otherwise, the position of the specified stock is updated to match the specified quantity.

Positions not included in the request remain unchanged.

URL parameters

parameter	type
id	string

Request body

parameter	type
modifications	positionQty[]

Response

(empty)

Errors

• PORTFOLIO_ID_INVALID
• SYMBOL_INVALID
• QTY_INVALID
• REAL_PORTFOLIO_MODIFICATION

POST /portfolio/duplicate/{id}

Creates a new virtual portfolio as a duplicate of a real or virtual portfolio. Changes to a real portfolio will not be tracked in the duplicated version.

URL parameters

parameter	type	description
id	string	ID of the portfolio to copy

Request body

parameter	type	description
name	string	Name of the new portfolio

Response

parameter	type	description
id	string	ID of the new portfolio

Errors

• PORTFOLIO_ID_INVALID
• PORTFOLIO_NAME_INVALID
• PORTFOLIO_NAME_DUPLICATE

Types

portfolioOverview

parameter	type	description
id	string	Unique portfolio ID
name	string	Portfolio name as specified by the user
virtual	boolean	true if the the portfolio is virtual
positionCount	number (Int)	Number of positions currently in the portfolio
value	number (FP)	Total monetary value of the portfolio
score?	number	Evaluation score (empty if positionCount == 0)
perf7d	number (FP)	7-day portfolio performance (absolute)
perf7dPercent	number (FP)	7-day portfolio performance (percentage)
perf1y	number (FP)	1-year portfolio performance (absolute)
perf1yPercent	number (FP)	1-year portfolio performance (percentage)
modified	number (UNIX timestamp)	Timestamp of the last modification to the portfolio's positions

portfolioDetails

parameter	type	description
overview	portfolioOverview	Portfolio overview
positions	position[]	All positions in the portfolio
risk?	riskAnalysis	Portfolio risk analysis
keyFigures?	keyFigures[]	key figures per year
nextDividend?	number (UNIX timestamp)	next dividend payout
totalReturn?	number (FP)	return since portfolio creation
totalReturnPercent?	number (FP)	return since portfolio creation
analytics?	analytics	Portfolio analytics

Optional values are present iff the portfolio is not empty.

position

parameter	type	description
stock	stock
qty	number
totalReturn	number (FP)	return since portfolio creation
totalReturnPercent	number (FP)	return since portfolio creation

positionQty

parameter	type
symbol	string
qty	number

portfolioQty

parameter	type	description
id	string	Portfolio ID
qty	number	Quantity of a stock in the portfolio

portfolioStock

parameter	type	description
id	string	Portfolio ID
name	string	Portfolio name
virtual	boolean	true if the the portfolio is virtual
qty	number	Quantity of a stock in the portfolio

stock

parameter	type	description
symbol	string	Ticker symbol
name	string
price	number (FP)	Price per share
perf7d	number (FP)	7-day performance (absolute)
perf7dPercent	number (FP)	7-day performance (percentage)
perf1y	number (FP)	1-year performance (absolute)
perf1yPercent	number (FP)	1-year performance (percentage)
volatility	number (FP)
debtEquity	number (FP)
score	number	score within the portfolio (sell/hold/buy recommendation)

keyFigures

parameter	type	description
year	number (Int)
pte	number (FP)	price to earnings ratio
ptb	number (FP)	price to book ratio
ptg	number (FP)	price to earning growth ratio
eps	number (FP)	earnings per share
div	number (FP)	paid out dividend in percentage per share
dividendPayoutRatio	number (FP)	dividend payout ratio

riskAnalysis

parameter	type
countries	diversification
segments	diversification
currency	diversification

analytics

parameter	type
volatility	number (FP)
standardDeviation	number (FP)
sharpeRatio	number (FP)
treynorRatio	number (FP)
debtEquity	number (FP)
correlations	correlations

correlations

{[string]: number}

The keys are 2 ticker symbols separated by ;. The values are correlation scores between 2 stocks.

Only the 10 largest positions are included.

Example

{
  'AAPL;GOOG': 0.397373186,
  'AAPL;AMZN': 0.352196405,
  'GOOG;AMZN': 0.57879282,
  ...
}

diversification

{[string]: number}

Keys are names/codes of countries/segments/currencies. Values are percentages (total should be approximately 1).

TODO: Maybe add an internal API that provides all known countries, segments and currencies for localization purposes.

Example for countries

{ 'USA': 0.5, 'Germany': 0.3, 'China': 0.2}

Errors

Error response:

{
  error: XXX
}

Numeric error codes are mapped to these types:

error	description
AUTH_TOKEN_INVALID	The provided authentication token is missing or not valid.
AUTH_TOKEN_EXPIRED	The user's session has expired.
PORTFOLIO_ID_INVALID	The portfolio ID has an invalid format or the portfolio does not exist.
PORTFOLIO_NAME_INVALID	The portfolio name is empty or exceeds the allowed length.
PORTFOLIO_NAME_DUPLICATE	The user has an existing portfolio with the same name.
SYMBOL_INVALID	No stock for a specified ticker symbol has been found.
QTY_INVALID	The quantity is negative or too large.
REAL_PORTFOLIO_MODIFICATION	The positions of a real portfolio cannot be modified.