Better ESG data for your analysis or application

Endpoint schema

Companies
Retrieve company-level information, ratings and metrics
Funds
Retrieve fund-level information, ratings and metrics
Causes
Retrieve the list of available causes on Ethos
Metrics
Retrieve the list of available metrics on Ethos

Getting started

Every firm on Ethos has a unique client_id and secret that you can use to access the Ethos API. You can find your client_id and secret under "Keys" in your account on Ethos.

Protocols and headers

The Ethos API uses POST requests to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Ethos API is served over HTTPS TLS v1.2+ to ensure data privacy. All requests must include a Content-Type of application/json and the body must be valid JSON.

Almost all Ethos API endpoints require a firm_id and secret. These may be sent either in the request body or in the headers ETHOS-FIRM-ID and ETHOS-SECRET.

Every Ethos API response includes a request_id in the returned JSON response (see examples below). The request_id is included regardless of whether or not the API request succeeded or failed. For faster support, include the request_id when contacting support regarding a specific API call.

API host

Development: https://development.ethosesg.com
Production: https://production.ethosesg.com
The Development environment is unrestricted and supports up to 100 API calls per week (contact us for additional calls). All testing should be done in the Development environment.

Company endpoints

Retrieve data on one or more companies, including company information, classification, ESG screens, ratings and metrics.
In this section

/companies/get

The /companies/get endpoint allows you to receive data about one or more Companies, including classification, geography, screens (e.g., fossil fuel, gambling or nuclear), and more.

Companies are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data associated with multiple Companies, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_companies response body field.

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
include_price
Whether or not to include price data (delayed 15-minutes) in the returned information
[true/false]
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of companies to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/companies/get
  1. curl -X POST https://development.ethosesg.com/companies/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getCompanies (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const companies = response.companies
  1. response = client.Companies.get(firm_id, secret)
  2. companies = response['companies']
  3. # Manipulate the count and offset parameters to paginate
  4. # companies and retrieve all available data
  5. while len (companies) < response[' total_companies' ]:
  6. response = client.Companies.get(firm_id, secret,
  7. offset= len (companies))
  8. companies.extend(response[ 'companies' ])
  1. response = @client .companies. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # companies and retrieve all available data
  4. response = @client .companies. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_companies = response[ 'companies' ]

Response fields

companies
An array containing the requested companies.
[object]
company_id
Ethos' unique identifier for the company. Like all Ethos identifiers, the company_id is case sensitive
integer
symbol
Unique symbol (ticker) for the company. Like all Ethos identifiers, the symbol is case sensitive
string
cusip
Unique CUSIP number of stock associated with company, if available
string
isin
Unique ISIN number of stock associated with company, if available
string
name
Name of the company
string
classifications
A set of fields describing company classification (sector, industry and peer group)
object
sector
Sector of the company. Sector is the broadest classification that Ethos uses; potential values are Basic Materials, Consumer Goods, Energy, Financial, Food & Beverage, Healthcare, Industrials, Real Estate, Services, Technology & Communications, Transportation, and Utilities
string
industry
Industry of the company. Industry is a narrower classification than sector
string
peer_group
Peer group of the company. Peer group is the narrowest classification that Ethos uses
string
geography
A set of fields describing company geography
object
region
Global region of the company. Possible values are Asia, Europe, North America ex. US, Rest of World, South America, and United States
string
hq_country
Country of company headquarters
string
hq_state
State or province of company headquarters, if available
string
hq_city
City of company headquarters, if available
string
financial
A set of fields describing company financial highlights
object
revenue
Trailing twelve-month revenue
integer
market_value
Market capitalization
integer
market_cap
Market cap category of company. Possible values are small (less than $250M), medium ($250M - $10B) large (more than $10B)
string
net_income
Trailing twelve-month net income
integer
price
Share price of the associated security (delayed 15-minutes). In order to include this in the response, you must set the "include_price" option to "true" in the request.
string
earnings_per_share
Earnings per share
string
return_on_assets
Return on assets
string
return_on_equity
Return on equity
string
net_invested_capital
Total amount of non-financial assets, net of non-financial liabilities
string
dividends_per_share
Sum of declared dividends issued by a company for every ordinary share outstanding
string
net_debt
Short-term debt + long-term debt - cash and cash equivalents
string
cash_and_short_term
Cash and equivalents and short term investments in marketable securities
string
performance
A set of fields describing financial performance (returns) of an associated stock. Please note our terms of use for price and performance data.
object
return_one_day
One-day return of stock price, based on end-of-day prices
string
return_one_week
One-week return of stock price, based on end-of-day prices
string
return_one_month
One-month return of stock price, based on end-of-day prices
string
return_three_months
Three-month return of stock price, based on end-of-day prices
string
return_one_year
One-year return of stock price, based on end-of-day prices
string
return_two_years
Two-year return of stock price, based on end-of-day prices
string
return_three_years
Three-year return of stock price, based on end-of-day prices
string
return_five_years
Five-year return of stock price, based on end-of-day prices
string
executives
A set of fields describing company executives
[object]
name
Executive name
string
title
Executive title
string
is_ceo
Whether or not the executive is CEO of the company
boolean
age
Executive age
integer
pay
Executive compensation for last available year
integer
screens
A set of fields describing whether or not the company fails ESG-related screens
object
advertising
Whether company is involved in advertising as part of its business model.
string
advertising_lite
Whether company generates more than 10% of revenue from advertising.
string
alcohol
Whether company generates significant revenue from the sale of alcohol. This typically means that the company derives more than 1% of its revenue from alcohol-related sales.
string
alcohol_lite
Whether company generates at least 10% of revenue from the sale of alcohol.
string
animal_testing
Whether company has been reported to test on animals.
string
animal_testing_lite
Whether company has been reported to test on animals and generates at least 10% of revenue from activites that involve testing on animals.
string
anti_abortion
Whether company has been reported to lobby against abortion or donate to politicians or groups working to erode female rights.
string
cannabis
Whether company is involved in the cannabis industry as part of its business model.
string
cannabis_lite
Whether company generates at least 10% of revenue from the sale of cannabis.
string
carbon_emissions_intensity
Whether company's carbon emissions intensity is significantly higher than peers. Carbon intensity is measured as (Scope 1 and 2 emissions) / $M revenue. Threshold for failing this screen is emissions intensity greater than 1 standard deviation above peer average.
string
coal
Whether company's primary business model involves thermal coal mining.
string
coal_lite
Whether company's primary business model is thermal coal mining, and company generates at least 10% of revenue from thermal coal mining.
string
contraceptives
Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
string
contraceptives_lite
Whether company derives more than 10% of its revenue from manufacturing or selling contraceptives.
string
deforestation_financing
Whether company is a major financer of deforestation. Defined as providing more than $100M USD to companies involved in deforestation.
string
deforestation_financing_lite
Whether company is a major financer of deforestation. Defined as providing more than $250M USD to companies involved in deforestation.
string
deforestation_supply_chain
Whether company is involved in deforestation in its supply chain and has been rated in the bottom two quintiles (lower 40%) by publicly-available sources.
string
deforestation_supply_chain_lite
Whether company is involved in deforestation in its supply chain and has been rated in the bottom quintile (lower 20%) by publicly-available sources.
string
discrimination_cont
Whether company has been involved in a "severe" or "very severe" controversy related to customer or employee discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
discrimination_cont_lite
Whether company has been involved in a "very severe" controversy related to customer or employee discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
environmental_cont
Whether company has been involved in a "severe" or "very severe" controversy related to the environment over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
environmental_cont_lite
Whether company has been involved in a "very severe" controversy related to the environment over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
factory_farming
Whether company has been reported to use factory farming in its supply chain.
string
factory_farming_lite
Whether company has been reported to use factory farming in its supply chain and generates at least 10% of revenue from activities that involve factory farming.
string
fast_food
Whether company is considered a fast-food company.
string
fast_food_lite
Whether company generates at least 10% of its revenue from fast-food sales.
string
fossil_fuel
Whether company is involved in fossil fuel production or distribution. Includes oil and gas companies, coal companies, and utilities that use fossil fuels.
string
fossil_fuel_lite
Whether company is considered a fossil fuel company and generates at least 10% of revenue from fossil fuel-related activities. Fossil fuel companies include oil and gas, coal, and utilities that use fossil fuels.
string
fur
Whether company produces or sells fur as a part of its business model.
string
fur_lite
Whether company produces or sells fur as a core part of its business model and generates at least 10% of revenue from fur products.
string
gambling
Whether company generates significant revenue from gambling-related activities. This typically means that the company derives more than 1% of its revenue from gambling-related activities.
string
gambling_lite
Whether company generates at least 10% of revenue from gambling-related activities.
string
genetic_engineering
Whether company uses genetic engineering in its product development or other research.
string
genetic_engineering_lite
Whether company uses genetic engineering in its product development or other research, and generates at least 10% of revenue from activities that involve genetic engineering.
string
health_cont
Whether company has been involved in a "severe" or "very severe" controversy related to health and well-being over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
health_cont_lite
Whether company has been involved in a "very severe" controversy related to health and well-being over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
human_trafficking
Whether company has been reported to be involved in human trafficking over the past 5 years, either directly or through its supply chain.
string
interest_based
Whether company offers an interest-based financial product as part of its business model.
string
interest_based_lite
Whether company generates more than 10% of revenue from an interest-based financial product.
string
interest_bearing_debt
Whether company's debt-to-market-cap ratio is greater than 30%.
string
interest_bearing_debt_lite
Whether company's debt-to-market-cap ratio is greater than 33%.
string
interest_bearing_securities
Whether company's ratio of interest-bearing securities to market cap is greater than 30%. This is calculated as (cash and equivalents and short-term investments) / market cap.
string
interest_bearing_securities_lite
Whether company's ratio of interest-bearing securities to market cap is greater than 33%. This is calculated as (cash and equivalents and short-term investments) / market cap.
string
misleading_communication
Whether company has been involved in a "severe" or "very severe" controversy related to misleading communication over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
misleading_communication_lite
Whether company has been involved in a "very severe" controversy related to misleading communication over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
music
Whether company is involved in producing, distributing or selling music as part of its business model.
string
music_lite
Whether company generates more than 10% of revenue from producing, distributing or selling music.
string
no_sbti
Whether company has committed to a "science-based" target to reduce its emissions in line with the Paris Agreement on climate change mitigation. Uses data from the Science-Based Targets Initiative (SBTI).
string
nuclear
Whether company generates nuclear power or provides supplies enabling nuclear power.
string
nuclear_lite
Whether company generates nuclear power or provides supplies enabling nuclear power, and generates at least 10% of revenue from these activities.
string
oil_and_gas
Whether company is involved in oil and gas industries. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.
string
oil_and_gas_lite
Whether company is considered an oil and gas company and generates at least 10% of revenue from oil and gas-related sales. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.
string
opioid_cont
Whether company has been reported to be involved in the opiod crisis in the United States.
string
opioid_cont_lite
Whether company has been reported to be involved in the opiod crisis in the United States, and generated at least 10% of revenue from opioid-related sales.
string
oppressive_cont
Whether company has been involved in a "severe" or "very severe" controversy with an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
oppressive_cont_lite
Whether company has been involved in a "very severe" controversy with an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
pharma_cont
Whether company has been reported to be involved in pharmaceutical-related controversies such as price-gouging or the opioid crisis.
string
pork
Whether company produces or sells pork as part of its business model.
string
pork_lite
Whether company generates at least 10% of revenue from the sale of pork or pork-based products.
string
pornography
Whether a core part of company's business seeks to appeal to a prurient interest in sex or to incite sexual excitement. Includes companies that produce pornographic material as well as companies that feature adult entertainment, such as casinos.
string
pornography_lite
Whether company generates at least 10% of revenue from activities seeking to appeal to a prurient interest in sex or to incite sexual excitement. Includes companies that produce pornographic material as well as companies that feature adult entertainment, such as casinos.
string
predatory_lending
Whether company has been reported to engage in predatory lending.
string
prison_involvement
Whether company is involved in private prisons or immigrant detention. Involvement defined as direct involvement in the operations of a prison or a prison 'harm score' of 11 or higher from the nonprofit organization Worth Rises.
string
prison_involvement_lite
Whether company is involved in private prisons or immigrant detention, defined as direct involvement in the operations of a prison or a prison 'harm score' higher than 13 from the nonprofit organization Worth Rises.
string
privacy_cont
Whether company has been involved in a "severe" or "very severe" controversy related to privacy over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
privacy_cont_lite
Whether company has been involved in a "very severe" controversy related to privacy over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
pro_life
Whether company directly participates in or enables abortion. Direct participation may include manufacturing of abortifacients and health care companies that perform abortions when not required to by law.
string
pro_life_lite
Whether company directly participates in or enables abortion, and generates at least 10% of revenue from activities related to abortion. Participation may include manufacturing of abortifacients and health care companies that perform abortions when not required to by law.
string
russia
Whether company is headquartered in Russia, has significant operations in Russia, or has significant ties (such as a joint venture or major investment) with Russian companies.
string
russia_lite
Whether company generates at least 10% of revenue from activities in Russia, sales to Russia, or sales through partnerships with Russian companies.
string
single_use_plastic
Whether company produces or sells single-use plastic items as part of its business model.
string
single_use_plastic_lite
Whether company produces or sells single-use plastic items as part of its core business model, and generates at least 10% of revenue from selling these items.
string
stem_cell
Whether company performs research on human fetuses or embryos that results in the end of pre-natal life, makes use of tissue derived from abortions, or otherwise violates the dignity of a developing person.
string
stem_cell_lite
Whether company generates more than 10% of revenue from stem cell research or activities that depend on such research. Stem cell research may involve research on human fetuses or embryos that results in the end of pre-natal life, makes use of tissue derived from abortions, or otherwise violates the dignity of a developing person.
string
sugar
Whether company produces or sells sugary products as part of its business model.
string
sugar_lite
Whether company generates at least 10% of revenue from the sale of sugary products.
string
tobacco
Whether company generates significant revenue from tobacco-related sales. This typically means deriving more than 1% of revenue from tobacco-related sales.
string
tobacco_lite
Whether company generates at least 10% of revenue from tobacco products.
string
weapons
Whether company generates significant revenue from weapons-related sales. This typically means deriving more than 1% of revenue from arms sales.
string
weapons_lite
Whether company generates at least 10% of revenue from the sale of weapons.
string
historical_screens
A set of fields describing whether or not the company failed ESG-related screens in previous years
object
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553
  5. "symbol" : "AAPL"
  6. "cusip" : "37833100"
  7. "isin" : "US0378331005"
  8. "name" : "Apple"
  9. "price" : "200.5"
  10. "classifications" : {
  11. "sector" : "Technology & Communications"
  12. "industry" : "Software & Services"
  13. "peer_group" : "Big Tech - Major Diversified"
  14. }
  15. "geography" : {
  16. "region" : "United States"
  17. "hq_country" : "United States"
  18. "hq_state" : "California"
  19. "hq_city" : "Cupertino"
  20. }
  21. "financial" : {
  22. "revenue" : 347155005440
  23. "market_value" : 2457875513344
  24. "market_cap" : "large"
  25. "net_income" : 100555000000
  26. "price" : "168.64"
  27. "earnings_per_share" : "6.015"
  28. "return_on_assets" : "0.2"
  29. "return_on_equity" : "1.46"
  30. "net_invested_capital" : 194730000000
  31. "dividends_per_share" : "0.865"
  32. "net_debt" : 85679000000
  33. "cash_and_short_term" : 63913000000
  34. }
  35. "performance" : {
  36. "return_one_day" : "-2.102473"
  37. "return_one_week" : "-5.29824"
  38. "return_one_month" : "-3.678318"
  39. "return_three_months" : "14.046122"
  40. "return_one_year" : "24.975637"
  41. "return_two_years" : "108.424224"
  42. "return_three_years" : "304.289341"
  43. "return_five_years" : "369.4877506"
  44. }
  45. "executives" : [{
  46. "name" : "Mr. Timothy D. Cook"
  47. "title" : "CEO & Director"
  48. "is_ceo" : true
  49. "age" : 61
  50. "pay" : 16386559
  51. ]}
  52. "screens" : {
  53. "advertising" : pass
  54. "alcohol" : pass
  55. "animal_testing" : pass
  56. "cannabis" : pass
  57. "carbon_emissions_intensity" : pass
  58. "coal" : pass
  59. "contraceptives" : pass
  60. "deforestation_financing" : pass
  61. "deforestation_supply_chain" : pass
  62. "discrimination_cont" : pass
  63. "environmental_cont" : pass
  64. "factory_farming" : pass
  65. "fast_food" : pass
  66. "fossil_fuel" : pass
  67. "fur" : pass
  68. "gambling" : pass
  69. "genetic_engineering" : pass
  70. "health_cont" : pass
  71. "human_trafficking" : fail
  72. "interest_based" : pass
  73. "interest_bearing_debt" : pass
  74. "interest_bearing_securities" : pass
  75. "misleading_communication" : pass
  76. "music" : pass
  77. "no_sbti" : pass
  78. "nuclear" : pass
  79. "oil_and_gas" : pass
  80. "opioid_cont" : pass
  81. "oppressive_cont" : fail
  82. "pork" : pass
  83. "pornography" : pass
  84. "predatory_lending" : pass
  85. "prison_involvement" : pass
  86. "privacy_cont" : fail
  87. "pro_life" : pass
  88. "single_use_plastic" : pass
  89. "stem_cell" : pass
  90. "sugar" : pass
  91. "tobacco" : pass
  92. "weapons" : pass
  93. }
  94. "historical_screens" : {
  95. "2021" : {
  96. "advertising" : pass
  97. "..." : pass
  98. },
  99. "2020" : {
  100. "advertising" : pass
  101. "..." : pass
  102. },
  103. "2019" : {
  104. "advertising" : pass
  105. "..." : pass
  106. },
  107. "2018" : {
  108. "advertising" : pass
  109. "..." : pass
  110. },
  111. "2017" : {
  112. "advertising" : pass
  113. "..." : pass
  114. }
  115. }
  116. }
  117. ],
  118. "paged_companies" : 1 ,
  119. "total_companies" : 1 ,
  120. "request_id" : "28HyTu"
  121. }

/companies/ratings/get

The /companies/ratings/get endpoint allows you to receive ESG Ratings data about one or more Companies.

You must specify at least one Company identifier (symbol, CUSIP or ISIN). Optionally specify the id of a cause you want to retrieve a Rating for. Defaults to all causes on Ethos.

Companies are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data associated with multiple Companies, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_companies response body field.

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An object to be used with the request. You must specify at least one company identifier (symbol, CUSIP or ISIN).
object
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
cause_ids
A list of cause_ids to retrieve company data for. If not specified, ratings for all causes for requested companies will be returned
[integer]
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer

Example request

/companies/ratings/get
  1. curl -X POST https://development.ethosesg.com/companies/ratings/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getCompanyRatings (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const companies = response.companies
  1. response = client.CompanyRatings.get(firm_id, secret)
  2. companies = response['companies']
  3. # Manipulate the count and offset parameters to paginate
  4. # companies and retrieve all available data
  5. while len (companies) < response[' total_companies' ]:
  6. response = client.CompanyRatings.get(firm_id, secret,
  7. offset= len (companies))
  8. companies.extend(response[ 'companies' ])
  1. response = @client .company_ratings. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # companies and retrieve all available data
  4. response = @client .company_ratings. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_companies = response[ 'companies' ]

Response fields

companies
An array containing the requested companies.
[object]
company_id
Ethos' unique identifier for the company. Like all Ethos identifiers, the company_id is case sensitive
integer
symbol
Unique symbol (ticker) for the company. Like all Ethos identifiers, the symbol is case sensitive
string
cusip
Unique CUSIP number of stock associated with company, if available
string
isin
Unique ISIN number of stock associated with company, if available
string
name
Name of the company
string
ratings
A set of fields describing ESG ratings associated with the company
object
cause
Name of the cause for which the company is rated
string
updated_at
Date the rating was last updated
date
score
Score of the rating, from 0 (worst) to 100 (best)
integer
rank
Rank of the rating, compared to all companies
integer
percentile
Percentile of the rating, compared to all companies
integer
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553
  5. "symbol" : "AAPL"
  6. "cusip" : "37833100"
  7. "isin" : "US0378331005"
  8. "name" : "Apple"
  9. "ratings" : [
  10. {
  11. "cause" : "Gender equality"
  12. "updated_at" : "2021-04-15"
  13. "score" : 84.1
  14. "rank" : 119
  15. "percentile" : 0.85
  16. }
  17. ]
  18. }
  19. ],
  20. "paged_companies" : 1 ,
  21. "total_companies" : 1 ,
  22. "request_id" : "28HyTu"
  23. }

/companies/metrics/get

The /companies/metrics/get endpoint allows you to receive ESG Metrics data about one or more Companies.

You must specify at least one Company identifier (symbol, CUSIP or ISIN). Optionally specify the id of a Metric you want to retrieve data for. Defaults to all Metrics on Ethos.

Companies are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data associated with multiple Companies, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_companies response body field.

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An object to be used with the request. You must specify at least one company identifier (symbol, CUSIP or ISIN).
object
symbols
A list of company symbols (tickers) to retrieve company data for
[string]
cusips
A list of cusip numbers to retrieve company data for
[string]
isins
A list of ISIN numbers to retrieve company data for
[string]
metric_ids
A list of metric_ids to retrieve company data for. If not specified, all metrics for requested companies will be returned
[integer]
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer

Example request

/companies/metrics/get
  1. curl -X POST https://development.ethosesg.com/companies/metrics/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getCompanyMetrics (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const companies = response.companies
  1. response = client.CompanyMetrics.get(firm_id, secret)
  2. companies = response['companies']
  3. # Manipulate the count and offset parameters to paginate
  4. # companies and retrieve all available data
  5. while len (companies) < response[' total_companies' ]:
  6. response = client.CompanyMetrics.get(firm_id, secret,
  7. offset= len (companies))
  8. companies.extend(response[ 'companies' ])
  1. response = @client .company_metrics. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # companies and retrieve all available data
  4. response = @client .company_metrics. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_companies = response[ 'companies' ]

Response fields

companies
An array containing the requested companies.
[object]
company_id
Ethos' unique identifier for the company. Like all Ethos identifiers, the company_id is case sensitive
integer
symbol
Unique symbol (ticker) for the company. Like all Ethos identifiers, the symbol is case sensitive
string
cusip
Unique CUSIP number of stock associated with company, if available
string
isin
Unique ISIN number of stock associated with company, if available
string
name
Name of the company
string
metrics
A set of fields describing ESG metrics associated with the company
object
name
Name of the metric
string
description
Short description of the metric
string
link
Link to metric source, if available
string
uom
Unit of measure of the metric
string
updated_at
Date that metric data was last updated
date
esg_category
Primary ESG category of the metric (environment, social or governance)
string
score_base
Base score of the metric, measured according to the unit of measure
integer
normalization_scope
Whether the metric is normalized relative to peers, all companies, or not at all
string
score_normalized
Normalized score of the metric (on a 0-100 scale)
integer
peer_value
Whether or not the score is based on an average of its peer group. Ethos uses peer averages when no data is available for a company
boolean
paged_companies
Number of paged companies returned
integer
total_companies
Number of total companies available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "companies" : [
  3. {
  4. "company_id" : 553
  5. "symbol" : "AAPL"
  6. "cusip" : "37833100"
  7. "isin" : "US0378331005"
  8. "name" : "Apple"
  9. "metrics" : [
  10. {
  11. "name" : "Advertising fines and violations"
  12. "description" : "Sum of fines incurred over the past four years from the Federal Trade Commission, related to advertising"
  13. "link" : "https://www.goodjobsfirst.org/violation-tracker"
  14. "uom" : "$ fines"
  15. "updated_at" : "2021-04-15"
  16. "esg_category" : "social"
  17. "score_base" : 113000000
  18. "score_normalized" : 0
  19. "peer_value" : false
  20. }
  21. ]
  22. }
  23. ],
  24. "paged_companies" : 1 ,
  25. "total_companies" : 1 ,
  26. "request_id" : "28HyTu"
  27. }

Fund endpoints

Retrieve current data on one or more funds, including fund information, classification, ESG screens, ratings and metrics.
In this section

/funds/get

The /funds/get endpoint allows you to receive data about one or more Funds, including classification, expense ratio and AUM, and screens (e.g., whether the fund holds fossil fuel, gambling, nuclear or other types of companies).

Funds are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data associated with multiple Funds, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_funds response body field.

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
symbols
A list of fund symbols (tickers) to retrieve fund data for
[string]
cusips
A list of cusip numbers to retrieve fund data for
[string]
isins
A list of ISIN numbers to retrieve fund data for
[string]
include_price
Whether or not to include price data (delayed 15-minutes) in the returned information
[true/false]
count
The number of companies to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of companies to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/funds/get
  1. curl -X POST https://development.ethosesg.com/funds/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getFunds (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const funds = response.funds
  1. response = client.Funds.get(firm_id, secret)
  2. funds = response['funds']
  3. # Manipulate the count and offset parameters to paginate
  4. # funds and retrieve all available data
  5. while len (funds) < response[' total_funds' ]:
  6. response = client.Funds.get(firm_id, secret,
  7. offset= len (funds))
  8. funds.extend(response[ 'funds' ])
  1. response = @client .funds. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # funds and retrieve all available data
  4. response = @client .funds. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_funds = response[ 'funds' ]

Response fields

funds
An array containing the requested funds.
[object]
fund_id
Ethos' unique identifier for the fund. Like all Ethos identifiers, the fund_id is case sensitive
integer
symbol
Unique symbol (ticker) for the fund. Like all Ethos identifiers, the symbol is case sensitive
string
cusip
Unique CUSIP number of security associated with fund, if available
string
isin
Unique ISIN number of security associated with fund, if available
string
name
Name of the fund
string
price
Share price of the associated security (delayed 15-minutes)
string
classifications
A set of fields describing fund classifications
object
fund_type
Type of fund (ETF, Mutual Fund, or Index)
string
asset_class
Asset class of the fund
string
category
Fund category. More detailed classification than asset class
string
style
Morningstar style of the fund
object
fund_family
Fund family
object
financial
A set of fields basic financial attributes of the fund
object
expense_ratio
Net expense ratio of the fund
string
aum
Total assets under management at the fund
string
screens
A set of fields describing percent of fund holdings that fail ESG-related screens
object
advertising
Percent of fund holdings that fail company screen: Whether company is involved in advertising as part of its business model.
string
advertising_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from advertising.
string
alcohol
Percent of fund holdings that fail company screen: Whether company generates significant revenue from the sale of alcohol. This typically means that the company derives more than 1% of its revenue from alcohol-related sales.
string
alcohol_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of alcohol.
string
animal_testing
Percent of fund holdings that fail company screen: Whether company has been reported to test on animals.
string
animal_testing_lite
Percent of fund holdings that fail company screen: Whether company has been reported to test on animals and generates at least 10% of revenue from activites that involve testing on animals.
string
anti_abortion
Percent of fund holdings that fail company screen: Whether company has been reported to lobby against abortion or donate to politicians or groups working to erode female rights.
string
cannabis
Percent of fund holdings that fail company screen: Whether company is involved in the cannabis industry as part of its business model.
string
cannabis_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of cannabis.
string
carbon_emissions_intensity
Percent of fund holdings that fail company screen: Whether company's carbon emissions intensity is significantly higher than peers. Carbon intensity is measured as (Scope 1 and 2 emissions) / $M revenue. Threshold for failing this screen is emissions intensity greater than 1 standard deviation above peer average.
string
coal
Percent of fund holdings that fail company screen: Whether company's primary business model involves thermal coal mining.
string
coal_lite
Percent of fund holdings that fail company screen: Whether company's primary business model is thermal coal mining, and company generates at least 10% of revenue from thermal coal mining.
string
contraceptives
Percent of fund holdings that fail company screen: Whether company manufactures contraceptives or derives significant revenue from selling contraceptives.
string
contraceptives_lite
Percent of fund holdings that fail company screen: Whether company derives more than 10% of its revenue from manufacturing or selling contraceptives.
string
deforestation_financing
Percent of fund holdings that fail company screen: Whether company is a major financer of deforestation. Defined as providing more than $100M USD to companies involved in deforestation.
string
deforestation_financing_lite
Percent of fund holdings that fail company screen: Whether company is a major financer of deforestation. Defined as providing more than $250M USD to companies involved in deforestation.
string
deforestation_supply_chain
Percent of fund holdings that fail company screen: Whether company is involved in deforestation in its supply chain and has been rated in the bottom two quintiles (lower 40%) by publicly-available sources.
string
deforestation_supply_chain_lite
Percent of fund holdings that fail company screen: Whether company is involved in deforestation in its supply chain and has been rated in the bottom quintile (lower 20%) by publicly-available sources.
string
discrimination_cont
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to customer or employee discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
discrimination_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy related to customer or employee discrimination over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
environmental_cont
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to the environment over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
environmental_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy related to the environment over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
factory_farming
Percent of fund holdings that fail company screen: Whether company has been reported to use factory farming in its supply chain.
string
factory_farming_lite
Percent of fund holdings that fail company screen: Whether company has been reported to use factory farming in its supply chain and generates at least 10% of revenue from activities that involve factory farming.
string
fast_food
Percent of fund holdings that fail company screen: Whether company is considered a fast-food company.
string
fast_food_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of its revenue from fast-food sales.
string
fossil_fuel
Percent of fund holdings that fail company screen: Whether company is involved in fossil fuel production or distribution. Includes oil and gas companies, coal companies, and utilities that use fossil fuels.
string
fossil_fuel_lite
Percent of fund holdings that fail company screen: Whether company is considered a fossil fuel company and generates at least 10% of revenue from fossil fuel-related activities. Fossil fuel companies include oil and gas, coal, and utilities that use fossil fuels.
string
fur
Percent of fund holdings that fail company screen: Whether company produces or sells fur as a part of its business model.
string
fur_lite
Percent of fund holdings that fail company screen: Whether company produces or sells fur as a core part of its business model and generates at least 10% of revenue from fur products.
string
gambling
Percent of fund holdings that fail company screen: Whether company generates significant revenue from gambling-related activities. This typically means that the company derives more than 1% of its revenue from gambling-related activities.
string
gambling_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from gambling-related activities.
string
genetic_engineering
Percent of fund holdings that fail company screen: Whether company uses genetic engineering in its product development or other research.
string
genetic_engineering_lite
Percent of fund holdings that fail company screen: Whether company uses genetic engineering in its product development or other research, and generates at least 10% of revenue from activities that involve genetic engineering.
string
health_cont
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to health and well-being over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
health_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy related to health and well-being over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
human_trafficking
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in human trafficking over the past 5 years, either directly or through its supply chain.
string
interest_based
Percent of fund holdings that fail company screen: Whether company offers an interest-based financial product as part of its business model.
string
interest_based_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from an interest-based financial product.
string
interest_bearing_debt
Percent of fund holdings that fail company screen: Whether company's debt-to-market-cap ratio is greater than 30%.
string
interest_bearing_debt_lite
Percent of fund holdings that fail company screen: Whether company's debt-to-market-cap ratio is greater than 33%.
string
interest_bearing_securities
Percent of fund holdings that fail company screen: Whether company's ratio of interest-bearing securities to market cap is greater than 30%. This is calculated as (cash and equivalents and short-term investments) / market cap.
string
interest_bearing_securities_lite
Percent of fund holdings that fail company screen: Whether company's ratio of interest-bearing securities to market cap is greater than 33%. This is calculated as (cash and equivalents and short-term investments) / market cap.
string
misleading_communication
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to misleading communication over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
misleading_communication_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy related to misleading communication over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
music
Percent of fund holdings that fail company screen: Whether company is involved in producing, distributing or selling music as part of its business model.
string
music_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from producing, distributing or selling music.
string
no_sbti
Percent of fund holdings that fail company screen: Whether company has committed to a "science-based" target to reduce its emissions in line with the Paris Agreement on climate change mitigation. Uses data from the Science-Based Targets Initiative (SBTI).
string
nuclear
Percent of fund holdings that fail company screen: Whether company generates nuclear power or provides supplies enabling nuclear power.
string
nuclear_lite
Percent of fund holdings that fail company screen: Whether company generates nuclear power or provides supplies enabling nuclear power, and generates at least 10% of revenue from these activities.
string
oil_and_gas
Percent of fund holdings that fail company screen: Whether company is involved in oil and gas industries. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.
string
oil_and_gas_lite
Percent of fund holdings that fail company screen: Whether company is considered an oil and gas company and generates at least 10% of revenue from oil and gas-related sales. Includes companies involved in the exploration, production, distribution, or marketing of oil and gas.
string
opioid_cont
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in the opiod crisis in the United States.
string
opioid_cont_lite
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in the opiod crisis in the United States, and generated at least 10% of revenue from opioid-related sales.
string
oppressive_cont
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy with an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
oppressive_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy with an oppressive government over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
pharma_cont
Percent of fund holdings that fail company screen: Whether company has been reported to be involved in pharmaceutical-related controversies such as price-gouging or the opioid crisis.
string
pork
Percent of fund holdings that fail company screen: Whether company produces or sells pork as part of its business model.
string
pork_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of pork or pork-based products.
string
pornography
Percent of fund holdings that fail company screen: Whether a core part of company's business seeks to appeal to a prurient interest in sex or to incite sexual excitement. Includes companies that produce pornographic material as well as companies that feature adult entertainment, such as casinos.
string
pornography_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from activities seeking to appeal to a prurient interest in sex or to incite sexual excitement. Includes companies that produce pornographic material as well as companies that feature adult entertainment, such as casinos.
string
predatory_lending
Percent of fund holdings that fail company screen: Whether company has been reported to engage in predatory lending.
string
prison_involvement
Percent of fund holdings that fail company screen: Whether company is involved in private prisons or immigrant detention. Involvement defined as direct involvement in the operations of a prison or a prison 'harm score' of 11 or higher from the nonprofit organization Worth Rises.
string
prison_involvement_lite
Percent of fund holdings that fail company screen: Whether company is involved in private prisons or immigrant detention, defined as direct involvement in the operations of a prison or a prison 'harm score' higher than 13 from the nonprofit organization Worth Rises.
string
privacy_cont
Percent of fund holdings that fail company screen: Whether company has been involved in a "severe" or "very severe" controversy related to privacy over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
privacy_cont_lite
Percent of fund holdings that fail company screen: Whether company has been involved in a "very severe" controversy related to privacy over the past 5 years, based on publicly-available media reports. Ethos defines controversy severity from "low" to "very severe".
string
pro_life
Percent of fund holdings that fail company screen: Whether company directly participates in or enables abortion. Direct participation may include manufacturing of abortifacients and health care companies that perform abortions when not required to by law.
string
pro_life_lite
Percent of fund holdings that fail company screen: Whether company directly participates in or enables abortion, and generates at least 10% of revenue from activities related to abortion. Participation may include manufacturing of abortifacients and health care companies that perform abortions when not required to by law.
string
russia
Percent of fund holdings that fail company screen: Whether company is headquartered in Russia, has significant operations in Russia, or has significant ties (such as a joint venture or major investment) with Russian companies.
string
russia_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from activities in Russia, sales to Russia, or sales through partnerships with Russian companies.
string
single_use_plastic
Percent of fund holdings that fail company screen: Whether company produces or sells single-use plastic items as part of its business model.
string
single_use_plastic_lite
Percent of fund holdings that fail company screen: Whether company produces or sells single-use plastic items as part of its core business model, and generates at least 10% of revenue from selling these items.
string
stem_cell
Percent of fund holdings that fail company screen: Whether company performs research on human fetuses or embryos that results in the end of pre-natal life, makes use of tissue derived from abortions, or otherwise violates the dignity of a developing person.
string
stem_cell_lite
Percent of fund holdings that fail company screen: Whether company generates more than 10% of revenue from stem cell research or activities that depend on such research. Stem cell research may involve research on human fetuses or embryos that results in the end of pre-natal life, makes use of tissue derived from abortions, or otherwise violates the dignity of a developing person.
string
sugar
Percent of fund holdings that fail company screen: Whether company produces or sells sugary products as part of its business model.
string
sugar_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of sugary products.
string
tobacco
Percent of fund holdings that fail company screen: Whether company generates significant revenue from tobacco-related sales. This typically means deriving more than 1% of revenue from tobacco-related sales.
string
tobacco_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from tobacco products.
string
weapons
Percent of fund holdings that fail company screen: Whether company generates significant revenue from weapons-related sales. This typically means deriving more than 1% of revenue from arms sales.
string
weapons_lite
Percent of fund holdings that fail company screen: Whether company generates at least 10% of revenue from the sale of weapons.
string
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "funds" : [
  3. {
  4. "fund_id" : 553
  5. "symbol" : "VEGN"
  6. "cusip" : "26922A 297"
  7. "isin" : "US26922A2978"
  8. "name" : "US Vegan Climate ETF"
  9. "price" : "200.5"
  10. "classifications" : {
  11. "fund_family" : "Technology & Communications"
  12. "industry" : "Software & Services"
  13. "peer_group" : "Big Tech - Major Diversified"
  14. }
  15. "geography" : {
  16. "region" : "United States"
  17. "hq_country" : "United States"
  18. "hq_state" : "California"
  19. "hq_city" : "Cupertino"
  20. }
  21. "market_cap" : "large"
  22. "screens" : {
  23. "abortion" : "2.23%"
  24. "advertising" : "0.74%"
  25. "alcohol" : "0%"
  26. "animal_testing" : "0%"
  27. "cannabis" : "0%"
  28. "carbon_emissions_intensity" : "5.58%"
  29. "coal" : "0%"
  30. "contraceptives" : "0.74%"
  31. "deforestation_financing" : "0.74%"
  32. "deforestation_supply_chain" : "2.23%"
  33. "discrimination_cont" : "12.64%"
  34. "environmental_cont" : "15.61%"
  35. "factory_farming" : "0%"
  36. "fast_food" : "0%"
  37. "fossil_fuel" : "0%"
  38. "fur" : "0%"
  39. "gambling" : "0%"
  40. "genetic_engineering" : "0%"
  41. "health_cont" : "6.32%"
  42. "human_trafficking" : "2.23%"
  43. "interest_based" : "21.93%"
  44. "interest_bearing_debt" : "13.75%"
  45. "interest_bearing_securities" : "8.18%"
  46. "misleading_communication" : "10.04%"
  47. "music" : "0.37%"
  48. "no_sbti" : "72.49%"
  49. "nuclear" : "0%"
  50. "oil_and_gas" : "0%"
  51. "opioid_cont" : "0.37%"
  52. "oppressive_cont" : "3.72%"
  53. "pork" : "0%"
  54. "pornography" : "0%"
  55. "predatory_lending" : "1.12%"
  56. "prison_involvement" : "3.35%"
  57. "privacy_cont" : "5.95%"
  58. "single_use_plastic" : "0.37%"
  59. "stem_cell" : "0%"
  60. "sugar" : "0.37%"
  61. "tobacco" : "0%"
  62. "weapons" : "0%"
  63. }
  64. }
  65. ],
  66. "paged_funds" : 1 ,
  67. "total_funds" : 1 ,
  68. "request_id" : "28HyTu"
  69. }

/funds/ratings/get

The /funds/ratings/get endpoint allows you to receive ESG Ratings data about one or more Funds.

You must specify at least one Fund identifier (symbol, CUSIP or ISIN). Optionally specify the id of a cause you want to retrieve a Rating for. Defaults to all causes on Ethos.

Funds are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data associated with multiple Funds, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_funds response body field.

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An object to be used with the request. You must specify at least one fund identifier (symbol, CUSIP or ISIN).
object
symbols
A list of fund symbols (tickers) to retrieve fund data for
[string]
cusips
A list of cusip numbers to retrieve fund data for
[string]
isins
A list of ISIN numbers to retrieve fund data for
[string]
cause_ids
A list of cause_ids to retrieve fund data for. If not specified, ratings for all causes for requested funds will be returned
[integer]
count
The number of funds to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer

Example request

/funds/get
  1. curl -X POST https://development.ethosesg.com/funds/ratings/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getFundRatings (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const funds = response.funds
  1. response = client.FundRatings.get(firm_id, secret)
  2. funds = response['funds']
  3. # Manipulate the count and offset parameters to paginate
  4. # funds and retrieve all available data
  5. while len (funds) < response[' total_funds' ]:
  6. response = client.FundRatings.get(firm_id, secret,
  7. offset= len (funds))
  8. funds.extend(response[ 'funds' ])
  1. response = @client .fund_ratings. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # funds and retrieve all available data
  4. response = @client .fund_ratings. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_funds = response[ 'funds' ]

Response fields

funds
An array containing the requested funds.
[object]
fund_id
Ethos' unique identifier for the fund. Like all Ethos identifiers, the fund_id is case sensitive
integer
symbol
Unique symbol (ticker) for the fund. Like all Ethos identifiers, the symbol is case sensitive
string
cusip
Unique CUSIP number of security associated with fund, if available
string
isin
Unique ISIN number of security associated with fund, if available
string
name
Name of the fund
string
ratings
A set of fields describing ESG ratings associated with the fund
object
cause
Name of the cause for which the fund is rated
string
updated_at
Date the rating was last updated
date
score
Score of the rating, from 0 (worst) to 100 (best)
integer
rank
Rank of the rating, compared to all funds
integer
percentile
Percentile of the rating, compared to all funds
integer
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "funds" : [
  3. {
  4. "fund_id" : 2858
  5. "symbol" : "VEGN"
  6. "cusip" : "26922A 297"
  7. "isin" : "US26922A2978"
  8. "name" : "US Vegan Climate ETF"
  9. "ratings" : [
  10. {
  11. "cause" : "Gender equality"
  12. "updated_at" : "2021-04-15"
  13. "score" : 88.2
  14. "rank" : 84
  15. "percentile" : 0.92
  16. }
  17. ]
  18. }
  19. ],
  20. "paged_funds" : 1 ,
  21. "total_funds" : 1 ,
  22. "request_id" : "28HyTu"
  23. }

/funds/metrics/get

The /funds/metrics/get endpoint allows you to receive ESG Metrics data about one or more Funds.

You must specify at least one Fund identifier (symbol, CUSIP or ISIN). Optionally specify the id of a Metric you want to retrieve data for. Defaults to all Metrics on Ethos.

Funds are returned in alphabetical order by standard Ethos name. Due to the potentially large amount of data associated with multiple Funds, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_funds response body field.

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An object to be used with the request. You must specify at least one fund identifier (symbol, CUSIP or ISIN).
object
symbols
A list of fund symbols (tickers) to retrieve fund data for
[string]
cusips
A list of cusip numbers to retrieve fund data for
[string]
isins
A list of ISIN numbers to retrieve fund data for
[string]
metric_ids
A list of metric_ids to retrieve fund data for. If not specified, all metrics for requested funds will be returned
[integer]
count
The number of funds to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer

Example request

/funds/metrics/get
  1. curl -X POST https://development.ethosesg.com/funds/metrics/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "symbols": [String],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getFundMetrics (firm_id, secret , {
  3. symbols: [String] ,
  4. count: 100 ,
  5. offset: 0 ,
  6. })
  7. . catch ((err) => {
  8. // handle error
  9. })
  10. const funds = response.funds
  1. response = client.FundMetrics.get(firm_id, secret)
  2. funds = response['funds']
  3. # Manipulate the count and offset parameters to paginate
  4. # funds and retrieve all available data
  5. while len (funds) < response[' total_funds' ]:
  6. response = client.FundMetrics.get(firm_id, secret,
  7. offset= len (funds))
  8. funds.extend(response[ 'funds' ])
  1. response = @client .fund_metrics. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # funds and retrieve all available data
  4. response = @client .fund_metrics. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_funds = response[ 'funds' ]

Response fields

funds
An array containing the requested funds.
[object]
fund_id
Ethos' unique identifier for the fund. Like all Ethos identifiers, the fund_id is case sensitive
integer
symbol
Unique symbol (ticker) for the fund. Like all Ethos identifiers, the symbol is case sensitive
string
cusip
Unique CUSIP number of security associated with fund, if available
string
isin
Unique ISIN number of security associated with fund, if available
string
name
Name of the fund
string
metrics
A set of fields describing ESG metrics associated with the fund
object
name
Name of the metric
string
description
Short description of the metric
string
link
Link to metric source, if available
string
uom
Unit of measure of the metric
string
updated_at
Date that metric data was last updated
date
esg_category
Primary ESG category of the metric (environment, social or governance)
string
score_base
Base score of the metric, measured according to the unit of measure
integer
normalization_scope
Whether the metric is normalized relative to peers, all funds, or not at all
string
score_normalized
Normalized score of the metric (on a 0-100 scale)
integer
paged_funds
Number of paged funds returned
integer
total_funds
Number of total funds available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "funds" : [
  3. {
  4. "fund_id" : 2858
  5. "symbol" : "VEGN"
  6. "cusip" : "26922A 297"
  7. "isin" : "US26922A2978"
  8. "name" : "US Vegan Climate ETF"
  9. "metrics" : [
  10. {
  11. "name" : "Advertising fines and violations"
  12. "description" : "Sum of fines incurred over the past four years from the Federal Trade Commission, related to advertising"
  13. "link" : "https://www.goodjobsfirst.org/violation-tracker"
  14. "uom" : "$ fines"
  15. "updated_at" : "2021-04-15"
  16. "esg_category" : "social"
  17. "score_base" : 42100000
  18. "score_normalized" : 0
  19. }
  20. ]
  21. }
  22. ],
  23. "paged_funds" : 1 ,
  24. "total_funds" : 1 ,
  25. "request_id" : "28HyTu"
  26. }

Cause endpoints

Retrieve a list of causes available on Ethos. Ratings of companies and funds can be scoped to specific causes
In this section

/causes/get

The /causes/get endpoint allows you to receive a list of Causes available on Ethos, with basic information about each Cause.

Causes are returned in alphabetical order by name. There are 45 total Causes available on Ethos; no paging is included in the response.

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
cause_ids
A list of cause_ids to retrieve metric data for
[integer]

Example request

/causes/get
  1. curl -X POST https://development.ethosesg.com/causes/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "cause_ids": [Integer]
  8. }
  9. }'
  1. const response = await client
  2. . getCauses (firm_id, secret , {
  3. cause_ids: [Integer]
  4. })
  5. . catch ((err) => {
  6. // handle error
  7. })
  8. const causes = response.causes
  1. response = client.Causes.get(firm_id, secret)
  2. causes = response['causes']
  3. response = client.Causes.get(firm_id, secret,
  4. offset= len (causes))
  5. causes.extend(response[ 'causes' ])
  1. response = @client .causes. get ( @firm_id , @secret )
  2. total_companies = response[ 'causes' ]

Response fields

causes
An array containing the requested causes.
[object]
cause_id
Ethos' unique identifier for the cause
integer
name
Name of the cause
string
description
Short description of the cause
string
problem
Problem statement of the cause, i.e., the problem the cause seeks to address
string
keywords
Keywords associated with the cause
string
total_causes
Number of total causes available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "causes" : [
  3. {
  4. "cause_id" : 32
  5. "name" : "Sustainable use of water"
  6. "description" : "Promote sustainable management of water everywhere"
  7. "problem" : "Less than 1.2% of all water on earth is available for human use, and the UN projects a 40% shortfall in meeting demand for global water by 2030. More efficient use of water is critical to addressing this shortfall, as well as mitigating the impact of increasing droughts and floods resulting from climate change. Companies play a central role in how water is used, especially in industrial, agricultural, and food industries. Companies can contribute to sustainable water use in several ways, including by reducing water withdrawals, especially in high-stress water regions; setting specific targets for their water use and establishing robust policies for water use and management; engaging with their value chains on sustainable water use; leading on developing and implementing international standards for water use; and setting board and executive compensation incentives to better manage water issues"
  8. "keywords" : "sustainable farming, industrial agriculture, sustainability, access to water, water stress"
  9. }
  10. ],
  11. "total_causes" : 1 ,
  12. "request_id" : "28HyTu"
  13. }

Metric endpoints

Retrieve a list of metrics available on Ethos. Metrics of companies and funds (info above) can be scoped to specific metrics
In this section

/metrics/get

The /metrics/get endpoint allows you to receive a list of Metrics available on Ethos, with basic information about each Metric.

Metrics are returned in alphabetical order by name. Due to the potentially large amount of data associated with multiple Metrics, results are paginated in groups of 100. Manipulate the count and offset parameters in conjunction with the total_metrics response body field.

Request fields

firm_id
Your Ethos API client_id. The firm_id is required and may be provided either in the ETHOS-FIRM-ID header or as part of a request body.
string
secret
Your Ethos API secret. The secret is required and may be provided either in the ETHOS-SECRET header or as part of a request body.
string
options
An optional object to be used with the request. If specified, options must not be null.
object
metric_ids
A list of metric_ids to retrieve metric data for
[integer]
count
The number of metrics to fetch.
Default: 10
Minimum: 1
Maximum: 100
integer
offset
The number of metrics to skip. The default value is 0.
Default: 0
Minimum: 0
integer

Example request

/metrics/get
  1. curl -X POST https://development.ethosesg.com/metrics/get \
  2. -H 'Content-Type: application/json' \
  3. -d '{
  4. "firm_id": String,
  5. "secret": String,
  6. "options": {
  7. "metric_ids": [Integer],
  8. "count": 100,
  9. "offset": 0
  10. }
  11. }'
  1. const response = await client
  2. . getMetrics (firm_id, secret , {
  3. metric_ids: [Integer]
  4. })
  5. . catch ((err) => {
  6. // handle error
  7. })
  8. const metrics = response.metrics
  1. response = client.Metrics.get(firm_id, secret)
  2. metrics = response['metrics']
  3. # Manipulate the count and offset parameters to paginate
  4. # metrics and retrieve all available data
  5. while len (metrics) < response[' total_metrics' ]:
  6. response = client.Metrics.get(firm_id, secret,
  7. offset= len (metrics))
  8. metrics.extend(response[ 'metrics' ])
  1. response = @client .metrics. get ( @firm_id , @secret )
  2. # Manipulate the count and offset parameters to paginate
  3. # metrics and retrieve all available data
  4. response = @client .metrics. get ( @firm_id , @secret , count: 250 , offset: 0 )
  5. total_metrics = response[ 'metrics' ]

Response fields

metrics
An array containing the requested metrics.
[object]
metric_id
Ethos' unique identifier for the metric
integer
name
Name of the metric
string
description
Short description of the metric
string
source
Name of the metric source
string
link
Link to the metric source
string
uom
Unit of measure of the metric
string
updated_at
Date that metric data was last updated
date
esg_category
Primary ESG category of the metric (environment, social or governance)
string
normalization_scope
Whether the metric is normalized relative to peers, all companies, or not at all
string
paged_metrics
Number of paged metrics returned
integer
total_metrics
Number of total metrics available based on the request
integer
request_id
Unique id for the request
string

Example response

API Object
  1. {
  2. "metrics" : [
  3. {
  4. "metric_id" : 224
  5. "name" : "Fines and violations"
  6. "description" : "Sum of fines and violations incurred from US government agencies over the previous four years"
  7. "source" : "Violation Tracker"
  8. "link" : "https://www.goodjobsfirst.org/violation-tracker"
  9. "metric_uom" : "$ fines"
  10. "updated_at" : "2021-04-15"
  11. "esg_category" : "governance"
  12. "normalization_scope" : "all"
  13. }
  14. ],
  15. "paged_metrics" : 1 ,
  16. "total_metrics" : 1 ,
  17. "request_id" : "28HyTu"
  18. }

Errors

We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Ethos-related issues. Error fields will be null if no error has occurred.
In this section

Error schema

error_code
The particular error code. Safe for programmatic use.
string
error_message
A representation of the error code. This may change over time and is not safe for programmatic use.
string
request_id
A unique identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
string

Error codes

INCORRECT_KEYS
Incorrect firm_id or secret sent with the request
string
NO_IDENTIFIER
No identifier passed for company or fund
string
ITEM_NOT_FOUND
Requested company, fund, cause or metric could not be found in the Ethos database
string
OFFSET_TOO_HIGH
No records available with requested offset paramater
string
INTERNAL_SERVER_ERROR
Error caused by internal Ethos problem. Please contact us for support
string