Introduction
Welcome to the Carbon Insights Documentation. This is a guide for usage of the Carbon Insights API.
If you have questions or need support, please contact tech@carboninsights.co.
Schema
All API access is over HTTPS, and accessed from https://api.carboninsights.co
. All data is sent and received as JSON. You must include the Content-Type: application/json
header when sending your requests.
Registration & Authentication
curl "https://api.carboninsights.co"
-H "Authorization: Token YOUR_ACCESS_TOKEN"
-H "Content-Type: application/json"
carbIN uses JSON Web Tokens
to control access to the API. In order to send and receive data, you must first register for an account.
After successfully registering, you can request your authorization tokens. You will receive two tokens. Save these, but don't get too attached to them. They expire quickly for security purposes.
Your access token
is a short-lived token that is sent in the header of every request:
Authorization: Token YOUR_ACCESS_TOKEN
Your refresh token
is a longer-lived token that is used to request a new access token when your access token expires.
When your refresh token expires, you will use your account credentials to reauthenticate and request a new set of tokens.
Request Ids
Each API request has an associated request id. You can find this value in the Request-Id
response header. Referencing the request id is helpful when you need to contact us for support regarding a specific request.
Endpoints
Register for an account
Sample Request:
{
"username": "ilovetheplanet",
"password": "Sav3Th3Whal3s",
"first_name": "jeff",
"last_name": "whalen",
"email": "jwhalen@bluebank.com"
}
Sample Response:
{
"message": "Account with username ilovetheplanet created successfully. Use credentials to generate authorization token."
}
POST https://api.carboninsights.co/register
Query Parameters
Required
Parameter | Type | Description |
---|---|---|
username |
string |
The account username. Must be < 50 characters. |
password |
string |
The account password. Must be distinct from username and > 7 characters. |
first_name |
string |
The account holder first name. Must be < 50 characters. |
last_name |
string |
The account holder last name. Must be < 50 characters. |
email |
string |
The account email. Must be a valid email format. |
Request authorization tokens
Sample Request:
{
"username": "ilovetheplanet",
"password": "Sav3Th3Whal3s"
}
Sample Response:
{
"access": <YOUR_ACCESS_TOKEN>,
"refresh": <YOUR_REFRESH_TOKEN>
}
POST https://api.carboninsights.co/token
Query Parameters
Required
Parameter | Type | Description |
---|---|---|
username |
string |
The account username. Must match registered account username. |
password |
string |
The account password. Must match registered account password. |
Request new access token
Sample Request:
{
"refresh": <YOUR_REFRESH_TOKEN>
}
Sample Response:
{
"access": <YOUR_NEW_ACCESS_TOKEN>
}
POST https://api.carboninsights.co/token/refresh
Query Parameters
Required
Parameter | Type | Description |
---|---|---|
refresh |
string |
Your refresh token received when initially requesting your authorization tokens. |
Calculate a carbon score
Sample Request:
{
"user_profile": {
"diet": "typical",
"renewable_energy": 0,
"natural_gas": true,
"shared_account": false,
"zip_code": 19130,
"fuel_grade": "regular"
},
"options": {
"offsets": false,
"recommendations": true,
"CO2e": true,
"land": false,
"water": false,
"category_type": "category",
"country": "United States",
"aggregate": true
},
"transactions": [
{
"date": "01-03-2020",
"amount": 248.76,
"category": "Air Travel",
"description": "Delta",
"original_description": "Delta 866-576-1039 GA"
},
{
"date": "2020-03-03",
"amount": 73.88,
"category": "Hotel",
"description": "Hilton",
"original_description": "Hilton - WESTHEIM HOUSTON"
},
{
"date": "2020-03-03",
"amount": 11.23,
"category": "Rental Car & Taxi",
"description": "Lyft",
"original_description": "LYFT *RIDE SUN 12AM 855-865-9553 CA"
}
]
}
Sample Response:
{
"messages": [],
"details": {
"footprint": {
"category": {
"0": "Air Travel",
"1": "Hotel",
"2": "Rental Car & Taxi"
},
"CO2e Emissions [tonne]": {
"0": 0.23864127230148421,
"1": 0.021415030569301514,
"2": 0.04303300299010413
}
},
"recommendations": {
"category": {
"0": "One Less Flight",
"1": "Driving 10% less"
},
"CO2e Emissions [tonne]": {
"0": 0.23864127230148421,
"1": 0.004303300299010413
}
}
}
}
POST https://api.carboninsights.co/calculateCarbonScore
Query Parameters for transactions
Required
Parameter | Type | Description |
---|---|---|
date |
date string |
The transaction date. Format can be one of: YYYY-MM-DD DD-MM-YYYY |
amount |
decimal |
The transaction amount in USD Note: negative amounts are treated as refunds and have negative emissions associated with them |
category |
string |
The transaction category (category or Merchant Category Code (MCC)) |
description |
string |
Optional The transaction description |
original_description |
string |
Optional The original description of the transaction |
Query Parameters for user_profile
Optional
Parameter | Default | Description |
---|---|---|
diet |
"typical" |
The user's diet. Can be one of: "typical" "vegetarian" "vegan" |
renewable_energy |
0 |
The fraction of the user's eletricity that is renewable |
natural_gas |
false |
Whether the user uses natural gas for heating and cooking |
shared_account |
false |
Whether the user shares the account with at least one other person |
zip_code |
00000 |
The user's zip code |
fuel_grade |
"regular" |
The user's car's fuel grade. Can be one of: "regular" "mid_grade" "premium" "diesel" |
Query Parameters for options
Optional
Parameter | Default | Description |
---|---|---|
offsets |
false |
Whether to return an offset referral link |
recommendations |
false |
Whether to return user recommendedations |
CO2e |
true |
Whether to return CO2e emissions in response |
land |
false |
Whether to return land use in response |
water |
false |
Whether to return water use in response |
category_type |
"category" |
Whether to use a category or Merchant Category Code (MCC) to categorize the transaction. Can be one of: "category" "mcc" |
country |
"United States" |
Country used to determine economic and environmental data. We currently only provide full support for the United States. |
aggregate |
false |
Whether to return an aggregated (by category or Merchant Category Code (MCC)) footprint or by footprints by transaction. |
Transaction Categories
Below is an exhaustive list of the transaction categories we currently support for computing emissions
Recommended Categories
Air Travel Alcohol & Bars Allowance Amusement Arts ATM Fee Baby Supplies Babysitter & Daycare Bank Fee Bonus Books & Supplies Books Cash & ATM Charity Check Child Support Clothing Coffee Shops Credit Card Payment Dentist Doctor Electronics & Software Eyecare Fast Food Federal Tax Finance Charge |
Financial Advisor Furnishings Gift Groceries Gym Hair Health Insurance Hobbies Home Improvement Home Insurance Home Services Home Supplies Hotel Interest Income Investments Kids Activities Late Fee Laundry Lawn & Garden Life Insurance Local Tax Misc Expenses Mortgage & Rent Movies & DVDs Music Newspapers & Magazines |
Paycheck Pet Food & Supplies Pet Grooming Pharmacy Printing Property Tax Reimbursement Rental Car & Taxi Rental Income Renturned Purchase Restaurants Sales Tax Service Fee Shipping Spa & Massage Sporting Goods Sports State Tax Student Loan Toys Trade Commissions Transfer for Cash Spending Tuition Vacation Veterinary |
Additional Categories
Auto & Transport Bills & Utilities Business Services Education Entertainment Fees & Charge Financial |
Food & Dining Gifts & Donations Health & Fitness Home Income Investments Kids Misc Expenses |
Personal Care Pets Shopping Taxes Transfer Travel Uncategorized |
Throttling
The Carbon Insights API currently specifies the following request rate limits for authenticated users:
- Per Second:
30
- Per Minute:
400
- Per Day:
100000
Errors
The Carbon Insights API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your JWT Token is incorrect. |
405 | Method Not Allowed -- You tried to access an endpoint with an invalid method. |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
429 | Too Many Requests -- You've exceeded the request limit for your account. |