API: Component Ratings

The New Constructs Component Ratings API provides immediate access to our component ratings on 3400+ stocks, 1100+ ETFs, and 6100+ mutual funds. Ratings are updated daily.


For more information about our rating methodology, see the Education section of our website.

API: Component Ratings

Endpoint
URL
Method
/ratings/component/:ticker
GET
URL Parameters
Name
Description
Example
:ticker
Ticker of the stock, ETF, or mutual fund. You can use the coverage endpoint to get full lists of options.
Header Parameters
Name
Value
x-api-key
[New Constructs-provided API key]
Content-Type
application/json
Return Values
Name
Description
Example
ticker
Ticker of the listed security.
AAPL
name
Name of the security.
Apple Inc.
rating_overall
Rating: Overall Risk/Reward Rating (see Rating Definitions table; our best rating is 1 and our worst rating is 5)
1
rating_stock_price_sa_p_ebv_p_sosa
Rating: Price-to-EBV (Economic Book Value) Ratio
2
rating_gap
Rating: GAP (Growth Appreciation Period)
5
rating_fcf_yield
Rating: FCF (Free Cash Flow) Yield
3
rating_roic
Rating: ROIC (Return on Invested Capital)
2
rating_income_net_economic_profit
Rating: Economic vs Reported EPS
1
rating_expense_total_annualized
Rating: Expense Total Annualized (ETFs and mutual funds only)
2
rating_allocation_pct_cash
Rating: Allocation Percent Cash (mutual funds only)
4
Sample Call:
Check out Python examples and more in our GitHub repo.
curl -i -H 'x-api-key: [New Constructs-provided API key]' -H "Content-Type: application/json" 'https://api.newconstructs.com/v1/ratings/component/A'
Success Response: 

{ "statusCode": 200
  "headers": {"Content-Type": "application/json"},
  "body": {
    "results": {
      "rating_stock_price_sa_p_ebv_p_sosa": 3,
      "rating_gap": 5,
      "rating_fcf_yield": 2,
      "rating_roic": 3,
      "rating_income_net_economic_profit": 1,
      "rating_overall": 3,
      "ticker": "A",
      "name": "Agilent Technologies, Inc."
    }
  }
}

API: Rating Definitions

Numeric Rating Value
Definition
1
Very Attractive - our best rating
2
Attractive
3
Neutral
4
Unattractive
5
Very Unattractive - our worst rating

API: Data Definitions

Rating Name
Function Value
Definition
Overall Risk/Reward Rating
1
Rating: Overall Risk/Reward Rating (see Table 4-1; our best rating is 1 and our worst rating is 5)
Economic vs. Reported EPS Rating
2
Rating: Economic vs Reported EPS
ROIC Rating
3
Rating: ROIC (Return on Invested Capital)
Free Cash Flow Yield Rating
4
Rating: FCF (Free Cash Flow) Yield
Price-to-Economic Book Value Rating
5
Rating: Price-to-EBV (Economic Book Value) Ratio
Growth Appreciation Period Rating
6
Rating: GAP (Growth Appreciation Period)
Total Annual Costs Rating
7
Rating: Expense Total Annualized (ETFs and mutual funds only)
Cash Allocation Rating
8
Rating: Allocation Percent Cash (mutual funds only)
Security Name
9
Note that this is not a rating; the name of the security provided for convenience.

API: Ratings Errors

Error
Message
Error Code
RatingNotFound
The requested rating information was not found.
404