/footprint - GET

This endpoint calculates the carbon footprint based on available fuel usage or distance travelled information.

Query parameters:

activity (required) - This parameter can contain the fuel consumption of the vehicle in US gallons OR the distance travelled in miles. What this parameter represents depends on the information you have available.

It is recommended to make this parameter the fuel consumption in gallons if you have access to this information and want to be more specific. Note that this number is not allowed to be 0(or else an error is returned).

activityType (required) - This refers to the type of activity value chosen above. Below are the valid values for this parameter.

• miles
• fuel

fuelType (optional) - Please set this If your activity and activityType represents fuel consumption in gallons. This represents the type of fuel the vehicle is using.

• motorGasoline → also known as petrol
• diesel
• aviationGasoline
• jetFuel

mode (optional) - This parameter refers to the mode of transportation. Below are the valid values for this parameter.

NOTE*: If your activity and activityType represents the miles travelled, you will need to set this property.

• dieselCar
• petrolCar
• anyCar
• taxi
• economyFlight
• businessFlight
• firstclassFlight
• anyFlight
• motorbike
• bus
• transitRail

country (required) - This refers to the country of the activity. This is represented using the appropriate ISO 3166-1 alpha-3 code for the location. NOTE: the value needs to be lower case.

You can find the country codes here: https://en.wikipedia.org/wiki/ISO_3166-1

For now the API supports specific data for the following:

• usa → United States

• gbr → United Kingdom

  If the country you are requesting data for is not part of those above. Use the following in the country parameter.

• def → Other countries/default values

This causes the API to use the default values set by the IPCC & DEFRA UK for estimating carbon emissions.

appTkn (optional) - This refers to the token given when you sign up on the site. This allows you to send 100 requests per minute. As opposed to being capped at 20 per minute.

RESPONSE FOR /footprint

Object Properties:

• carbonFootprint → This property contains the carbon footprint in kilograms

{
               "carbonFootprint": 222,
}

EXAMPLES FOR /footprint

EXAMPLE 1 (Miles)

A request to get the footprint of a taxi journey in a country other than us & uk.

https://api.triptocarbon.xyz/v1/footprint?activity=10&activityType=miles&country=def&mode=taxi

Expected response:

{
               "carbonFootprint": "2.30",
}

EXAMPLE 2 (Fuel usage):

A request to get the footprint of a petrol car trip in usa where the fuel consumption is known.

https://api.triptocarbon.xyz/v1/footprint?activity=100&activityType=fuel&country=usa&fuelType=motorGasoline

Expected response:

{
               "carbonFootprint": "878.00", 
}

Errors

Errors encountered have a standard structure. When an error has occurred the returned response will contain the "errorMessage" property.

{
               "errorMessage": "Some reason for the error",
								
}

At times requests fail due to invalid query parameter values, if this occurs the error response will contain a property called "invalidParameters" which is an object contains the parameters with invalid values. The country parameter was not supplied and the mode does not exist.

{
               "errorMessage": "Some reason for the error",
								"invalidParameters": { 
										"country": undefined
										"mode": "plane" 
								 }
}