Reference documentation for API data structures
Data Schemas
Industry
| Property |
Type |
Required |
Description |
| id |
|
❌ |
|
| name |
|
❌ |
|
| mean_score |
|
❌ |
The mean score for this industry globally. Values from 0 to 1, 0 being the worst and 1 being the best. Users typically represent this as a score between 0 and 100. See calculation methodology at https://ditchcarbon.com/calculation-methodologies/ |
| performances |
|
❌ |
|
OrganizationIdentifier
| Property |
Type |
Required |
Description |
| name | | ✅ | |
| hq_region | | ❌ | ISO two-letter country code of the organization's headquarters. |
| hq_subregion | | ❌ | ISO two-letter code of the organization's headquarters subregion (for example, Ohio would be OH). |
| hq_fuzzy | object | ❌ | If you don't know the ISO two-letter country code of the organization's headquarters, you can provide a fuzzy input. e.g. "United States" or an address like "1600 Amphitheatre Parkway, Mountain View, CA" |
| industry_id | | ❌ | |
| industry_name | | ❌ | |
| website | | ❌ | The organization's website or email address. e.g. https://example.com or user@example.com |
| external_id | | ❌ | |
| is_legal_entity_name | | ❌ | Indicates whether the provided name is the supplier's legal entity name (vs. trading name/brand). |
| duns_number | | ❌ | Data Universal Numbering System (DUNS) number for direct organization matching. |
| lei_number | | ❌ | Legal Entity Identifier (LEI) for direct organization matching. |
| isin_number | | ❌ | International Securities Identification Number (ISIN) for direct organization matching. |
| sp_global_number | | ❌ | S&P Global identifier for direct organization matching. |
Organization
The fields returned depend on your project plan. The schema below describes the full (detailed) response. Summary plan responses return a subset: matching_organization omits names, websites, and tickers; industry_confidence is not included; and sbti and ecovadis objects are included.
| Property |
Type |
Required |
Description |
| id | | ❌ | Unique DitchCarbon identifier for an organization |
| name | | ❌ | Name of the organization |
| hq_region | | ❌ | ISO 3166 two-letter country code for the country in which a business's registered headquarters are located. |
| hq_subregion | | ❌ | ISO 3166-2 two-letter code of the organization's headquarters subregion (for example, Ohio would be OH). |
| industry | Industry | ❌ | |
| website | | ❌ | The organization's website or email address. e.g. https://example.com or user@example.com |
| external_id | | ❌ | External id provided by a customer or a 3rd party provider such as DUNS or ISIN |
| status | | ❌ | The status of the organization's data. All statuses except synced and errored mean the research is still in progress. synced means the research is complete. errored means there was an error during the research. |
| organization_relationship_type | | ❌ | The type of relationship this organization has (e.g., "ultimate parent", "subsidiary") |
| has_relevant_upstream | | ❌ | Whether the organization has disclosed relevant upstream categories in any year |
| matching_organization | | ❌ | |
| performances | | ❌ | |
| sources | | ❌ | An array of sources that DitchCarbon used to create the response. |
| score | | ❌ | DitchCarbon assessed score from 0 to 1, 0 being the worst and 1 being the best. See calculation methodology at https://ditchcarbon.com/calculation-methodologies/ |
| industry_score_percentile | | ❌ | DitchCarbon assessed percentile of the organization's industry score. A value of 80 means the organization is in the 80th percentile. |
| industry_confidence | | ❌ | DitchCarbon confidence rating. Values can be: low, medium or high |
| industry_rank | | ❌ | DitchCarbon assessed rank of the organization's industry's intensity. Values can be: very_high, high, medium, low, very_low, unknown |
| region_rank | | ❌ | DitchCarbon assessed rank of the organization's region. Values can be: very_high, high, medium, low, very_low, unknown |
| related_environmental_report_status | | ❌ | Whether or not the organization currently has any associated environmental reports. Values can be: processing, found, not_found |
| cdp | | ❌ | |
| sbti | | ❌ | |
| un | | ❌ | |
| ecovadis | | ❌ | |
| climate_pledge | | ❌ | |
| document_reduction_targets | | ❌ | Reduction targets automatically extracted from the organization's public documents. |
| sbti_reduction_targets | | ❌ | Reduction targets declared to and validated by the Science Based Targets initiative (SBTi). |
Organization Performance
An organization's performance in a given year. This includes the organization's emissions, revenue, and emission factors. We use this dataset https://simplemaps.com/data/world-cities to help with normalizing regional data.
| Property |
Type |
Required |
Description |
| year | | ❌ | The year that the organization's GHG emissions data refers to. |
| region | | ❌ | ISO 3166 two-letter country code of the organization's headquarters |
| emission_factor | | ❌ | Organization's total reported scope 1 + 2 + 3 GHG emissions divided by the organization's revenue. Measured in kgCo2e/USD. |
| total_upstream_emission_factor | | ❌ | Organization's reported total scope 1 and 2 GHG emissions + scope 3 categories 1-8 divided by organization's revenue. |
| scope_1_and_2_emission_factor | | ❌ | Organization's reported total scope 1 and 2 GHG emissions divided by organization's revenue |
| revenue_currency | | ❌ | ISO three-letter currency code for the organization's revenue |
| has_revenue | | ❌ | Indicates whether the organization has revenue data available for this year |
| revenue | | ❌ | Deprecated – this field is now only available by request. The total amount of money brought in by an organization's operations, measured over a financial year. |
| emissions | | ❌ | |
| production_emission_factors | | ❌ | |
| documents | | ❌ | |
Industry Performance
| Property |
Type |
Required |
Description |
| year |
|
❌ |
|
| region |
|
❌ |
|
| emission_factor |
|
❌ |
|
| ghg_emission_factors |
|
❌ |
All factors in kgCO2e/USD, transformed using GHG protocol data. https://ghgprotocol.org/... |
| source |
|
❌ |
|
Category
| Property |
Type |
Required |
Description |
| id |
|
❌ |
|
| name |
|
❌ |
|
Recommended Actions
| Property |
Type |
Required |
Description |
| recommended_actions |
|
❌ |
|
Reduction Target
| Property |
Type |
Required |
Description |
| id | | ❌ | |
| classification | | ❌ | |
| timeframe | | ❌ | |
| scope | | ❌ | |
| start_year | | ❌ | |
| end_year | | ❌ | |
| overall_reduction_percentage | | ❌ | |
| text | | ❌ | |
| source_url | | ❌ | |
| permanent_mirror_url | | ❌ | |
| page | | ❌ | |
| on_track_two_year | | ❌ | |
| on_track_five_year | | ❌ | |
Emission
DitchCarbon's estimate of CO2e emitted.
| Property |
Type |
Required |
Description |
| kg_co2e |
|
❌ |
|
Server
| Property |
Type |
Required |
Description |
| id | | ❌ | |
| manufacturer_name | | ❌ | |
| model | | ❌ | |
| ram_bytes | | ❌ | In bytes |
| cpu_name | | ❌ | |
| os_name | | ❌ | |
| cpu_count | | ❌ | Number of physical CPUs |
| core_count | | ❌ | Number of physical cores per chip (CPU) |
| thread_count | | ❌ | Number of logical threads across all chips (CPUs) |
| is_virtual | | ❌ | Whether the server is dedicated (exclusively used by the entity) or virtual (shared between the entity and others, such as with Virtual Private Servers on cloud platforms) |
| disk_count | | ❌ | |
.svg)
