skip to main content

API

We here at International Carbon Register provide a free to use API to help get the Carbon Data you need.

Navigation

Overview

International Carbon Register provides a free-to-use API to automatically retrieve a companies' Carbon Data.

Company Request

GET/api/company/{company_id}/

Retrieve Carbon Data for all years for Company.

Response:

{
    "company_id": "ICR00001",
    "company_name": "Example Company",
    "company_no": 123456789,
    "carbon_data": [
      {
        "year": 2022,
        "emissions": {
          "scope_1": 1001,
          "scope_2": 1001,
          "scope_3": 1001
        },
        "turnover": {
          "currency": "GBP",
          "value": 123456,
          "conversion": {
            "value": 123456,
            "conversion_rate": 1,
            "conversion_timestamp": 1637256377
          }
        }
      },
      {
        "year": 2021,
        "emissions": {
          "scope_1": 100,
          "scope_2": 153,
          "scope_3": 240
        },
        "turnover": {
          "currency": "USD",
          "value": 314100,
          "conversion": {
            "value": 314100,
            "conversion_rate": 1,
            "conversion_timestamp": 1636984951
          }
        }
      }
    ]
  }
Variable Requirement Example Description
company_key required {company_id} A unique key to access the companies carbon data. Only companies have authority to give this key out.

Search Request

GET/api/search/?pattern={search_string}

Search for companies that match the "string" you supply. Filters, Sorting will not affect search results.

Response:

{
    "error": false,
    "code": 200,
    "results": [
      {
        "company_id": "ICR00001",
        "company_name": "Company Name",
        "company_number": "Company Number"
      }
    ]
  }
Variable Requirement Example Description
search_string required Test Company A "string" to find companies.

Filters

Filter by Year

GET/api/company/{company_id}/?year={years}

Retrieve a specific year by passing the year you want as a GET parameter. The year MUST be in YYYY format. Multiple years can be added at once by separating the years with commas.

If no data is found for the year the carbon data array will be empty.

Response:

{
  "company": "Example Company",
  "company_no": 123456789,
  "carbon_data": [
    {
      "year": 2022,
      "emissions": {
        "scope_1": 1001,
        "scope_2": 1001,
        "scope_3": 1001
      },
      "turnover": {
        "currency": "GBP",
        "value": 123456,
        "conversion": {
          "value": 123456,
          "conversion_rate": 1,
          "conversion_timestamp": 1637256377
        }
      }
    }
  ]
}
Variable Requirement Example Description
company_key required {company_id} A unique key to access the companies carbon data. Only companies have authority to give this key out.
years optional 2020 or 2020,2019,2018 The year which data is to be returned. Multiple years can be supplied by separating the years with commas.

Sorting

Sort by Year

GET/api/company/{company_id}/?order={order}

Order the results by year. Either by ascending or descending. Can order filtered years.

Response:

{
  "company": "Example Company",
  "company_no": 123456789,
  "carbon_data": [
    {
      "year": 2021,
      "emissions": {
        "scope_1": 100,
        "scope_2": 153,
        "scope_3": 240
      },
      "turnover": {
        "currency": "USD",
        "value": 314100,
        "conversion": {
          "value": 314100,
          "conversion_rate": 1,
          "conversion_timestamp": 1636984951
        }
      }
    },
    {
      "year": 2022,
      "emissions": {
        "scope_1": 1001,
        "scope_2": 1001,
        "scope_3": 1001
      },
      "turnover": {
        "currency": "GBP",
        "value": 123456,
        "conversion": {
          "value": 123456,
          "conversion_rate": 1,
          "conversion_timestamp": 1637256377
        }
      }
    }
  ]
}
Variable Requirement Example Description
company_key required {company_id} A unique key to access the companies carbon data. Only companies have authority to give this key out.
order optional ASC or DESC Order the results by year.

Limits

Each company has a set amount of credit. Each successful call to the API will result in a credit being used up. If the company no longer has credits, you will receive a 503 Error.

Credits are refreshed each day.

Errors

If an error occurs with retrieving a companies carbon data, the company data will be returned but carbon data will be empty.

In the case of an error, a JSON encoded array is returned with an error message.

Example:

{
  "error": true,
  "code": 400,
  "message": "Invalid Request"
}
Error Code Description Action
400 Invalid Request Please double check the URL your are requesting.
403 Failed to find company Double check the Company Key provided is correct.
503 No API Credits available The company run out of API Credits. Try again the next day when the credits are reset.

International Carbon Register helped our company and the environment

John Doe , CEO at Green Company LLC

Membership

What's included in your membership?

  • Unlimited access to your carbon emission data
  • Monthly invoices to keep track of your account
  • Easy to use membership management
£10 / month
Get Started

Trusted international partners