Better ESG data for your analysis or application
Endpoint schema
Companies
Retrieve company-level information, ratings and metrics
Retrieve the list of available companies
Funds
Retrieve fund-level information, ratings and metrics
Retrieve the list of available funds
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
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
Example request
- curl -X POST https://development.ethosesg.com/companies/get \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "symbols": [String],
- "count": 100,
- "offset": 0
- }
- }'
- const response = await client
- . getCompanies (firm_id, secret , {
- symbols: [String] ,
- count: 100 ,
- offset: 0 ,
- })
- . catch ((err) => {
- // handle error
- })
- const companies = response.companies
- response = client.Companies.get(firm_id, secret)
- companies = response['companies']
- # Manipulate the count and offset parameters to paginate
- # companies and retrieve all available data
- while len (companies) < response[' total_companies' ]:
- response = client.Companies.get(firm_id, secret,
- offset= len (companies))
- companies.extend(response[ 'companies' ])
- response = @client .companies. get ( @firm_id , @secret )
- # Manipulate the count and offset parameters to paginate
- # companies and retrieve all available data
- response = @client .companies. get ( @firm_id , @secret , count: 250 , offset: 0 )
- total_companies = response[ 'companies' ]
Response fields
Example response
- {
- "companies" : [
- {
- "company_id" : 553
- "symbol" : "AAPL"
- "cusip" : "37833100"
- "isin" : "US0378331005"
- "name" : "Apple"
- "updated_at" : "2022-06-19"
- "price" : "200.5"
- "classifications" : {
- "sector" : "Technology & Communications"
- "industry" : "Software & Services"
- "peer_group" : "Big Tech - Major Diversified"
- }
- "geography" : {
- "region" : "United States"
- "hq_country" : "United States"
- "hq_state" : "California"
- "hq_city" : "Cupertino"
- }
- "financial" : {
- "revenue" : 347155005440
- "market_value" : 2457875513344
- "market_cap" : "mega"
- "net_income" : 100555000000
- "price" : "168.64"
- "earnings_per_share" : "6.015"
- "return_on_assets" : "0.2"
- "return_on_equity" : "1.46"
- "net_invested_capital" : 194730000000
- "dividends_per_share" : "0.865"
- "net_debt" : 85679000000
- "cash_and_short_term" : 63913000000
- }
- "performance" : {
- "return_one_day" : "-2.102473"
- "return_one_week" : "-5.29824"
- "return_one_month" : "-3.678318"
- "return_three_months" : "14.046122"
- "return_one_year" : "24.975637"
- "return_two_years" : "108.424224"
- "return_three_years" : "304.289341"
- "return_five_years" : "369.4877506"
- }
- "executives" : [{
- "name" : "Mr. Timothy D. Cook"
- "title" : "CEO & Director"
- "is_ceo" : true
- "age" : 61
- "pay" : 16386559
- ]}
- "screens" : {
- "advertising" : pass
- "alcohol" : pass
- "animal_testing" : pass
- "cannabis" : pass
- "carbon_emissions_intensity" : pass
- "coal" : pass
- "contraceptives" : pass
- "deforestation_financing" : pass
- "deforestation_supply_chain" : pass
- "discrimination_cont" : pass
- "environmental_cont" : pass
- "factory_farming" : pass
- "fast_food" : pass
- "fossil_fuel" : pass
- "fur" : pass
- "gambling" : pass
- "genetic_engineering" : pass
- "health_cont" : pass
- "human_trafficking" : fail
- "interest_based" : pass
- "interest_bearing_debt" : pass
- "interest_bearing_securities" : pass
- "misleading_communication" : pass
- "music" : pass
- "no_sbti" : pass
- "nuclear" : pass
- "oil_and_gas" : pass
- "opioid_cont" : pass
- "oppressive_cont" : fail
- "pork" : pass
- "pornography" : pass
- "predatory_lending" : pass
- "prison_involvement" : pass
- "privacy_cont" : fail
- "pro_life" : pass
- "single_use_plastic" : pass
- "stem_cell" : pass
- "sugar" : pass
- "tobacco" : pass
- "weapons" : pass
- }
- "historical_screens" : {
- "2021" : {
- "advertising" : pass
- "..." : pass
- },
- "2020" : {
- "advertising" : pass
- "..." : pass
- },
- "2019" : {
- "advertising" : pass
- "..." : pass
- },
- "2018" : {
- "advertising" : pass
- "..." : pass
- },
- "2017" : {
- "advertising" : pass
- "..." : pass
- }
- }
- }
- ],
- "paged_companies" : 1 ,
- "total_companies" : 1 ,
- "request_id" : "28HyTu"
- }
/companies/screens/get
The /companies/screens/get endpoint allows you to receive ESG Screens data about one or more Companies.
You must specify at least one Company identifier (symbol, CUSIP, ISIN or UUID).
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
Example request
- curl -X POST https://development.ethosesg.com/companies/get \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "symbols": [String],
- "count": 100,
- "offset": 0
- }
- }'
- const response = await client
- . getCompanyScreens (firm_id, secret , {
- symbols: [String] ,
- count: 100 ,
- offset: 0 ,
- })
- . catch ((err) => {
- // handle error
- })
- const companies = response.companies
- response = client.CompanyScreens.get(firm_id, secret)
- companies = response['companies']
- # Manipulate the count and offset parameters to paginate
- # companies and retrieve all available data
- while len (companies) < response[' total_companies' ]:
- response = client.CompanyScreens.get(firm_id, secret,
- offset= len (companies))
- companies.extend(response[ 'companies' ])
- response = @client .company_screen_exclusions. get ( @firm_id , @secret )
- # Manipulate the count and offset parameters to paginate
- # companies and retrieve all available data
- response = @client .company_screen_exclusions. get ( @firm_id , @secret , count: 250 , offset: 0 )
- total_companies = response[ 'companies' ]
Response fields
Example response
- {
- "companies" : [
- {
- "company_id" : 553
- "symbol" : "AAPL"
- "cusip" : "37833100"
- "isin" : "US0378331005"
- "name" : "Apple"
- "updated_at" : "2022-06-19"
- "screens" : {
- "advertising" : {
- "pass" : "false"
- "revenue_percent" : 0.157
- "updated_at" : "2022-06-19"
- }
- "alcohol" : {
- "pass" : "true"
- "revenue_percent" : 0
- "updated_at" : "2022-06-19"
- }
- "animal_testing" : {
- "pass" : "true"
- "revenue_percent" : 0
- "updated_at" : "2022-06-19"
- }
- "cannabis" : {
- "pass" : "true"
- "revenue_percent" : 0
- "updated_at" : "2022-06-19"
- }
- "carbon_emissions_intensity" : {
- "pass" : "true"
- "revenue_percent" : 0
- "updated_at" : "2022-06-19"
- }
- "..." : {
- "pass" : "true"
- "revenue_percent" : 0
- "updated_at" : "2022-06-19"
- }
- }
- "historical_screens" : {
- "2021" : {
- "advertising" : {
- "pass" : "false"
- "alcohol" : {
- "pass" : "true"
- "..." : {
- "pass" : "true"
- },
- "2020" : {
- "advertising" : {
- "pass" : "false"
- "alcohol" : {
- "pass" : "true"
- "..." : {
- "pass" : "true"
- },
- "2019" : {
- "advertising" : {
- "pass" : "false"
- "alcohol" : {
- "pass" : "true"
- "..." : {
- "pass" : "true"
- },
- "2018" : {
- "advertising" : {
- "pass" : "false"
- "alcohol" : {
- "pass" : "true"
- "..." : {
- "pass" : "true"
- },
- "2017" : {
- "advertising" : {
- "pass" : "false"
- "alcohol" : {
- "pass" : "true"
- "..." : {
- "pass" : "true"
- }
- }
- }
- ],
- "paged_companies" : 1 ,
- "total_companies" : 1 ,
- "request_id" : "28HyTu"
- }
/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, ISIN or UUID). Optionally specify the id of a cause you want to retrieve a Rating for. Defaults to returning ratings for all causes on Ethos and all "Impact Personas" of your clients and leads.
An "Impact Persona" is a combination of causes based on what a client or lead selects in their Impact Assessment. It can be a single cause or many causes that are important to a client.
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
Example request
- curl -X POST https://development.ethosesg.com/companies/ratings/get \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "symbols": [String],
- "count": 100,
- "offset": 0
- }
- }'
- const response = await client
- . getCompanyRatings (firm_id, secret , {
- symbols: [String] ,
- count: 100 ,
- offset: 0 ,
- })
- . catch ((err) => {
- // handle error
- })
- const companies = response.companies
- response = client.CompanyRatings.get(firm_id, secret)
- companies = response['companies']
- # Manipulate the count and offset parameters to paginate
- # companies and retrieve all available data
- while len (companies) < response[' total_companies' ]:
- response = client.CompanyRatings.get(firm_id, secret,
- offset= len (companies))
- companies.extend(response[ 'companies' ])
- response = @client .company_ratings. get ( @firm_id , @secret )
- # Manipulate the count and offset parameters to paginate
- # companies and retrieve all available data
- response = @client .company_ratings. get ( @firm_id , @secret , count: 250 , offset: 0 )
- total_companies = response[ 'companies' ]
Response fields
Example response
- {
- "companies" : [
- {
- "company_id" : 553
- "symbol" : "AAPL"
- "cusip" : "37833100"
- "isin" : "US0378331005"
- "name" : "Apple"
- "updated_at" : "2022-06-19"
- "ratings" : [
- {
- "cause" : "Gender equality"
- "cause_id" : "37"
- "updated_at" : "2022-06-19"
- "score" : 84.1
- "rank" : 119
- "percentile" : 0.85
- }
- ]
- }
- ],
- "paged_companies" : 1 ,
- "total_companies" : 1 ,
- "request_id" : "28HyTu"
- }
/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, ISIN or UUID). 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 very large amount of data associated with multiple Companies, results are paginated in groups of max 10. Manipulate the count and offset parameters in conjunction with the total_companies response body field.
Request fields
Example request
- curl -X POST https://development.ethosesg.com/companies/metrics/get \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "symbols": [String],
- "count": 100,
- "offset": 0
- }
- }'
- const response = await client
- . getCompanyMetrics (firm_id, secret , {
- symbols: [String] ,
- count: 100 ,
- offset: 0 ,
- })
- . catch ((err) => {
- // handle error
- })
- const companies = response.companies
- response = client.CompanyMetrics.get(firm_id, secret)
- companies = response['companies']
- # Manipulate the count and offset parameters to paginate
- # companies and retrieve all available data
- while len (companies) < response[' total_companies' ]:
- response = client.CompanyMetrics.get(firm_id, secret,
- offset= len (companies))
- companies.extend(response[ 'companies' ])
- response = @client .company_metrics. get ( @firm_id , @secret )
- # Manipulate the count and offset parameters to paginate
- # companies and retrieve all available data
- response = @client .company_metrics. get ( @firm_id , @secret , count: 250 , offset: 0 )
- total_companies = response[ 'companies' ]
Response fields
Example response
- {
- "companies" : [
- {
- "company_id" : 553
- "symbol" : "AAPL"
- "cusip" : "37833100"
- "isin" : "US0378331005"
- "name" : "Apple"
- "updated_at" : "2022-06-19"
- "metrics" : [
- {
- "name" : "Advertising fines and violations"
- "metric_id" : "224"
- "description" : "Sum of fines incurred over the past four years from the Federal Trade Commission, related to advertising"
- "link" : "https://www.goodjobsfirst.org/violation-tracker"
- "uom" : "$ fines"
- "updated_at" : "2022-06-30"
- "esg_category" : "social"
- "score_base" : 113000000
- "score_normalized" : 0
- "peer_value" : false
- }
- ]
- }
- ],
- "paged_companies" : 1 ,
- "total_companies" : 1 ,
- "request_id" : "28HyTu"
- }
/companies/list
The /companies/list endpoint allows you to receive a list of Companies available on Ethos, with basic identifiers for each Company.
Companies are returned in alphabetical order by name. No paging is included in the response.
If you would like more detailed information about a company, use the /companies/get endpoint below.
Request fields
Example request
- curl -X POST https://development.ethosesg.com/companies/list \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- }'
- const response = await client
- . listCompanies (firm_id, secret )
- . catch ((err) => {
- // handle error
- })
- const companies = response.companies
- response = client.Companies.list(firm_id, secret)
- companies = response['companies']
- response = @client .companies. list ( @firm_id , @secret )
- total_companies = response[ 'companies' ]
Response fields
Example response
- {
- "companies" : [
- {
- "company_id" : 553
- "symbol" : "AAPL"
- "cusip" : "37833100"
- "isin" : "US0378331005"
- "name" : "Apple"
- "updated_at" : "2022-06-19"
- }
- ],
- "total_companies" : 1 ,
- "request_id" : "28HyTu"
- }
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
Example request
- curl -X POST https://development.ethosesg.com/funds/get \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "symbols": [String],
- "count": 100,
- "offset": 0
- }
- }'
- const response = await client
- . getFunds (firm_id, secret , {
- symbols: [String] ,
- count: 100 ,
- offset: 0 ,
- })
- . catch ((err) => {
- // handle error
- })
- const funds = response.funds
- response = client.Funds.get(firm_id, secret)
- funds = response['funds']
- # Manipulate the count and offset parameters to paginate
- # funds and retrieve all available data
- while len (funds) < response[' total_funds' ]:
- response = client.Funds.get(firm_id, secret,
- offset= len (funds))
- funds.extend(response[ 'funds' ])
- response = @client .funds. get ( @firm_id , @secret )
- # Manipulate the count and offset parameters to paginate
- # funds and retrieve all available data
- response = @client .funds. get ( @firm_id , @secret , count: 250 , offset: 0 )
- total_funds = response[ 'funds' ]
Response fields
Example response
- {
- "funds" : [
- {
- "fund_id" : 553
- "symbol" : "VEGN"
- "cusip" : "26922A 297"
- "isin" : "US26922A2978"
- "name" : "US Vegan Climate ETF"
- "updated_at" : "2022-06-19"
- "price" : "200.5"
- "classifications" : {
- "fund_family" : "Technology & Communications"
- "industry" : "Software & Services"
- "peer_group" : "Big Tech - Major Diversified"
- }
- "geography" : {
- "region" : "United States"
- "hq_country" : "United States"
- "hq_state" : "California"
- "hq_city" : "Cupertino"
- }
- "market_cap" : "large"
- "screens" : {
- "abortion" : "2.23%"
- "advertising" : "0.74%"
- "alcohol" : "0%"
- "animal_testing" : "0%"
- "cannabis" : "0%"
- "carbon_emissions_intensity" : "5.58%"
- "coal" : "0%"
- "contraceptives" : "0.74%"
- "deforestation_financing" : "0.74%"
- "deforestation_supply_chain" : "2.23%"
- "discrimination_cont" : "12.64%"
- "environmental_cont" : "15.61%"
- "factory_farming" : "0%"
- "fast_food" : "0%"
- "fossil_fuel" : "0%"
- "fur" : "0%"
- "gambling" : "0%"
- "genetic_engineering" : "0%"
- "health_cont" : "6.32%"
- "human_trafficking" : "2.23%"
- "interest_based" : "21.93%"
- "interest_bearing_debt" : "13.75%"
- "interest_bearing_securities" : "8.18%"
- "misleading_communication" : "10.04%"
- "music" : "0.37%"
- "no_sbti" : "72.49%"
- "nuclear" : "0%"
- "oil_and_gas" : "0%"
- "opioid_cont" : "0.37%"
- "oppressive_cont" : "3.72%"
- "pork" : "0%"
- "pornography" : "0%"
- "predatory_lending" : "1.12%"
- "prison_involvement" : "3.35%"
- "privacy_cont" : "5.95%"
- "single_use_plastic" : "0.37%"
- "stem_cell" : "0%"
- "sugar" : "0.37%"
- "tobacco" : "0%"
- "weapons" : "0%"
- }
- }
- ],
- "paged_funds" : 1 ,
- "total_funds" : 1 ,
- "request_id" : "28HyTu"
- }
/funds/screens/get
The /funds/screens/get endpoint allows you to receive ESG Screens data about one or more Funds.
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
Example request
- curl -X POST https://development.ethosesg.com/funds/screens/get \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "symbols": [String],
- "count": 100,
- "offset": 0
- }
- }'
- const response = await client
- . getFundScreens (firm_id, secret , {
- symbols: [String] ,
- count: 100 ,
- offset: 0 ,
- })
- . catch ((err) => {
- // handle error
- })
- const funds = response.funds
- response = client.FundScreens.get(firm_id, secret)
- funds = response['funds']
- # Manipulate the count and offset parameters to paginate
- # funds and retrieve all available data
- while len (funds) < response[' total_funds' ]:
- response = client.FundScreens.get(firm_id, secret,
- offset= len (funds))
- funds.extend(response[ 'funds' ])
- response = @client .fund_screens. get ( @firm_id , @secret )
- # Manipulate the count and offset parameters to paginate
- # funds and retrieve all available data
- response = @client .fund_screens. get ( @firm_id , @secret , count: 250 , offset: 0 )
- total_funds = response[ 'funds' ]
Response fields
Example response
- {
- "funds" : [
- {
- "fund_id" : 553
- "symbol" : "VEGN"
- "cusip" : "26922A 297"
- "isin" : "US26922A2978"
- "name" : "US Vegan Climate ETF"
- "updated_at" : "2022-06-19"
- "screens" : {
- "advertising" : {
- "fail_count" : 2
- "fail_percent" : 0.02
- "revenue_percent" : null
- "updated_at" : "2022-06-19"
- }
- "..." : {
- "fail_count" : 10
- "fail_percent" : 0.11
- "revenue_percent" : null
- "updated_at" : "2022-06-19"
- }
- }
- }
- ],
- "paged_funds" : 1 ,
- "total_funds" : 1 ,
- "request_id" : "28HyTu"
- }
/funds/ratings/get
The /funds/ratings/get endpoint allows you to receive ESG Ratings data about one or more Funds.
Optionally specify the id of a cause you want to retrieve a Rating for. Defaults to returning ratings for all causes on Ethos and all "Impact Personas" of your clients and leads.
An "Impact Persona" is a combination of causes based on what a client or lead selects in their Impact Assessment. It can be a single cause or many causes that are important to a client.
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
Example request
- curl -X POST https://development.ethosesg.com/funds/ratings/get \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "symbols": [String],
- "count": 100,
- "offset": 0
- }
- }'
- const response = await client
- . getFundRatings (firm_id, secret , {
- symbols: [String] ,
- count: 100 ,
- offset: 0 ,
- })
- . catch ((err) => {
- // handle error
- })
- const funds = response.funds
- response = client.FundRatings.get(firm_id, secret)
- funds = response['funds']
- # Manipulate the count and offset parameters to paginate
- # funds and retrieve all available data
- while len (funds) < response[' total_funds' ]:
- response = client.FundRatings.get(firm_id, secret,
- offset= len (funds))
- funds.extend(response[ 'funds' ])
- response = @client .fund_ratings. get ( @firm_id , @secret )
- # Manipulate the count and offset parameters to paginate
- # funds and retrieve all available data
- response = @client .fund_ratings. get ( @firm_id , @secret , count: 250 , offset: 0 )
- total_funds = response[ 'funds' ]
Response fields
Example response
- {
- "funds" : [
- {
- "fund_id" : 2858
- "symbol" : "VEGN"
- "cusip" : "26922A 297"
- "isin" : "US26922A2978"
- "name" : "US Vegan Climate ETF"
- "updated_at" : "2022-06-19"
- "ratings" : [
- {
- "cause" : "Gender equality"
- "cause_id" : "37"
- "updated_at" : "2022-06-19"
- "score" : 88.2
- "rank" : 84
- "percentile" : 0.92
- }
- ]
- }
- ],
- "paged_funds" : 1 ,
- "total_funds" : 1 ,
- "request_id" : "28HyTu"
- }
/funds/metrics/get
The /funds/metrics/get endpoint allows you to receive ESG Metrics data about one or more Funds.
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
Example request
- curl -X POST https://development.ethosesg.com/funds/metrics/get \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "symbols": [String],
- "count": 100,
- "offset": 0
- }
- }'
- const response = await client
- . getFundMetrics (firm_id, secret , {
- symbols: [String] ,
- count: 100 ,
- offset: 0 ,
- })
- . catch ((err) => {
- // handle error
- })
- const funds = response.funds
- response = client.FundMetrics.get(firm_id, secret)
- funds = response['funds']
- # Manipulate the count and offset parameters to paginate
- # funds and retrieve all available data
- while len (funds) < response[' total_funds' ]:
- response = client.FundMetrics.get(firm_id, secret,
- offset= len (funds))
- funds.extend(response[ 'funds' ])
- response = @client .fund_metrics. get ( @firm_id , @secret )
- # Manipulate the count and offset parameters to paginate
- # funds and retrieve all available data
- response = @client .fund_metrics. get ( @firm_id , @secret , count: 250 , offset: 0 )
- total_funds = response[ 'funds' ]
Response fields
Example response
- {
- "funds" : [
- {
- "fund_id" : 2858
- "symbol" : "VEGN"
- "cusip" : "26922A 297"
- "isin" : "US26922A2978"
- "name" : "US Vegan Climate ETF"
- "updated_at" : "2022-06-19"
- "metrics" : [
- {
- "name" : "Advertising fines and violations"
- "metric_id" : "224"
- "description" : "Sum of fines incurred over the past four years from the Federal Trade Commission, related to advertising"
- "link" : "https://www.goodjobsfirst.org/violation-tracker"
- "uom" : "$ fines"
- "updated_at" : "2022-06-19"
- "esg_category" : "social"
- "score_base" : 42100000
- "score_normalized" : 0
- }
- ]
- }
- ],
- "paged_funds" : 1 ,
- "total_funds" : 1 ,
- "request_id" : "28HyTu"
- }
/funds/list
The /funds/list endpoint allows you to receive a list of Funds available on Ethos, with basic identifiers for each Fund.
Funds are returned in alphabetical order by name. No paging is included in the response.
If you would like more detailed information about a fund, use the /funds/get endpoint below.
Request fields
Example request
- curl -X POST https://development.ethosesg.com/funds/list \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- }'
- const response = await client
- . listFunds (firm_id, secret )
- . catch ((err) => {
- // handle error
- })
- const funds = response.funds
- response = client.Funds.list(firm_id, secret)
- funds = response['funds']
- response = @client .funds. list ( @firm_id , @secret )
- total_funds = response[ 'funds' ]
Response fields
Example response
- {
- "funds" : [
- {
- "fund_id" : 553
- "symbol" : "VEGN"
- "cusip" : "26922A 297"
- "isin" : "US26922A2978"
- "name" : "US Vegan Climate ETF"
- "updated_at" : "2022-06-19"
- }
- ],
- "total_funds" : 1 ,
- "request_id" : "28HyTu"
- }
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/list
The /causes/list 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
Example request
- curl -X POST https://development.ethosesg.com/causes/list \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "cause_ids": [Integer]
- }
- }'
- const response = await client
- . listCauses (firm_id, secret , {
- cause_ids: [Integer]
- })
- . catch ((err) => {
- // handle error
- })
- const causes = response.causes
- response = client.Causes.list(firm_id, secret)
- causes = response['causes']
- response = client.Causes.list(firm_id, secret,
- offset= len (causes))
- causes.extend(response[ 'causes' ])
- response = @client .causes. list ( @firm_id , @secret )
- total_companies = response[ 'causes' ]
Response fields
Example response
- {
- "causes" : [
- {
- "cause_id" : 32
- "name" : "Sustainable use of water"
- "description" : "Promote sustainable management of water everywhere"
- "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"
- "keywords" : "sustainable farming, industrial agriculture, sustainability, access to water, water stress"
- }
- ],
- "total_causes" : 1 ,
- "request_id" : "28HyTu"
- }
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/list
The /metrics/list 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
Example request
- curl -X POST https://development.ethosesg.com/metrics/list \
- -H 'Content-Type: application/json' \
- -d '{
- "firm_id": String,
- "secret": String,
- "options": {
- "metric_ids": [Integer],
- "count": 100,
- "offset": 0
- }
- }'
- const response = await client
- . listMetrics (firm_id, secret , {
- metric_ids: [Integer]
- })
- . catch ((err) => {
- // handle error
- })
- const metrics = response.metrics
- response = client.Metrics.list(firm_id, secret)
- metrics = response['metrics']
- # Manipulate the count and offset parameters to paginate
- # metrics and retrieve all available data
- while len (metrics) < response[' total_metrics' ]:
- response = client.Metrics.list(firm_id, secret,
- offset= len (metrics))
- metrics.extend(response[ 'metrics' ])
- response = @client .metrics. list ( @firm_id , @secret )
- # Manipulate the count and offset parameters to paginate
- # metrics and retrieve all available data
- response = @client .metrics. list ( @firm_id , @secret , count: 250 , offset: 0 )
- total_metrics = response[ 'metrics' ]
Response fields
Example response
- {
- "metrics" : [
- {
- "metric_id" : 224
- "name" : "Fines and violations"
- "description" : "Sum of fines and violations incurred from US government agencies over the previous four years"
- "source" : "Violation Tracker"
- "link" : "https://www.goodjobsfirst.org/violation-tracker"
- "uom" : "$ fines"
- "updated_at" : "2021-04-15"
- "esg_category" : "governance"
- "normalization_scope" : "all"
- }
- ],
- "paged_metrics" : 1 ,
- "total_metrics" : 1 ,
- "request_id" : "28HyTu"
- }