Flowcarbon Docs
Search…
⌃K

CO2 Calculator

CO2 Calculator API

Summary

The API can be used to estimate the annual carbon emissions footprint of a single person by taking different emission-generating areas of living into account. It is organized around REST, uses standard HTTP response codes, and returns JSON-encoded responses.

Base URL

https://backend.flowcaboom.com/api/v1/co2-calculator

Overview

URL
method
description
/ping
GET
for monitoring purposes
/countries
GET
get a list of all supported countries
/config
GET
get the default measurement units for a country
/footprint
GET
get the average carbon footprint of a person living in a country
/flight
GET
get the carbon emissions produced by flight behavior
/diet
GET
get the average carbon footprint of a diet
/car
GET
get the carbon emissions produced by distance driven by car or rail usage
/clothes
GET
get the carbon emissions produced by shopping behavior
/energy
GET
get the carbon emissions produced by electricity and heating
No authentication is required.

Errors

The API responses with conventional HTTP codes to indicate success or failure of a request. In general:
  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that failed given the provided information. The error is briefly explained.
  • Codes in the 5xx range indicate a server error.

HTTP status codes

code
meaning
description
200
OK
Everything worked as expected.
400
Bad Request
The request was unacceptable, often due to a wrong or missing parameter.
401
Unauthorized
No valid API key provided.
402
Request Failed
The parameters were valid but the request failed.
403
Forbidden
The API key doesn't have permissions to perform the request.
404
Not Found
The requested resource doesn't exist often because of not accepted path parameters.
429
Too Many Requests
Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504
Server Errors
Something went wrong on our side. We are sorry.

Ping

Endpoint: /ping

Successful response

{
"message": "pong"
}

Countries list

Endpoint: /countries

Returns

If the request succeeded, a list of all supported countries and their basic information are returned. Otherwise, this call returns an error.
Fields
field
data type
description
countries
Array of Dictionaries
array of all supported countries and their information, alphabetically ordered by their names
country_code
String
the ISO 3166-1 alpha-3 country code
country_name
String
the name of the country
sub_region
String
the sub region of the country
region
String
the region of the country
measurement_system
String
the most widely used measurement system of the country

Example

Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/countries
Successful response
Content (click to expand)

Measurement units

Endpoint: /config

Parameters

parameter
data type
possible values
optional
description
country_code
String
e.g. DEU, VNM or any other supported alpha-3 country code
no
the ISO 3166-1 alpha-3 code of the country

Returns

If the request succeeded, the measurement units and basic information for the given country are returned. Otherwise, this call returns an error.
Fields
field
data type
description
country_code
String
the ISO 3166-1 alpha-3 country code
country_name
String
the name of the country
sub_region
String
the sub region of the country
region
String
the region of the country
measurement_system
String
the most widely used measurement system of the country; either metric or imperial
t_co2
Float
the average annual carbon emissions of a person living in the given country (measured either in long tons (lt) or metric tons (mt) according to the country's measurement system)
ton
String
the unit of the t_co2 field; either lt (long ton) or mt (metric ton)
distance
String
the unit of the distance ranges for driving a car; either km or miles
drive_ranges
Array of Integers
suggestion for three distance ranges for driving a car, e.g. 0-6000, 6000-12000 or 12000-30000 miles per year
home_size
String
the unit for the home size; either ft² or

Examples

Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/config?country_code=USA
Successful response
{
"country_code":"USA",
"country_name":"United States",
"sub_region":"Northern America",
"region":"Americas",
"measurement_system":"imperial",
"t_co2":14.013139266,
"ton":"lt",
"distance":"miles",
"drive_ranges":[
6000,
12000,
30000
],
"home_size":"ft²"
}

CO2

Endpoint: /footprint

Parameters

parameter
data type
possible values
optional
description
country_code
String
e.g. DEU, VNM or any other supported alpha-3 country code
no
the ISO 3166-1 alpha-3 code of the country
measurement_system
String
imperial, metric
yes
the measurement system the t_co2 value should be returned in (lt or mt); default value is metric

Returns

If the request succeeded, the average carbon footprint of a person living in the given country is returned according to the specified measurement system. Otherwise, this call returns an error.
Fields
field
data type
description
t_co2
Float
the average annual carbon emissions of a person living in the given country
ton
String
the measurement unit of the t_co2 value; either lt (long ton) or mt (metric ton)

Examples

Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/footprint?country_code=DEU
Successful response
{
"t_co2":7.69,
"ton":"mt"
}
Please notice that the value is returned in metric tons (mt) as measurement_system is set to metric by default.
Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/footprint?country_code=LBR&measurement_system=imperial
Successful response
{
"t_co2":0.19684140000000003,
"ton":"lt"
}
Please notice that the value is returned in long tons (lt) as measurement_system is set to imperial.

Flight

Endpoint: /flight

Parameters

parameter
data type
possible values
optional
description
country_code
String
e.g. DEU, VNM or any other supported alpha-3 country code
no
the ISO 3166-1 alpha-3 code of the country
frequency
String
often (4 round trip short-, 2 medium, 1 long-haul flights), sometimes (2 round trip short-, 1 medium-haul flights), rare (1 round trip short-haul flight)
no
how often a person flies in a year
measurement_system
String
imperial, metric
yes
the measurement system the t_co2 value should be returned in (lt or mt); default value is metric

Returns

If the request succeeded, the calculated carbon emissions based on the flight behaviour of a person living in the given country is returned according to the specified measurement system. Otherwise, this call returns an error.
Fields
field
data type
description
t_co2
Float
the calculated amount of carbon emissions produced by the flights a person takes in a year
ton
String
the measurement unit of the t_co2 value; either lt (long ton) or mt (metric ton)

Examples

Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/flight?country_code=LUX&frequency=often
Successful response
{
"t_co2":6.235822125827555,
"ton":"mt"
}

Diet

Endpoint: /diet

Parameters

parameter
data type
possible values
optional
description
country_code
String
e.g. DEU, VNM or any other supported alpha-3 country code
no
the ISO 3166-1 alpha-3 code of the country
diet_form
String
everything, pescetarian, vegetarian, vegan
no
how often a person flies in a year
measurement_system
String
imperial, metric
yes
the measurement system the t_co2 value should be returned in (lt or mt); default value is metric

Returns

If the request succeeded, the estimated carbon emissions based on the dietary of a person living in the given country are returned according to the specified measurement system. Otherwise, this call returns an error.
Fields
field
data type
description
t_co2
Float
the estimated amount of carbon emissions produced by the dietary of a person in a year
ton
String
the measurement unit of the t_co2 value; either lt (long ton) or mt (metric ton)

Examples

Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/diet?country_code=IND&diet_form=vegan
Successful response
{
"t_co2":0.21884388933927548,
"ton":"mt"
}

Car

Endpoint: /car

Parameters

parameter
data type
possible values
optional
description
country_code
String
e.g. DEU, VNM or any other supported alpha-3 country code
no
the ISO 3166-1 alpha-3 code of the country
distance
Integer
any integer number
no
the distance traveled in a year using the unit of measurement configured for the given country; in case distance is set to 0, the carbon emissions amount for average rail usage for the given country is returned
measurement_system
String
imperial, metric
yes
the measurement system the t_co2 value should be returned in (lt or mt); default value is metric

Returns

If the request succeeded, the estimated carbon emissions based on the annual driving behaviour of a person living in the given country are returned in according to the specified measurement system. If the person does not drive a car, the carbon emissions amount for average annual rail usage for the given country is returned. Otherwise, this call returns an error.
Fields
field
data type
description
t_co2
Float
the estimated amount of carbon emissions produced by driving a car or the rail usage of a person in a year
ton
String
the measurement unit of the t_co2 value; either lt (long ton) or mt (metric ton)

Examples

Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/car?country_code=CRI&distance=6000
Please notice that distance is expected to be given in kilometers as measurement_system is set to metric by default.
Successful response
{
"t_co2":1.08,
"ton":"mt"
}

Clothes

Endpoint: /clothes

Returns

If the request succeeded, the estimated carbon emissions based on the shopping behaviour of a person living in the given country are returned according to the specified measurement system. Otherwise, this call returns an error.
Fields
field
data type
description
t_co2
Float
the estimated amount of carbon emissions produced by the annual shopping behaviour of a person
ton
String
the measurement unit of the t_co2 value; either lt (long ton) or mt (metric ton)

Parameters

parameter
data type
possible values
optional
description
country_code
String
e.g. DEU, VNM or any other supported alpha-3 country code
no
the ISO 3166-1 alpha-3 code of the country
amount
String
little (3/4 the average), average, much (twice the average)
no
how much clothes does a person approx. buy in a year
measurement_system
String
imperial, metric
yes
the measurement system the t_co2 value should be returned in (lt or mt); default value is metric

Examples

Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/clothes?country_code=CHE&amount=much
Successful response
{
"t_co2":0.9534339177339287,
"ton":"mt"
}

Energy

Endpoint: /energy

Parameters

parameter
data type
possible values
optional
description
country_code
String
e.g. DEU, VNM or any other supported alpha-3 country code
no
the ISO 3166-1 alpha-3 code of the country
household_size
Integer
1, 2, 3 (or any other integer number if home_size is specified)
no
the number of household members / how many people live in this household
energy_type
String
green, conventional
no
the type of energy is being used
home_size
Integer
any integer number
yes if household_size < 4, otherwise no
the size of the home (should be given in except measurement_system is set to imperial, then ft²)
measurement_system
String
imperial, metric
yes
the measurement system the t_co2 and home_size field values should be returned in (lt or mt); default value is metric

Returns

If the request succeeded, the estimated carbon emissions produced by electricity and heating of the home the person lives in are returned according to the given energy type, the country and the specified measurement system. Otherwise, this call returns an error.
Fields
field
data type
description
t_co2
Float
the estimated amount of carbon emissions produced by energy usage of a person in a year
ton
String
the measurement unit of the t_co2 value; either lt (long ton) or mt (metric ton)

Examples

Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/energy?country_code=TJK&household_size=1&energy_type=conventional
Please notice that home_size is expected to be given in as measurement_system is set to metric by default.
Successful response
{
"t_co2":0.5122168449673026,
"ton":"mt"
}
Request
GET https://backend.flowcaboom.com/api/v1/co2-calculator/energy?country_code=USA&household_size=6&home_size=1600&energy_type=green&measurement_system=imperial
Please notice that home_size is expected to be given in ft² as measurement_system is set to imperial.
Successful response
{
"t_co2":0.9703105933738454,
"ton":"lt"
}