Ethos API

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 client_id and secret. These may be sent either in the request body or in the headers ETHOS-CLIENT-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]
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
market_cap
Market cap category of company. Possible values are small (less than $250M), medium ($250M - $10B) large (more than $10B)
string
screens
A set of fields describing whether or not the company meets ESG-related screens
object
alcohol
Whether company produces or distributes alcohol as its primary business
boolean
bcorp
Whether company is a certified B Corporation or has B Corporation subsidiaries
boolean
customer_fines
Whether company has received customer- or product-related fines from the US government in the last 4 years. Fines tracked by the Violation Tracker of Good Jobs First.
boolean
env_fines
Whether company has received environment-related fines from the US government in the last 4 years. Fines tracked by the Violation Tracker of Good Jobs First.
boolean
fossil_fuel
Whether company is considered a fossil fuel company. Fossil fuel companies include oil and gas, coal, and utilities that use fossil fuels
boolean
gambling
Whether company offers gambling or gambling-related products as its primary business
boolean
nuclear
Whether company generates nuclear power or provides supplies enabling nuclear power
boolean
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' higher than 11 from the nonprofit organization Worth Rises
boolean
tobacco
Whether company is considered a tobacco company. Tobacco companies are any that derive more than 15% of total revenue from tobacco-related sales
boolean
weapons
Whether company is considered a weapons company. Weapons companies are any that derive at least $1B revenue or 10% of total revenue from arms sales
boolean
worker_fines
Whether company has received worker-related fines from the US government in the last 4 years. Fines tracked by the Violation Tracker of Good Jobs First
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. "classifications" : {
  10. "sector" : "Technology & Communications"
  11. "industry" : "Software & Services"
  12. "peer_group" : "Big Tech - Major Diversified"
  13. }
  14. "geography" : {
  15. "region" : "United States"
  16. "hq_country" : "United States"
  17. "hq_state" : "California"
  18. "hq_city" : "Cupertino"
  19. }
  20. "market_cap" : "large"
  21. "screens" : {
  22. "alcohol" : false
  23. "bcorp" : false
  24. "customer_fines" : true
  25. "env_fines" : false
  26. "fossil_fuel" : false
  27. "gambling" : false
  28. "nuclear" : false
  29. "prison_involvement" : false
  30. "tobacco" : false
  31. "weapons" : false
  32. "worker_fines" : false
  33. }
  34. }
  35. ],
  36. "paged_companies" : 1 ,
  37. "total_companies" : 1 ,
  38. "request_id" : "28HyTu"
  39. }

/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]
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
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 meet ESG-related screens
object
alcohol
Percent of fund holdings that produce or distribute alcohol as their primary business
boolean
bcorp
Percent of fund holdings that are certified B Corporations or have B Corporation subsidiaries
boolean
customer_fines
Percent of fund holdings that have received customer- or product-related fines from the US government in the last 4 years. Fines tracked by the Violation Tracker of Good Jobs First.
boolean
env_fines
Percent of fund holdings that have received environment-related fines from the US government in the last 4 years. Fines tracked by the Violation Tracker of Good Jobs First.
boolean
fossil_fuel
Percent of fund holdings that are considered fossil fuel companies. Fossil fuel companies include oil and gas, coal, and utilities that use fossil fuels
boolean
gambling
Percent of fund holdings that offer gambling or gambling-related products as their primary business
boolean
nuclear
Percent of fund holdings that generate nuclear power or provide supplies enabling nuclear power
boolean
prison_involvement
Percent of fund holdings that are involved in private prisons or immigrant detention. Involvement defined as direct involvement in the operations of a prison or a prison 'harm score' higher than 11 from the nonprofit organization Worth Rises
boolean
tobacco
Percent of fund holdings that are considered tobacco companies. Tobacco companies are any that derive more than 15% of total revenue from tobacco-related sales
boolean
weapons
Percent of fund holdings that are considered weapons companies. Weapons companies are any that derive at least $1B revenue or 10% of total revenue from arms sales
boolean
worker_fines
Percent of fund holdings that have received worker-related fines from the US government in the last 4 years. Fines tracked by the Violation Tracker of Good Jobs First
boolean
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. "classifications" : {
  10. "fund_family" : "Technology & Communications"
  11. "industry" : "Software & Services"
  12. "peer_group" : "Big Tech - Major Diversified"
  13. }
  14. "geography" : {
  15. "region" : "United States"
  16. "hq_country" : "United States"
  17. "hq_state" : "California"
  18. "hq_city" : "Cupertino"
  19. }
  20. "market_cap" : "large"
  21. "screens" : {
  22. "alcohol" : 0%
  23. "bcorp" : 0%
  24. "customer_fines" : 16%
  25. "env_fines" : 7%
  26. "fossil_fuel" : 0%
  27. "gambling" : 0%
  28. "nuclear" : 0%
  29. "prison_involvement" : 1%
  30. "tobacco" : 0%
  31. "weapons" : 0%
  32. "worker_fines" : 41%
  33. }
  34. }
  35. ],
  36. "paged_funds" : 1 ,
  37. "total_funds" : 1 ,
  38. "request_id" : "28HyTu"
  39. }

/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