Using the API

Full Swagger docs ↗

Consider the information below a "highlight reel," but the best of the best (and all the rest) is available at the link above.

API Testing Notebook ↗

Skip the swagger and get right to the good stuff - here's a Python Notebook with a panoply of use cases to get you building your integration ASAP.

Calculate

The main whole life carbon calculation endpoint.

Calculate Emissions

POST/api/calculate

Header parameters

Body

application/json

Cscalerequest

CscaleRequestCscaleRequest_Flat

Response

200422

Successful Response

Body

application/json

summary*response_LegacySummary

timeseries*Timeseries

emission_totals*any of

response_emission_totalsnull

areas*any of

response_areasnull

structural_carbon_intensities*any of

response_carbon_intensities_structurenull

carbon_intensities*any of

response_carbon_intensitiesnull

structural_quantities*any of

response_structural_quantitiesnull

energy_data*any of

response_energy_datanull

pv_data*any of

response_pv_datanull

ref_data*any of

response_ref_datanull

category_by_stages*any of

response_category_lifecyclestagesnull

regional_data*any of

response_regional_datanull

api_messages*Api Messages

version*Version

Request

JavaScriptCurl

const response = await fetch('/api/calculate', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "location": {
        "latitude": 0,
        "longitude": 0
      },
      "building_form": {
        "above_floor_area": 0
      },
      "structure": "Reinforced Concrete",
      "use_category": "Aquarium"
    }),
});
const data = await response.json();

Response

{
  "summary": {
    "total_area": 0,
    "total_sqf": 0,
    "total_m2": 0,
    "total_planting_area": 0,
    "loseq_planting_area": 0,
    "hiseq_planting_area": 0,
    "benchmark_EUI": 0,
    "onsite_ff_pc": 0,
    "ac_annual": 0,
    "total_array_area": 0,
    "nameplate_capacity": 0,
    "pv_pc_load": 0,
    "av_seq": 0,
    "ref_charge": 0,
    "em_env": 0,
    "em_syst": 0,
    "em_site": 0,
    "em_struct": 0,
    "em_constr": 0,
    "em_tfo": 0,
    "av_store": 0,
    "av_pv": 0,
    "av_biogenic": 0,
    "av_site": 0,
    "op_ref": 0,
    "op_ff": 0,
    "op_elec": 0,
    "op_total": 0,
    "em_total": 0,
    "net_total": 0,
    "av_total": 0,
    "kgCO2e_sf": 0,
    "kgCO2e_m2": 0,
    "target_EUI": "text"
  },
  "timeseries": [
    {
      "net_cumul": 0,
      "av_cumul": 0,
      "em_cumul": 0,
      "op_cumul": 0,
      "em_struct": 0,
      "em_clad": 0,
      "em_glaz": 0,
      "em_roof": 0,
      "em_tfo": 0,
      "em_mep": 0,
      "op_ref": 0,
      "em_pv": 0,
      "op_foss": 0,
      "op_elec": 0,
      "av_pv": 0,
      "av_biogenic": 0,
      "av_site": 0,
      "em_constr": 0,
      "av_store": 0,
      "em_hardsc": 0,
      "em_green": 0,
      "em_maint": 0
    }
  ],
  "emission_totals": {
    "em_env": 0,
    "em_syst": 0,
    "em_site": 0,
    "em_struct": 0,
    "em_constr": 0,
    "em_tfo": 0,
    "av_store": 0,
    "av_pv": 0,
    "av_biogenic": 0,
    "av_site": 0,
    "op_ref": 0,
    "op_ff": 0,
    "op_elec": 0,
    "op_total": 0,
    "em_total": 0,
    "net_total": 0,
    "av_total": 0
  },
  "areas": {
    "total_area": 0,
    "building_footprint": 0,
    "roof_area": 0,
    "cladding_area": 0,
    "glazing_area": 0,
    "fitout_area": 0,
    "conditioned_area": 0,
    "total_pv_array_area": 0,
    "site_area": 0,
    "hardscape_area": 0,
    "total_planting_area": 0,
    "loseq_planting_area": 0,
    "hiseq_planting_area": 0,
    "plantedroof_area": 0
  },
  "structural_carbon_intensities": {
    "Conc3_4kPSI": 0,
    "Conc5_6kPSI": 0,
    "Conc7_10kPSI": 0,
    "ReinforcingBar": 0,
    "SteelStruct": 0,
    "SteelDeck": 0,
    "WoodLumber": 0,
    "WoodPly": 0,
    "WoodMassTimber": 0
  },
  "carbon_intensities": {
    "interior_fitout": 0,
    "cladding": 0,
    "glazing": 0,
    "roofing": 0,
    "mep": 0,
    "hardscape": 0,
    "ref_GWP": 0
  },
  "structural_quantities": {
    "SMQi": 0,
    "concrete": 0,
    "reinforcing": 0,
    "steel": 0,
    "wood": 0
  },
  "energy_data": {
    "benchmark_EUI": 0,
    "onsite_ff_pc": 0,
    "target_EUI": "text"
  },
  "pv_data": {
    "pv_pc_load": 0,
    "ac_annual": 0,
    "nameplate_capacity": 0,
    "total_pv_array_area": 0
  },
  "ref_data": {
    "ref_GWP": 0,
    "ref_charge": 0,
    "ref_ann_leakage": 0,
    "ref_eol_leakage": 0
  },
  "category_by_stages": {
    "structure": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "interior_fitout": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "envelope": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "mep": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "cladding": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "glazing": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "roofing": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "site": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "ref": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "operational_energy": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    },
    "hardscape": {
      "A1_3": 0,
      "A4_5": 0,
      "B1": 0,
      "B2_5": 0,
      "B6": 0,
      "C1_4": 0,
      "D": 0
    }
  },
  "regional_data": {
    "CDD": 0,
    "HDD": 0,
    "region": "text"
  },
  "api_messages": [],
  "version": "text"
}

Token Data

Get data on your auth token, such as how many calls you've made to date and in the last tracking period.

Return Token Summary

GET/api/tokens/token-data

Header parameters

Body

application/json

token*Token

Response

200422

Successful Response

Body

application/json

thismonth*Thismonth

thisyear*Thisyear

requeststhismonth*Requeststhismonth

requeststhisyear*Requeststhisyear

lastmonth*Lastmonth

yearlastmonth*Yearlastmonth

lastyear*Lastyear

requestslastmonth*Requestslastmonth

requestslastyear*Requestslastyear

expires*Expires

Request

JavaScriptCurl

const response = await fetch('/api/tokens/token-data', {
    method: 'GET',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "token": "text"
    }),
});
const data = await response.json();

Response

{
  "thismonth": "text",
  "thisyear": "text",
  "lastmonth": "text",
  "yearlastmonth": "text",
  "lastyear": "text",
  "expires": "text"
}

Payload

Parse your partial payload through the ingress schema. This endpoint is here to help troubleshoot errors related to formatting or schema parsing.

Return Payload

POST/api/payload

Header parameters

Body

application/json

Cscalerequest

CscaleRequest_FlatCscaleRequest

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('/api/payload', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "primary_structural_system": "Reinforced Concrete",
      "primary_use": "Aquarium",
      "location": {
        "latitude": 0,
        "longitude": 0
      },
      "above_floor_sqf": 0
    }),
});
const data = await response.json();

Carbon Intensities

Documentation of our Carbon Intensities endpoint is available in this documentation under reference data.