Welcome to the Portfolio123 API Knowledge base. Here you will find documentation for our Data, Universe, Rank and Screen APIs.
About This Documentation
For our REST APIs, this documentation is powered by OpenAPI specifications.
An integrated REST client is embedded directly in the "Try it out" section of each page powered by OpenAPI. Once you have obtained an API key, you can test calls without leaving the documentation portal. Alternatively you can test calls with any other GUI REST clients (Postman, Insomnia, Paw) or CLI tools like cUrl.
Finally, the OpenAPI specifications are compatible with tools in the Swagger ecosystem, so you can even generate a client for the programming language of your choice.
Before starting using the API, we recommend taking a look at how Portfolio123 Research works here
If you have any questions or concerns, we're listening.
- Support module: https://help.portfolio123.com/hc/en-us/requests/new
- Email: email@example.com
- Call: +1 312 586 1104
To begin using the API or the Data Miner you will need your own API Key. To do so login to your account on Portfolio123, click your user picture on top right, select Account Settings -> DataMiner & API, then click on ‘Select Membership’ or, if you already have an API membership, 'Create Key'. You will need both the ID and the KEY. This is your private, personal key and anyone with that key will be able to run requests using your account.
Getting Started with API
You can directly import our financial data and analyses from Portfolio123 API starting your request with:
Make sure to include your API key/token as the token parameter in the request query string.
client = p123api.Client(api_id='xx', api_key='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
Before dwelling on the API operations, a quick note on the syntax used.
Long term P123 users will recognize the input parameters from Portfolio123 interface, but for new users it might take some time to digest. The most important parameters are:
- Formulas: referring to both P123 factors and formulas (factor reference here);
- startDt / endDt: start and end date;
- pitMethod: “Prelim” includes preliminary data from earnings calls, while “Complete” only includes quarter or annual report data;
- rankingMethod: it specifies NA data treatment in a ranking system. 2 stands for Percentile NAs Negative, 4 stands for Percentile NAs Neutral
- transType: Transaction Type. Used for operations that involve backtest, it can be Long, Short, Long/short, Hedged
- tickers: stock symbols (such as AAPL);
- rebalFreq: data frequency, expressed in weeks. It can be Every Day, Every Week, Every 2 Weeks, Every 3 Weeks, Every 4 Weeks, Every 6 Weeks, Every 8 Weeks, Every 13 Weeks, Every 26 Weeks, Every 52 Weeks
- includeNames, includeNaCnt, includeFinalStmt, includeNodeDetails: True or false, depending if you want company names, information on NAs, FinalStms and node details.
Other parameters are specified on each operation paragraph.
Parameters can be mandatory or optional. For each API operation example, optional parameters are shown in the image.
With Portfolio123 API you will be able to automatically generate output from several P123 Research tools: Data, Universe, Ranking, Screening. We will now go through each operation: how to operate it, its subscription requirements, and examples.
You can find the code for all of the examples below here: SAMPLE CODE
Be aware that you will need a Research subscription in order to access the API; check out our subscription options here.
This operation allows you to retrieve large sets of data from our point in time engine. You will need to obtain your own license from the data vendor (Factset or Compustat) to fully access.
You can try it without a license with the following stocks: IBM, MSFT & INTC. The sample data is available with 5 years of history.
In this example we are downloading weekly data on several factors (#AnalystsCurQ, ROE%TTM, …) for Microsoft and IBM.
This operation allows you to retrieve point in time data for a selected universe. A data license with the data providers we support (Compustat or Factset) is required for this operation in order to return fundamental factors. However, you can retrieve most price related data and derived fundamental factor ranks and z-scores without a vendor data license. An example of derived data would be the Price to Sales rank vs the other stocks in the stocks industry.
In this example we are retrieving data from 11/19/2020 for the S&P 500 constituents. The first factor is the rank of the stocks Price to Sales vs the other stocks in the S&P 500. The second factor is their rank vs the other stocks in their subindustry.
This operation updates the Universe saved on the API, also called ApiUniverse. If you don’t have this Universe already saved in the platform, it will be created. Universe rules are expresses as “rules”:[“…”,”…”, … ]. Type can be stock, ETF or CEF.
This operation allows you to retrieve rank data from a ranking system of your choice for a specific universe or a set of tickers.
In this example we are downloading rank data from our “Core: Value” ranking system on 11/12/2020 for several factors; the universe selected is the Dow Jones 30 (DJIA). This universe will be used during the ranking, but the only ranks returned will be for IBM and MSFT since the tickers rule acts as a filter.
This operation lets you run multiple bucket performance tests of multifactor ranking systems. You can specify the system directly as well as use one of your existing ones. Other specific settings include the number of buckets, minimum price, transaction slippage (expressed in %), sector, benchmark and output type. The output includes many more statistics than what the website offers (to collect these stats the API runs a screen backtest for each bucket).
In this example we are making a 6-month test of a P123 ranking system “Core: Value”. It divides the DJIA universe in ten buckets and compares them to the universe and the benchmark.
This operation updates the ranking system saved on the API, also called ApiRankingSystem. If you don’t have this ranking system already saved in the platform, it will be created. To easily create the nodes lines create a ranking system in p123, go to the text editor for that ranking system and copy the text/XML. You will have to escape every quote that appears in the text by putting a \ in front of it. Paste that text into nodes in the script.
This operation allows you to run a Screen. You can specify the system directly as well as use one of your existing ones. One setting specific to Screen is Type, in which you can specify whether it is a stock or ETF screen.
This operation allows you to run a performance backtest of a Screen. Other specific settings include the number of buckets, minimum price, transaction slippage (expressed in % point), long and short weight, rank tolerance, carry cost and risk statistics period.
In this example we are making a six-month test of a P123 screen “Piotroski”. It divides the DJIA universe in ten buckets and compares them to the universe and the benchmark.
This operation allows you to run and collect the output of rolling screens. Rolling screens are subsequent, fixed holding period backtests of a screen, moving forward the starting date for each test. Rolling screens are excellent robustness tests. Other specific settings include the transaction price, maximum position percentage, long and short weight, holding period.
In this example we are generating rolling screen output, testing our Piotroski screen on a six-month period rolling 4 weeks.
This operation returns the data from the Summary, Holdings (current) and Statistics tabs on the website for strategies and books. The only parameter is the name or code of the strategy or book.
You can create and store a custom data series on the website which consists of a list of dates and their associated values. There are 3 API endpoints available which create/update, delete or upload data to an imported data series. These endpoints are available in the API, but not in DataMiner.
Create a new data series:
Update an existing data series:
Delete a data series:
Upload data from a csv file into an existing data series:
You can create and store a custom stock factor on the website which consists of a list of dates, tickers and their associated values. There are 3 API endpoints available which create/update, delete or upload data to an imported stock factor. These endpoints are available in the API, but not in DataMiner.
Create a new stock factor:
Update an existing stock factor:
Delete a stock factor:
Upload data from a csv file into an existing stock factor: