Documentation

API

Here we document a few of the REST API HTTP endpoints behind the PortfolioTree webapp.

You can use them for programmatic interaction with public data.

Although the specification below is subject to change without notice, you may use it to do things like write scripts or integrate with your own custom (personal use) dashboards. In the future we will provide stable libraries for interacting with our API.

Most of the examples use CURL; however, you can use whatever language tooling you like.

Path parameters that start with a colon ‘:’ (unicode character U+00F8) are variables. For example: https://portfoliotree.com/api/portfolio/:_id, the “_id” is the name of a path parameter. It should be replaced with some valid value. You can find this in the portfolio profile URL.

Endpoints

POST /api/portfolio-risk-from-inputs

This endpoint allows you to calculate portfolio risk from asset risks, weights, and correlations.

Example
curl -X POST https://portfoliotree.com/api/portfolio-risk-from-inputs \
  -H 'Content-Type: application/json' \ 
  -d '{"risks": [0.1, 0.2], "weights": [50, 50], "correlations": [[1, 0.2],[0.2, 1]]}'
Output
{"risk":0.12}

GET /api/asset

This endpoint returns metadata about securities. It can receive multiple “id” parameters. One for each security. It can receive a single benchmark parameter.

Query Parameters
  • “id” (variadic): specifies a Security ID. This is usually a ticker such as SPY or GOOG.
  • “benchmark”: specifies the ticker to use as a benchmark.
Example
curl 'https://portfoliotree.com/api/asset?id=AGG&id=ACWI&benchmark=BIGPX'
Output
{
  "assets": [
    {
      "id": "AGG",
      "name": "iShares Core U.S. Aggregate Bond ETF",
      "availablePeriods": 4793,
      "dataStart": "2003-09-29T04:00:00Z",
      "dataEnd": "2022-10-11T04:00:00Z",
      "type": "ETF",
      "url": "",
      "periodicMetrics": {
        "returns": {
          "fiveYears": -0.18,
          "inceptionKey": 3.87,
          "oneDay": 0.04,
          "oneMonth": -2.57,
          "oneWeek": -1.11,
          "oneYear": -9.43,
          "tenYears": 0.61,
          "threeMonths": -3.47,
          "threeYears": -2.11
        },
        "risks": {
          "fiveYears": 3.57,
          "inceptionKey": 3.87,
          "oneMonth": 0.37,
          "oneWeek": 0.15,
          "oneYear": 4.48,
          "tenYears": 3.01,
          "threeMonths": 0.33,
          "threeYears": 4.34
        },
        "sharpes": {
          "fiveYears": -0.03,
          "inceptionKey": 0.19,
          "oneYear": -0.93,
          "tenYears": 0.04,
          "threeYears": -0.21
        },
        "inceptionDate": "2003-09-29T04:00:00Z"
      }
    },
    {
      "id": "ACWI",
      "name": "iShares MSCI ACWI ETF",
      "availablePeriods": 3661,
      "dataStart": "2008-03-31T04:00:00Z",
      "dataEnd": "2022-10-11T04:00:00Z",
      "type": "ETF",
      "url": "",
      "periodicMetrics": {
        "returns": {
          "fiveYears": 3.69,
          "inceptionKey": 19.83,
          "oneDay": -0.69,
          "oneMonth": -9.49,
          "oneWeek": -4.67,
          "oneYear": -18.18,
          "tenYears": 6.66,
          "threeMonths": -6.39,
          "threeYears": 3.23
        },
        "risks": {
          "fiveYears": 16.74,
          "inceptionKey": 19.83,
          "oneMonth": 1.39,
          "oneWeek": 0.67,
          "oneYear": 17.64,
          "tenYears": 14.31,
          "threeMonths": 1.14,
          "threeYears": 19.32
        },
        "sharpes": {
          "fiveYears": 0.37,
          "inceptionKey": 0.47,
          "oneYear": -1.81,
          "tenYears": 0.61,
          "threeYears": 0.35
        },
        "inceptionDate": "2008-03-31T04:00:00Z"
      }
    }
  ],
  "benchmark": {
    "id": "BIGPX",
    "name": "BlackRock Gwth Ptf Institutional",
    "availablePeriods": 3697,
    "dataStart": "2006-12-27T05:00:00Z",
    "dataEnd": "2021-09-02T04:00:00Z",
    "type": "Mutual Fund",
    "url": "",
    "periodicMetrics": {
      "returns": {
        "fiveYears": 8.08,
        "inceptionKey": 13.26,
        "oneDay": 0.21,
        "oneMonth": 1.32,
        "oneWeek": 0.97,
        "oneYear": 11.9,
        "tenYears": 8.59,
        "threeMonths": 1.88,
        "threeYears": 8.91
      },
      "risks": {
        "fiveYears": 7.36,
        "inceptionKey": 13.26,
        "oneMonth": 0.28,
        "oneWeek": 0.27,
        "oneYear": 7.63,
        "tenYears": 9.11,
        "threeMonths": 0.31,
        "threeYears": 8.61
      },
      "sharpes": {
        "fiveYears": 0.7,
        "inceptionKey": 0.55,
        "oneYear": 1.02,
        "tenYears": 0.74,
        "threeYears": 0.77
      },
      "inceptionDate": "2006-12-27T05:00:00Z"
    }
  },
  "correlations": [
    [
      1,
      -0.02
    ],
    [
      -0.02,
      1
    ]
  ]
}

GET /api/portfolio/:_id

This endpoint returns portfolio specification and includes the latest report data. The response is huge. Consider using jq for inspecting it.

Example

Top level report field not included in example output because it is nearly 20k lines long.

curl https://portfoliotree.com/api/portfolio/5f456687fedae83924931071 | jq 'del(.report)'
Output
{
  "id": "5f456687fedae83924931071",
  "authorID": "5fa5ccaf64ab4340af6e994c",
  "name": "60/40",
  "assets": [
    {
      "symbol": "AGG"
    },
    {
      "symbol": "ACWI"
    }
  ],
  "implementationSpec": {
    "weightAlgorithm": "UserInput",
    "rebalancingInterval": "Quarterly",
    "policyUpdateInterval": "Never",
    "lookBackDuration": "",
    "userInputWeights": [
      0.4,
      0.6
    ]
  },
  "factors": [
    {
      "id": "5fa7871f1a7dd8bfa14e24e3",
      "name": "Market"
    },
    {
      "id": "60ae9aa4dc3fe02bbf72dc00",
      "name": "U.S. (Non-U.S.)"
    },
    {
      "id": "5fa77cdce845242b9b33e027",
      "name": "Value (Growth)"
    },
    {
      "id": "5fa786b61a7dd8bfa14e24e2",
      "name": "Small (Large)"
    },
    {
      "id": "5fa8eb6da9cf999a0c632a16",
      "name": "Credit"
    },
    {
      "id": "5fa83b7ea9cf999a0c632a0f",
      "name": "Duration"
    }
  ],
  "depth": 4,
  "isFactor": false,
  "benchmark": "BIGPX",
  "description": "",
  "isPrivate": false
}

GET /api/portfolio/:_id/report-data.csv

This endpoint responds with returns formatted as comma separated values.

Example

This example only fetches the latest 10 days of returns.

curl https://portfoliotree.com/api/portfolio/5f456687fedae83924931071/report-data.csv | sponge | head -n 11
Portfolio Returns (Time),Portfolio Returns (Value),Portfolio Daily Rebalanced Returns (Time),Portfolio Daily Rebalanced Returns (Value),Asset 1 Returns (Time),Asset 1 Returns (Value),Asset 2 Returns (Time),Asset 2 Returns (Value),Factor 1 Returns (Time),Factor 1 Returns (Value),Factor 2 Returns (Time),Factor 2 Returns (Value),Factor 3 Returns (Time),Factor 3 Returns (Value),Factor 4 Returns (Time),Factor 4 Returns (Value),Factor 5 Returns (Time),Factor 5 Returns (Value),Factor 6 Returns (Time),Factor 6 Returns (Value),Benchmark Returns (Time),Benchmark Returns (Value),Risk Free Returns (Time),Risk Free Returns (Value)
2021-09-02,0.0017,2021-09-02,0.0017,2021-09-02,0.0007,2021-09-02,0.0024,2021-09-02,0.0024,2021-09-02,0.0005,2021-09-02,0.0052,2021-09-02,0.0037,2021-09-02,0.0002,2021-09-02,0.0008,2021-09-02,0.0021,2021-09-02,0
2021-09-01,0.0022,2021-09-01,0.0022,2021-09-01,0.0002,2021-09-01,0.0036,2021-09-01,0.0036,2021-09-01,-0.0062,2021-09-01,-0.0026,2021-09-01,0.005,2021-09-01,0.0004,2021-09-01,0.0003,2021-09-01,0.0017,2021-09-01,0
2021-08-31,0,2021-08-31,0,2021-08-31,-0.001,2021-08-31,0.0006,2021-08-31,0.0006,2021-08-31,-0.0042,2021-08-31,0.0022,2021-08-31,0.0037,2021-08-31,-0.0002,2021-08-31,-0.0013,2021-08-31,-0.0008,2021-08-31,0
2021-08-30,0.0017,2021-08-30,0.0017,2021-08-30,0.0007,2021-08-30,0.0023,2021-08-30,0.0023,2021-08-30,0.003,2021-08-30,-0.0116,2021-08-30,-0.0075,2021-08-30,-0.0002,2021-08-30,0.0014,2021-08-30,0.0004,2021-08-30,0
2021-08-27,0.0057,2021-08-27,0.0057,2021-08-27,0.0018,2021-08-27,0.0083,2021-08-27,0.0083,2021-08-27,0.0014,2021-08-27,-0.0017,2021-08-27,0.0189,2021-08-27,0.0016,2021-08-27,0.0023,2021-08-27,0.0063,2021-08-27,0
2021-08-26,-0.0033,2021-08-26,-0.0033,2021-08-26,0.0001,2021-08-26,-0.0055,2021-08-26,-0.0055,2021-08-26,0.0001,2021-08-26,0.0006,2021-08-26,-0.0047,2021-08-26,-0.0002,2021-08-26,0,2021-08-26,-0.0034,2021-08-26,0
2021-08-25,0.0002,2021-08-25,0.0002,2021-08-25,-0.0012,2021-08-25,0.0011,2021-08-25,0.0011,2021-08-25,0.002,2021-08-25,0.0014,2021-08-25,0.001,2021-08-25,0.0012,2021-08-25,-0.0028,2021-08-25,0.0013,2021-08-25,0
2021-08-24,0.002,2021-08-24,0.002,2021-08-24,-0.001,2021-08-24,0.004,2021-08-24,0.004,2021-08-24,-0.0042,2021-08-24,0.0003,2021-08-24,0.0066,2021-08-24,0.0004,2021-08-24,-0.0019,2021-08-24,0.0025,2021-08-24,0
2021-08-23,0.0052,2021-08-23,0.0053,2021-08-23,0,2021-08-23,0.0088,2021-08-23,0.0088,2021-08-23,-0.0002,2021-08-23,-0.007,2021-08-23,0.0098,2021-08-23,0.0003,2021-08-23,0.0002,2021-08-23,0.0055,2021-08-23,0

*[HTML]: Hyper Text Markup Language

Correlation Matrix

Correlation Matrix Example

Description

To get the “free lunch” of diversification in a portfolio, the assets need to be able to move independently from one another—so when one asset zigs, another asset zags. The mathematical measure of how “different” two investments are is called correlation.

  • If two assets have a correlation of 1, they are perfectly correlated. Perfectly correlated assets don’t provide any diversification, because they mirror each other’s every move.
  • If two assets have a correlation of 0, they are uncorrelated. Uncorrelated assets are indifferent to each other; what one does provides no information about what the other will do.
  • If two assets have a correlation of -1, they are negatively correlated. Negatively correlated assets mirror each other, but in opposite directions. When one asset is down, the other asset is up.

Uses

Viewing the correlation matrix can help determine if an asset is helping to diversify a portfolio. If an added asset has a correlation of 0.9 to another asset, the two are going to “co-move” most of the time, so the additional asset provides very little diversification. This could inform a decision to remove the asset, or reduce the weight to the asset in order to give more diversifying assets more room.

Efficient Frontier Chart

Efficient Frontier Example

Description

Most investors prefer to maximize returns while also minimizing risk. Since return without risk is very rare to find, it is helpful to see how the two are related. The chart visualizes the relationship between risk and return to measure how “efficiently” risk is being used. The most efficient portfolio either provides the highest return for a fixed level of risk, or the lowest risk for a fixed level of return. These optimal combinations can be found along the convex upper-left-hand border, called the “frontier”. If your portfolio is close to this frontier, you are getting the most bang (return) for your buck (risk).

  • Each blue square is plotting one of the assets in the portfolio
  • The red square plots the portfolio’s risk & return as a whole
  • The gray dots plot other possible combinations of the portfolio assets to sample the possible range of outcomes from a risk/return perspective.
  • The darker-gray dots have more consistent risk/return ratios (preferable), while the lighter-gray dots have less consistent risk/return ratios (not preferable).
  • The plots will often appear to curve inwards (like a “C”). This is the “free lunch” of diversification that allows portfolios that combine uncorrelated assets to achieve a given return for less risk.

Uses

Observing a portfolio’s plot (in red) versus a sampling of other weight combinations (in gray) helps to visualize how risk-efficient a portfolio is relative to a range of other possibilities. The position of the portfolio plot can also inform how successfully a weighting algorithm is accomplishing its goal. For example, a weighting algorithm that minimizes variance should be able to plot very close to the farthest left point in the dot plot.

Factor Attribution

Factor Attribution Example

Description

Since risk factors often explain the sources of returns for a portfolio, it is possible to use factor coefficients of a portfolio to disaggregate the source of a portfolio’s returns. This is only meaningful when the risk factors provide good explain-ability (have a high adjusted R2).

  • A portfolio with a positive coefficient to a risk factor will contribute positive returns if the risk factor had positive returns. A positive coefficient to a risk factor that had negative returns will result in negative return contribution to the portfolio.
  • A portfolio with a negative coefficient to a risk factor will contribute positive returns if the risk factor had negative returns. A negative coefficient to a risk factor that had positive returns will result in negative return contribution to the portfolio.

Uses

Being able to attribute a portfolio’s returns back to fundamental risk factors has many benefits. If a portfolio performed well, but the majority of the returns came from a single risk factor that you don’t feel confident will do well in the coming years, that can help attenuate expectations for future performance. If a portfolio underperformed a benchmark, but under-performance was driven by a factor you have high confidence in the future, that might bolster expectations of performance going forward. This is a useful way to determine if a portfolio is responding to the types of risks you are targeting.

Factor Coefficients

Factor Coefficients Example

Description

Returns rarely present themselves without taking on risk. Returns that come in exchange for taking on known risks are called risk premiums. A handful of risk premiums do a pretty good job of explaining a portfolio’s returns. We can “regress” a portfolio against these known risk factors to measure how exposed a portfolio is to each one.

  • The measure of how exposed a portfolio is to a risk factor is called its “coefficient”. It can be used as a multiple to measure the degree to which a portfolio is impacted by a risk factor.
  • A positive coefficient means that the portfolio makes money when the risk factor makes money. A negative coefficient means the portfolio loses money when the risk factor makes money.
  • Combining risk factors can help “explain” the sources of returns for a portfolio; however, not all portfolios can be explained equally. To measure how good of a job the selected risk factors do in explaining the sources of returns for a portfolio, R2 can be used. R2 and adjusted R2 (for multiple risk factors) will be between 0 & 1, where 0 provides no explanation and 1 provides perfect explanation.

Uses

Knowing what risk factors you are exposed to can help measure if a portfolio matches your risk tolerances or needs. If a portfolio has a high coefficient to a risk factor that is undesirable, it can prompt a change. Such information can also add conviction in a strategy if exposure to the risk factor is desired.

Historical Weights Chart

Historical Weights Example

Description

For portfolios with two or more assets, the amount invested in each asset can vary over time—either due to drift (changes in asset prices), or due to changing the desired allocation (set by the policy). To track the exposure of a portfolio over time, the weight—or percent—invested in each asset is displayed since the portfolio’s inception. Each color represents an asset in the portfolio

The value of the portfolio will change over time, but the weight is always reflected in percentages (so the total adds up to 100%).

Uses

Tracking historical weights of a portfolio can help ensure that an investment isn’t overly exposed to a single asset. It also helps visualize the impact of choices such as how often to rebalance, the frequency for updating policy weights, or the preferred weighting algorithm.

Return Distribution Chart

Return Distribution Example

Description

A portfolio will tend to have many periods where the returns are slightly above and below the average, and fewer periods where the returns are way above and below the average. If we visualize these periodic returns by plotting how frequently each occurs, we get a snapshot of how common each periodic return is.

  • Most periodic returns are centered around the average (the highest point on the chart). The lower each bar on the chart, the less commonly that return showed up.
  • The red line shows what a “normal” distribution looks like, which is a statistical distribution. Its exact properties aren’t important, but it helps to visualize the shape of a portfolio’s distribution versus the normal distribution to observe where the two differ.
  • Most portfolios tend to have “excess kurtosis” which more simply means, “fat tails”. When the “tails” (far left and right bars) on a distribution are fatter than the normal distribution, this means more extreme returns should be expected.
  • Most portfolios also tend to have “skew”. Skew refers to having more extreme returns on one side of the distribution than another. Most portfolios are “negatively skewed” like the image above, meaning large negative returns are likely to occur more frequently than large positive returns.

Uses

Knowing the distribution of a portfolio can help mentally prepare for what the day-to-day reality of living with a portfolio is like. The more fat-tailed a portfolio is, the more “once-in-a-lifetime” experiences you’ll go through. Things that should only happen once every 100,000 years will occur once a decade. A portfolio with high negative skew will look amazing 90% of the time, but then have a devastating loss out of the blue that wipes out most of the gains from before. Negative skew tends to lure investors into a false state of confidence when gains are realized. But those gains aren’t really paid for until the inevitable wipe out hits the reset button. Both excess kurtosis and negative skew can be managed by seeking out diversifying assets. You may even find positively skewed assets to help balance the portfolio out.

User Privacy

User Data

The PortfolioTree server stores a unique identifier connecting your PortfolioTree account to the Linked In account you use to log in. The server does not save your name nor internet protocol (IP) address.

The user identifiers are stored indefinitely. However, feel free to contact us and we will scrub the identifier from our database.

Browser Cookies

The PortfolioTree server uses two cookies:

  1. The login flow cookie is required for the OAuth flow used to authenticate a user.
  2. The authentication cookie is used by the server to know if a user is logged in and how long ago you logged in. The cookie stores a JSON web token which includes metadata such as when you logged in, the user ID, and some other time and cryptography related information.

Both cookies are only set after you attempt logging in.

Emails and Notifications

Currently, our code and web pages do not collect an email address on the website. The only way we would have your email address is if you email our contact us address. We do not send any marketing emails and currently only would use your email address to respond to support requests and questions you send us. After emailing us, if you’d like us to delete your email address from our records, feel free to ask us to do so via email.

Contributor Training

The contributors (aka software developers) working on the PortfolioTree website have gone through user privacy and data training.

Data Protection Officer

Fewer than 250 people are involved with building the PortfolioTree codebase so no Data Protection Officer has been named.